python-backlog 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

backlog/_http.py

@@ -0,0 +1,204 @@
+# coding: utf-8
+"""
+Minimal HTTP client built on the standard library (urllib).
+
+python-backlog has no runtime dependencies. This module implements the small subset of HTTP
+features the Backlog API needs: query strings, form-encoded and multipart bodies, custom
+headers, timeouts and JSON responses.
+"""
+
+import json
+import os
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from email.message import Message
+
+
+class Response(object):
+    """
+    HTTP response returned by :meth:`backlog.base.BaseAPI.invoke_method`.
+
+    It provides the attributes of ``requests.Response`` that are commonly used with this library.
+    """
+
+    def __init__(self, status_code, headers, content, url):
+        self.status_code = status_code
+        self.headers = headers
+        self.content = content
+        self.url = url
+
+    @property
+    def ok(self):
+        return 200 <= self.status_code < 400
+
+    @property
+    def encoding(self):
+        _message = Message()
+        _message["Content-Type"] = self.headers.get("Content-Type", "")
+        return _message.get_content_charset() or "utf-8"
+
+    @property
+    def text(self):
+        return self.content.decode(self.encoding, errors="replace")
+
+    def json(self):
+        return json.loads(self.text)
+
+    def __repr__(self):
+        return "<Response [{}]>".format(self.status_code)
+
+
+def _items(params):
+    """
+    Flatten a parameter dict into (key, value) string pairs, like requests does:
+    None values are skipped and list/tuple values become repeated keys.
+    """
+    pairs = []
+    for key, value in (params or {}).items():
+        values = value if isinstance(value, (list, tuple)) else [value]
+        for v in values:
+            if v is None:
+                continue
+            if isinstance(v, bytes):
+                v = v.decode()
+            pairs.append((str(key), str(v)))
+    return pairs
+
+
+def encode_query(url, params):
+    pairs = _items(params)
+    if not pairs:
+        return url
+    return url + ("&" if "?" in url else "?") + urllib.parse.urlencode(pairs)
+
+
+def encode_form(data):
+    pairs = _items(data)
+    if not pairs:
+        return None
+    return urllib.parse.urlencode(pairs).encode()
+
+
+def encode_multipart(data, files):
+    """
+    Encode form fields and files as multipart/form-data.
+
+    :param files: dict of field name to ``(filename, fileobj_or_bytes[, content_type])``
+    :return: (body, content_type)
+    """
+    boundary = uuid.uuid4().hex
+    lines = []
+    for key, value in _items(data):
+        lines += [
+            "--{}".format(boundary).encode(),
+            'Content-Disposition: form-data; name="{}"'.format(_quote(key)).encode(),
+            b"",
+            value.encode(),
+        ]
+    for key, spec in files.items():
+        filename, content = spec[0], spec[1]
+        content_type = (spec[2] if len(spec) > 2 else None) or "application/octet-stream"
+        if hasattr(content, "read"):
+            content = content.read()
+        if isinstance(content, str):
+            content = content.encode()
+        lines += [
+            "--{}".format(boundary).encode(),
+            'Content-Disposition: form-data; name="{}"; filename="{}"'.format(_quote(key), _quote(filename)).encode(),
+            "Content-Type: {}".format(content_type).encode(),
+            b"",
+            content,
+        ]
+    lines += ["--{}--".format(boundary).encode(), b""]
+    return b"\r\n".join(lines), "multipart/form-data; boundary={}".format(boundary)
+
+
+def _quote(value):
+    return str(value).replace("\\", "\\\\").replace('"', '\\"').replace("\r", "").replace("\n", "")
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """
+    Do not follow redirects. The Backlog API does not redirect, and following a redirect would
+    forward the API key header to wherever the redirect points.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def _ssl_context():
+    """
+    Build the TLS context.
+
+    The system trust store is used as the standard library does (it also honors SSL_CERT_FILE and
+    SSL_CERT_DIR, so CAs added to the OS, such as those of corporate proxies, keep working).
+    CA bundles that requests users may rely on are added on top of it:
+
+    - the file in REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE, if set;
+    - certifi's bundle, if certifi is installed (helps on systems without a usable trust store).
+    """
+    context = ssl.create_default_context()
+    for name in ("REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE"):
+        path = os.environ.get(name)
+        if not path:
+            continue
+        if os.path.isdir(path):
+            context.load_verify_locations(capath=path)
+        else:
+            context.load_verify_locations(cafile=path)
+    try:
+        import certifi
+    except ImportError:
+        pass
+    else:
+        context.load_verify_locations(cafile=certifi.where())
+    return context
+
+
+_opener = None
+
+
+def _get_opener():
+    global _opener
+    if _opener is None:
+        _opener = urllib.request.build_opener(
+            urllib.request.HTTPSHandler(context=_ssl_context()),
+            _NoRedirectHandler(),
+        )
+    return _opener
+
+
+def _open(req, timeout):
+    """
+    Send the request. Returns (status, headers, body, url) for every HTTP status code.
+    """
+    try:
+        with _get_opener().open(req, timeout=timeout) as resp:
+            return resp.status, resp.headers, resp.read(), resp.url
+    except urllib.error.HTTPError as e:
+        with e:
+            return e.code, e.headers, e.read(), e.url
+
+
+def request(method, url, params=None, data=None, headers=None, files=None, timeout=None):
+    """
+    Send an HTTP request and return a :class:`Response`.
+
+    Network errors raise ``OSError`` subclasses (``urllib.error.URLError``, ``TimeoutError``, ...).
+    """
+    _headers = dict(headers or {})
+    body = None
+    if files:
+        body, _headers["Content-Type"] = encode_multipart(data, files)
+    elif method.upper() != "GET":
+        body = encode_form(data)
+        if body is not None:
+            _headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+    req = urllib.request.Request(encode_query(url, params), data=body, headers=_headers, method=method.upper())
+    status, response_headers, content, response_url = _open(req, timeout)
+    return Response(status, response_headers, content, response_url)

backlog/base.py

@@ -1,7 +1,8 @@
 # coding: utf-8
 
 import re
-import requests
+from backlog import _http
+from backlog._http import Response  # noqa: F401  (re-exported for type references)
 from backlog.wiki import Wiki
 from backlog.attachment import Attachment
 from backlog.project import Project
@@ -25,6 +26,18 @@ class BacklogError(Exception):
     pass
 
 
+class BacklogConnectionError(BacklogError):
+    """
+    Raised when the request could not be sent or no response was received
+    (DNS failure, refused connection, TLS error, timeout, ...).
+    """
+    pass
+
+
+# Keyword arguments accepted by invoke_method() in addition to its named parameters.
+_SUPPORTED_KWARGS = frozenset(["timeout", "files"])
+
+
 class BaseAPI(object):
     def __init__(self, space, api_key=None, timeout=DEFAULT_TIMEOUT):
         """
@@ -39,11 +52,10 @@ class BaseAPI(object):
         self.api_key = api_key
         self.timeout = timeout
         self.base_url = BACKLOG_BASE_URL.format(space=space) + BACKLOG_URI_PREFIX
-        self.api = None
         self._build_api()
 
     def _build_api(self):
-        self.api = None
+        pass
 
     def _build_headers(self, headers=None):
         """
@@ -58,16 +70,24 @@ class BaseAPI(object):
 
     def invoke_method(self, method, uri, query_param=None, request_param=None, headers=None, **kwargs):
         """
-        Delegate requests to get/post/delete method.
-        Each method implements by any http client, default client is requests.
+        Delegate requests to get/post/delete/patch method.
 
-        :param method: HTTP Method. supports GET/POST/DELETE
+        :param method: HTTP Method. supports GET/POST/DELETE/PATCH
         :param uri: API Endpoint. 'uri' expects a URI excluded '/api/v2/' prefix
         :param query_param: dict of URL parameter. this will be url-encoded string
         :param request_param: dict of body parameter. this will use when invoke post request
         :param headers: HTTP Header dict. Authentication headers are added automatically.
-        :return: http response object
+        :param kwargs: ``timeout`` (seconds, overrides the client default) and ``files``
+            (dict of field name to ``(filename, fileobj_or_bytes[, content_type])``).
+        :return: :class:`backlog._http.Response`
         """
+        unsupported = set(kwargs) - _SUPPORTED_KWARGS
+        if unsupported:
+            raise TypeError(
+                "Unsupported keyword argument(s): {}. Since 0.9.0 python-backlog no longer uses requests, "
+                "so requests-specific options are not available.".format(", ".join(sorted(unsupported)))
+            )
+
         # Copy the arguments so that neither the caller's dicts nor any shared state are mutated.
         query_param = dict(query_param or {})
         request_param = dict(request_param or {})
@@ -116,11 +136,9 @@ class BaseAPI(object):
 
 class BacklogAPI(BaseAPI):
     """
-    Using 'requests'
+    Backlog API client using the standard library HTTP client.
     """
     def _build_api(self):
-        self.api = None
-
         self.wiki = Wiki(self)
         self.attachment = Attachment(self)
         self.project = Project(self)
@@ -131,32 +149,36 @@ class BacklogAPI(BaseAPI):
         self.custom_field = CustomField(self)
 
     @staticmethod
-    def _raise_for_status(resp, ok):
-        if ok(resp.status_code):
+    def _raise_for_status(resp):
+        if resp.status_code // 100 == 2:
             return resp
         raise BacklogError("Http response {status}: {message}".format(status=resp.status_code, message=resp.text))
 
+    def _send(self, method, uri, query_param, request_param, headers, timeout=None, files=None):
+        try:
+            resp = _http.request(
+                method,
+                self.base_url + uri,
+                params=query_param,
+                data=request_param,
+                headers=headers,
+                files=files,
+                timeout=timeout,
+            )
+        except OSError as e:
+            raise BacklogConnectionError(
+                "Failed to send {method} request to {url}: {error}".format(method=method.upper(), url=self.base_url + uri, error=e)
+            ) from e
+        return self._raise_for_status(resp)
+
     def get(self, method, uri, query_param, request_param, headers, **kwargs):
-        _url = self.base_url + uri
-        resp = requests.get(_url, params=query_param, headers=headers, **kwargs)
-        return self._raise_for_status(resp, lambda code: code // 100 == 2)
+        return self._send("GET", uri, query_param, None, headers, **kwargs)
 
     def post(self, method, uri, query_param, request_param, headers, **kwargs):
-        _url = self.base_url + uri
-        resp = requests.post(_url, params=query_param, data=request_param, headers=headers, **kwargs)
-        return self._raise_for_status(resp, lambda code: code // 100 == 2)
+        return self._send("POST", uri, query_param, request_param, headers, **kwargs)
 
     def delete(self, method, uri, query_param, request_param, headers, **kwargs):
-        _url = self.base_url + uri
-        resp = requests.delete(_url, params=query_param, data=request_param, headers=headers, **kwargs)
-        return self._raise_for_status(resp, lambda code: code // 100 == 2)
+        return self._send("DELETE", uri, query_param, request_param, headers, **kwargs)
 
     def patch(self, method, uri, query_param, request_param, headers, **kwargs):
-        _url = self.base_url + uri
-        resp = requests.patch(_url, params=query_param, data=request_param, headers=headers, **kwargs)
-        return self._raise_for_status(resp, lambda code: code // 100 == 2)
-
-
-class BacklogObject(object):
-    def __init__(self, api):
-        self.api = api
+        return self._send("PATCH", uri, query_param, request_param, headers, **kwargs)

backlog/project.py

@@ -1,4 +1,6 @@
 # coding: utf-8
+
+import warnings
 from typing import TypedDict, Literal, Optional, NewType
 
 
@@ -346,6 +348,11 @@ class Project(object):
         :param projectIdOrKey:
         :return:
         """
+        warnings.warn(
+            "Project.list_categories() is deprecated and will be removed in a future release; use BacklogAPI.category.list() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         _uri = "projects/{project_id_or_key}/categories".format(
             project_id_or_key=projectIdOrKey,
         )
@@ -363,6 +370,11 @@ class Project(object):
         :param name: (str) Category name
         :return:
         """
+        warnings.warn(
+            "Project.add_category() is deprecated and will be removed in a future release; use BacklogAPI.category.add() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         _uri = "projects/{project_id_or_key}/categories".format(
             project_id_or_key=projectIdOrKey,
         )
@@ -381,6 +393,11 @@ class Project(object):
         :param name: (str) will modified
         :return:
         """
+        warnings.warn(
+            "Project.update_category() is deprecated and will be removed in a future release; use BacklogAPI.category.update() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         _uri = "projects/{project_id_or_key}/categories/{id}".format(
             project_id_or_key=projectIdOrKey,
             id=id
@@ -399,6 +416,11 @@ class Project(object):
         :param id:
         :return:
         """
+        warnings.warn(
+            "Project.delete_category() is deprecated and will be removed in a future release; use BacklogAPI.category.delete() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         _uri = "projects/{project_id_or_key}/categories/{id}".format(
             project_id_or_key=projectIdOrKey,
             id=id

{python_backlog-0.8.0.dist-info → python_backlog-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-backlog
-Version: 0.8.0
+Version: 0.9.0
 Summary: Backlog API v2 wrapper
 Author-email: hassaku63 <hassaku63@gmail.com>
 License-Expression: MIT
@@ -22,17 +22,17 @@ Classifier: Natural Language :: English
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests<3,>=2.32.2
 Provides-Extra: dev
 Requires-Dist: flake8>=7; extra == "dev"
 Requires-Dist: coverage>=7.6; extra == "dev"
-Requires-Dist: httpretty>=1.1.4; extra == "dev"
-Requires-Dist: tox>=4; extra == "dev"
 Dynamic: license-file
 
 # pbl
 
-A Python package wraps Backlog API V2
+A Python package that wraps the [Backlog API v2](https://developer.nulab.com/docs/backlog/).
+
+- Requires Python 3.10 or later.
+- No runtime dependencies: only the Python standard library is used.
 
 ## Usage
 
@@ -58,11 +58,15 @@ def main():
     # Requests time out after 30 seconds by default (configurable with `timeout=`).
     api = BacklogAPI("your-space", "your-api-key")
 
+    # Categories
+    # https://developer.nulab.com/docs/backlog/api/2/get-category-list/
+    print(api.category.list("SampleProject"))
+
     """
     Project API
     """
     # list project users
-    # https://developer.nulab-inc.com/ja/docs/backlog/api/2/get-project-list/
+    # https://developer.nulab.com/docs/backlog/api/2/get-project-list/
     print("# list project users")
     users = api.project.list_users("SampleProject")
     print(json.dumps(users, indent=2))
@@ -72,13 +76,13 @@ def main():
     Wiki API
     """
     # list wikis
-    # https://developer.nulab-inc.com/ja/docs/backlog/api/2/get-wiki-page-list/
+    # https://developer.nulab.com/docs/backlog/api/2/get-wiki-page-list/
     print("# list wikis")
     wikis = api.wiki.list("SampleProject")
     print(json.dumps(wikis[0], indent=2))
 
     # get attachment
-    # https://developer.nulab-inc.com/ja/docs/backlog/api/2/get-issue-attachment/
+    # https://developer.nulab.com/docs/backlog/api/2/get-issue-attachment/
     print("# get attachment")
     wiki = [w for w in api.wiki.list("SampleProject") if len(w["attachments"]) > 0][0]
     attachment = api.wiki.get_attachment(
@@ -92,10 +96,31 @@ if __name__ == "__main__":
     main()
 ```
 
+## Errors
+
+- `backlog.base.BacklogError` is raised when the API returns a non-2xx response.
+- `backlog.base.BacklogConnectionError` (a subclass of `BacklogError`) is raised when the request could not be sent or no response was received, for example on a timeout.
+
+## TLS certificates
+
+HTTPS certificates are verified against the system trust store (it also honors `SSL_CERT_FILE` and `SSL_CERT_DIR`). If `certifi` is installed, or `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE` is set, those CA certificates are trusted as well.
+
+## Upgrading to 0.9
+
+0.9.0 removed the dependency on `requests`:
+
+- `BaseAPI.invoke_method()` returns a `backlog._http.Response` instead of a `requests.Response`. It provides `status_code`, `ok`, `headers`, `content`, `text` and `json()`.
+- `invoke_method()` only accepts the `timeout` and `files` keyword arguments. Requests-specific options such as `verify` or `proxies` raise `TypeError`. Proxies are still read from the `HTTP(S)_PROXY` and `NO_PROXY` environment variables.
+- Network errors raise `BacklogConnectionError` instead of `requests.exceptions.*`.
+- Redirects are not followed, so the API key is never sent to another host.
+- `Project.list_categories()`, `add_category()`, `update_category()` and `delete_category()` are deprecated. Use `BacklogAPI.category` instead.
+
 ## See also
 
 Qiita https://qiita.com/hassaku_63/items/b9eb2a1c7ecd3c19507d
 
 ## Contact
 
+Please open an issue on [GitHub](https://github.com/hassaku63/pbl/issues).
+
 Twitter: [hassaku_63](https://twitter.com/hassaku_63)

{python_backlog-0.8.0.dist-info → python_backlog-0.9.0.dist-info}/RECORD

@@ -1,15 +1,16 @@
 backlog/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+backlog/_http.py,sha256=5mAhdQss-eOSgtMQalSATsZGMTxBccNVjMqMGKRxbc4,6385
 backlog/attachment.py,sha256=_Ex_ob7NC0ZMrt_5OM3MqLzIQrswx8SceKhOYNY5Wgs,872
-backlog/base.py,sha256=CnZ0LLGcHb8yJm6v4gXmVUcki_M1U3Wv8kNgZgyLGoc,6120
+backlog/base.py,sha256=4hEjxogGKAcF3PQ4AetiC7hX-w1OmmE7o-BGP3tKD4Y,7081
 backlog/category.py,sha256=DQ06yhOCXxtDbPMZ1Ig1QD8n7Ht_ZFrp8PJzO18IeZk,2530
 backlog/custom_field.py,sha256=dJ-XnrYv0rlpLvPhIkZEgcyNjZB8GR3352Or8HUPKlc,12243
 backlog/git.py,sha256=mazfvwn1Ekga0eeigk22Xf3vhXEo-P5Irfyq6r_QbaA,3056
 backlog/issue.py,sha256=E7bhNLLQd1KkSEilGcrmKYlkfi_w8rVfRF6xI-PGEtc,6650
-backlog/project.py,sha256=SCNbxjpzKwK5eijN58su9jHnBnIT8XcLqU8kv_vuE3s,14348
+backlog/project.py,sha256=9Wdy25M-dhDNuZ4_2iSUz1k3KkE5oLP8Ean7sVppCpU,15273
 backlog/user.py,sha256=kSEkInekQ8aGgYs5ygCdA5tsUYK3cxO9_Aay-sfaC2A,2890
 backlog/wiki.py,sha256=ThfWC-OlnHDHMYeARYJega92fd3QhZ817mhWF1OegT4,5943
-python_backlog-0.8.0.dist-info/licenses/LICENSE,sha256=1teWq4411yGkUz_9lD1V74mcHFRix2IqOAoFaghKYwo,1073
-python_backlog-0.8.0.dist-info/METADATA,sha256=G6XWmav2guYsZ8dUyY0CVTyTf_Y-Vylg3HIvupnvFUU,2809
-python_backlog-0.8.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-python_backlog-0.8.0.dist-info/top_level.txt,sha256=qzHRU2P6F24ntkXGiIBl4Qf_AlV0BRebSc5tuLlcOIE,8
-python_backlog-0.8.0.dist-info/RECORD,,
+python_backlog-0.9.0.dist-info/licenses/LICENSE,sha256=1teWq4411yGkUz_9lD1V74mcHFRix2IqOAoFaghKYwo,1073
+python_backlog-0.9.0.dist-info/METADATA,sha256=YgM4IPdNaO49SM5n3Za7KuWOT_D2wxHxlqNCTC1OJpA,4344
+python_backlog-0.9.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_backlog-0.9.0.dist-info/top_level.txt,sha256=qzHRU2P6F24ntkXGiIBl4Qf_AlV0BRebSc5tuLlcOIE,8
+python_backlog-0.9.0.dist-info/RECORD,,