kci-confluence-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{kci_confluence_cli-0.4.2 → kci_confluence_cli-0.4.3}/Makefile

@@ -19,8 +19,7 @@ lint:
 
 test:
 	# 並列実行してレポートも出力する
-	uv run pytest -n auto  --cov=kci --cov-report=html tests
+	uv run pytest -n auto --cov=confluence --cov-report=html tests
 
 docs:
 	cd docs && uv run make html
-

{kci_confluence_cli-0.4.2 → kci_confluence_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kci-confluence-cli
-Version: 0.4.2
+Version: 0.4.3
 Summary: Confluence v6.15.7を操作するためのCLIです。
 Project-URL: Repository, https://github.com/kurusugawa-computer/confluence-cli
 Author: Kurusugawa Computer Inc.
@@ -47,6 +47,24 @@ $ pip install kci-confluence-cli
 $ uvx --from kci-confluence-cli confluence page get_body --page_id 123456
 ```
 
+Python clientとして利用する場合は、共通のtimeout、redirect、response size policyを指定できます。
+
+```python
+from confluence.common.api import Api, TransportPolicy
+
+api = Api(
+    username,
+    password,
+    base_url,
+    transport_policy=TransportPolicy(
+        timeout_second=10,
+        follow_redirects=False,
+        response_byte_bound=2 * 1024 * 1024,
+    ),
+)
+content = api.get_content_by_id(content_id, query_params={"expand": "space,body.storage,version,ancestors"})
+```
+
 
 # Quick Start
 

{kci_confluence_cli-0.4.2 → kci_confluence_cli-0.4.3}/README.md

@@ -22,6 +22,24 @@ $ pip install kci-confluence-cli
 $ uvx --from kci-confluence-cli confluence page get_body --page_id 123456
 ```
 
+Python clientとして利用する場合は、共通のtimeout、redirect、response size policyを指定できます。
+
+```python
+from confluence.common.api import Api, TransportPolicy
+
+api = Api(
+    username,
+    password,
+    base_url,
+    transport_policy=TransportPolicy(
+        timeout_second=10,
+        follow_redirects=False,
+        response_byte_bound=2 * 1024 * 1024,
+    ),
+)
+content = api.get_content_by_id(content_id, query_params={"expand": "space,body.storage,version,ancestors"})
+```
+
 
 # Quick Start
 

{kci_confluence_cli-0.4.2 → kci_confluence_cli-0.4.3}/confluence/common/api.py

@@ -4,9 +4,11 @@ import copy
 import logging
 import mimetypes
 import time
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
+from requests import HTTPError, Response
 from requests_toolbelt import sessions
 
 logger = logging.getLogger(__name__)
@@ -15,6 +17,25 @@ QueryParams = dict[str, Any]
 RequestBody = dict[str, Any]
 
 
+class ResponseByteBoundExceeded(RuntimeError):
+    """Response body が configured byte bound を超えたことを表す。"""
+
+
+@dataclass(frozen=True)
+class TransportPolicy:
+    """Confluence HTTP transport に共通する bounded execution policy。"""
+
+    timeout_second: float = 30
+    follow_redirects: bool = True
+    response_byte_bound: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.timeout_second <= 0:
+            raise ValueError("timeout_secondは0より大きい値にしてください。")
+        if self.response_byte_bound is not None and self.response_byte_bound < 1:
+            raise ValueError("response_byte_boundは1以上の値にしてください。")
+
+
 class Api:
     """
     https://docs.atlassian.com/ConfluenceServer/rest/6.15.7/
@@ -22,10 +43,19 @@ class Api:
     Args:
         base_url: example: `https://kurusugawa.jp/confluence`
         delay_second: APIを連続で実行する際、何秒以上間隔を空けるか。Confluenceに負荷をかけすぎないようにするため、少なくとも0.3秒以上にすること。
+        transport_policy: timeout, redirect, response size の共通policy。
 
     """
 
-    def __init__(self, username: str, password: str, base_url: str, delay_second: float = 1) -> None:
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        base_url: str,
+        delay_second: float = 1,
+        *,
+        transport_policy: TransportPolicy | None = None,
+    ) -> None:
         if delay_second < 0.3:
             raise RuntimeError(f"引数'delay_second'は0.3以上にしてください。 :: {delay_second=}")
 
@@ -34,6 +64,7 @@ class Api:
         self.session.auth = (username, password)
 
         self.delay_second = delay_second
+        self.transport_policy = transport_policy or TransportPolicy()
         self._previous_timestamp: float = 0
 
     @staticmethod
@@ -57,21 +88,24 @@ class Api:
         params: QueryParams | None = None,
         data: Any = None,  # noqa: ANN401
         **kwargs,
-    ) -> Any:  # noqa: ANN401
+    ) -> Response:
         """
         HTTP Requestを投げて、Responseを返す。
 
         Args:
             http_method:
-            url_path:
-            query_params:
-            header_params:
-            body:
-            log_response_with_error: HTTP Errorが発生したときにレスポンスの中身をログに出力するか否か
+            url:
+            headers:
+            params:
+            data:
+            kwargs:
 
         Returns:
-            responseの中身。content_typeにより型が変わる。
-            application/jsonならdict型, text/*ならばstr型, それ以外ならばbite型。
+            HTTP response。response byte bound が指定されている場合は、bodyをbound内で読み込んだresponseを返す。
+
+        Raises:
+            HTTPError: HTTP status がerrorを表す場合。
+            ResponseByteBoundExceeded: Response body がconfigured byte boundを超えた場合。
 
         """
         now = time.time()
@@ -79,9 +113,22 @@ class Api:
         if diff_time < self.delay_second:
             time.sleep(self.delay_second - diff_time)
 
+        kwargs.setdefault("timeout", self.transport_policy.timeout_second)
+        kwargs.setdefault("allow_redirects", self.transport_policy.follow_redirects)
+        if self.transport_policy.response_byte_bound is not None:
+            kwargs["stream"] = True
+
         response = self.session.request(http_method, url, params=params, data=data, headers=headers, **kwargs)
         self._previous_timestamp = time.time()
 
+        try:
+            response.raise_for_status()
+        except HTTPError:
+            response.close()
+            raise
+        response_content = self._response_content(response)
+
+        # `kwargs["json"]` は credential やcontentを含みうるため、arbitrary JSON payloadは意図的にlogへ複製しない。
         logger.debug(
             "Sent a request :: %s",
             {
@@ -94,13 +141,39 @@ class Api:
                 },
                 "response": {
                     "status_code": response.status_code,
-                    "content_length": len(response.content),
+                    "content_length": len(response_content),
                 },
             },
         )
-        response.raise_for_status()
         return response
 
+    def _response_content(self, response: Response) -> bytes:
+        byte_bound = self.transport_policy.response_byte_bound
+        if byte_bound is None:
+            return response.content
+
+        body = bytearray()
+        try:
+            content_length = response.headers.get("Content-Length")
+            if content_length is not None:
+                try:
+                    if int(content_length) > byte_bound:
+                        raise ResponseByteBoundExceeded(f"Response bodyがbyte boundを超えました。 :: {byte_bound=}")
+                except ValueError:
+                    pass
+
+            for chunk in response.iter_content(chunk_size=min(64 * 1024, byte_bound + 1)):
+                body.extend(chunk)
+                if len(body) > byte_bound:
+                    raise ResponseByteBoundExceeded(f"Response bodyがbyte boundを超えました。 :: {byte_bound=}")
+        finally:
+            response.close()
+
+        response_content = bytes(body)
+        response._content = response_content
+        cast(Any, response)._content_consumed = True
+        return response_content
+
     def get_attachments(self, content_id: str, *, query_params: QueryParams | None = None) -> dict[str, Any]:
         url = f"content/{content_id}/child/attachment"
         return self._request("get", url, params=query_params).json()
@@ -170,5 +243,4 @@ class Api:
 
         https://docs.atlassian.com/ConfluenceServer/rest/6.15.7/#api/content-search
         """
-        response = self.session.get("content/search", params=query_params)
-        return response.json()
+        return self._request("get", "content/search", params=query_params).json()

kci_confluence_cli-0.4.3/docs/requirements.txt

@@ -0,0 +1,4 @@
+# ReadTheDocs用の依存パッケージ
+sphinx==9.1.0
+pydata-sphinx-theme==0.23.0
+sphinx-argparse==0.6.1

kci_confluence_cli-0.4.3/tests/test_common_api.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from requests import HTTPError, Response
+
+from confluence.common.api import Api, ResponseByteBoundExceeded, TransportPolicy
+
+
+def _json_response(body: bytes = b'{"id":"123456"}') -> Response:
+    response = Response()
+    response.status_code = 200
+    response.url = "https://confluence.example.test/confluence/rest/api/content/123456"
+    response.headers["Content-Type"] = "application/json"
+    response._content = body  # noqa: SLF001
+    response._content_consumed = True  # noqa: SLF001
+    return response
+
+
+def test_transport_policy_is_applied_to_protocol_request(monkeypatch: pytest.MonkeyPatch) -> None:
+    api = Api(
+        "reader",
+        "secret",
+        "https://confluence.example.test/confluence",
+        transport_policy=TransportPolicy(timeout_second=7, follow_redirects=False, response_byte_bound=1024),
+    )
+    request_argument: dict[str, Any] = {}
+
+    def fake_request(method: str, url: str, **kwargs: Any) -> Response:  # noqa: ANN401
+        request_argument.update(method=method, url=url, **kwargs)
+        return _json_response()
+
+    monkeypatch.setattr(api.session, "request", fake_request)
+
+    result = api.get_content_by_id("123456", query_params={"expand": "space,body.storage"})
+
+    assert result == {"id": "123456"}
+    assert request_argument == {
+        "method": "get",
+        "url": "content/123456",
+        "params": {"expand": "space,body.storage"},
+        "data": None,
+        "headers": None,
+        "timeout": 7,
+        "allow_redirects": False,
+        "stream": True,
+    }
+
+
+@pytest.mark.parametrize(
+    ("policy", "message"),
+    [
+        (TransportPolicy(timeout_second=1, response_byte_bound=4), "byte bound"),
+    ],
+)
+def test_response_byte_bound_is_enforced(
+    monkeypatch: pytest.MonkeyPatch,
+    policy: TransportPolicy,
+    message: str,
+) -> None:
+    api = Api("reader", "secret", "https://confluence.example.test/confluence", transport_policy=policy)
+    response = _json_response(b"12345")
+    monkeypatch.setattr(api.session, "request", lambda *_args, **_kwargs: response)
+
+    with pytest.raises(ResponseByteBoundExceeded, match=message):
+        api.get_content_by_id("123456")
+
+
+def test_streamed_error_response_is_closed(monkeypatch: pytest.MonkeyPatch) -> None:
+    api = Api(
+        "reader",
+        "secret",
+        "https://confluence.example.test/confluence",
+        transport_policy=TransportPolicy(response_byte_bound=1024),
+    )
+    response = _json_response()
+    response.status_code = 500
+    closed = False
+
+    def close() -> None:
+        nonlocal closed
+        closed = True
+
+    monkeypatch.setattr(response, "close", close)
+    monkeypatch.setattr(api.session, "request", lambda *_args, **_kwargs: response)
+
+    with pytest.raises(HTTPError):
+        api.get_content_by_id("123456")
+
+    assert closed is True
+
+
+def test_streamed_success_response_is_closed(monkeypatch: pytest.MonkeyPatch) -> None:
+    api = Api(
+        "reader",
+        "secret",
+        "https://confluence.example.test/confluence",
+        transport_policy=TransportPolicy(response_byte_bound=1024),
+    )
+    response = _json_response()
+    closed = False
+
+    def close() -> None:
+        nonlocal closed
+        closed = True
+
+    monkeypatch.setattr(response, "close", close)
+    monkeypatch.setattr(api.session, "request", lambda *_args, **_kwargs: response)
+
+    assert api.get_content_by_id("123456") == {"id": "123456"}
+    assert closed is True
+
+
+def test_transport_policy_rejects_non_positive_bounds() -> None:
+    with pytest.raises(ValueError, match="timeout_second"):
+        TransportPolicy(timeout_second=0)
+    with pytest.raises(ValueError, match="response_byte_bound"):
+        TransportPolicy(response_byte_bound=0)
+
+
+def test_search_uses_common_transport_policy(monkeypatch: pytest.MonkeyPatch) -> None:
+    api = Api("reader", "secret", "https://confluence.example.test/confluence")
+    request_argument: dict[str, Any] = {}
+
+    def fake_request(method: str, url: str, **kwargs: Any) -> Response:  # noqa: ANN401
+        request_argument.update(method=method, url=url, **kwargs)
+        return _json_response(b"{}")
+
+    monkeypatch.setattr(api.session, "request", fake_request)
+
+    assert api.search_content(query_params={"cql": "type=page"}) == {}
+    assert request_argument["timeout"] == 30
+    assert request_argument["allow_redirects"] is True