papycli 0.6.0__tar.gz → 0.7.0__tar.gz

{papycli-0.6.0 → papycli-0.7.0}/CLAUDE.md

@@ -58,6 +58,8 @@ papycli/
 │   ├── test_spec_loader.py
 │   └── test_summary.py
 ├── examples/
+│   ├── request_filter/      # リクエストフィルタープラグイン実装例
+│   ├── response_filter/     # レスポンスフィルタープラグイン実装例
 │   ├── docker-compose.yml
 │   └── petstore-oas3.json
 ├── pyproject.toml
@@ -90,8 +92,8 @@ bash / zsh 向けの補完スクリプトを生成する。補完の候補はメ
 **`config.py`** — 設定管理
 `papycli.conf` の読み書きと、`PAPYCLI_CONF_DIR` 環境変数の解決を行う。ログファイルパスの取得・設定・削除も担当する。
 
-**`request_filter.py`** — リクエストフィルタープラグイン機構
-エントリポイントグループ `papycli.request_filters` に登録されたフィルター関数をプラグイン名の昇順で呼び出し、リクエスト送信前に URL・クエリパラメータ・ボディ・ヘッダーを変換できるようにする。`RequestContext` データクラスと `load_filters()` / `apply_filters()` 関数を提供する。
+**`request_filter.py`** — リクエスト・レスポンスフィルタープラグイン機構
+エントリポイントグループ `papycli.request_filters` に登録されたフィルター関数をプラグイン名の昇順で呼び出し、リクエスト送信前に URL・クエリパラメータ・ボディ・ヘッダーを変換できるようにする。同様に `papycli.response_filters` グループのフィルター関数を呼び出し、レスポンス受信後にステータスコード・理由フレーズ（reason）・ボディ・ヘッダーを参照・変更できるようにする。`RequestContext` / `ResponseContext` データクラスと `load_filters()` / `apply_filters()` / `load_response_filters()` / `apply_response_filters()` 関数を提供する。
 
 **`summary.py`** — サマリー表示
 登録済み API のエンドポイント一覧を整形して出力する。`--summary-csv` では CSV 形式で出力する。

{papycli-0.6.0 → papycli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: papycli
-Version: 0.6.0
+Version: 0.7.0
 Summary: A CLI tool to call REST APIs defined in OpenAPI 3.0 specs
 Project-URL: Homepage, https://github.com/tmonj1/papycli
 Project-URL: Repository, https://github.com/tmonj1/papycli
@@ -39,6 +39,7 @@ Description-Content-Type: text/markdown
 - Automatically coerces `-p` values to the correct JSON type (integer, number, boolean) based on the API spec
 - Log requests and responses to a file with `papycli config log`
 - Extend request processing with request filter plugins (`papycli.request_filters` entry point)
+- Inspect and transform responses with response filter plugins (`papycli.response_filters` entry point)
 
 ## Requirements
 
@@ -293,6 +294,44 @@ Install the package and filters are applied automatically on every request, sort
 
 ---
 
+## Response Filter Plugins
+
+You can inspect and transform incoming responses by writing a response filter plugin.
+
+A filter is a callable that receives a `ResponseContext` and returns a modified `ResponseContext`:
+
+```python
+# my_plugin.py
+from papycli.request_filter import ResponseContext
+
+def response_filter(ctx: ResponseContext) -> ResponseContext:
+    if isinstance(ctx.body, dict):
+        ctx.body["_status"] = ctx.status_code
+    return ctx
+```
+
+Register it in your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."papycli.response_filters"]
+my-filter = "my_plugin:response_filter"
+```
+
+Install the package and the filters are applied automatically after every response, sorted by plugin name.
+
+`ResponseContext` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `method` | `str` | HTTP method used for the request (lowercase). |
+| `url` | `str` | Full URL of the request. |
+| `status_code` | `int` | HTTP response status code. |
+| `reason` | `str` | HTTP response reason phrase (e.g. `"OK"`, `"Not Found"`). |
+| `headers` | `dict[str, str]` | Response headers. |
+| `body` | `dict \| list \| str \| int \| float \| bool \| None` | Parsed response body. Modify this field to replace the response body. |
+
+---
+
 ## Limitations
 
 - Request bodies are `application/json` only

{papycli-0.6.0 → papycli-0.7.0}/README.ja.md

@@ -12,6 +12,7 @@
 - API 仕様に基づいて `-p` の値を適切な JSON 型（integer / number / boolean）に自動変換
 - `papycli config log` によるリクエスト/レスポンスのファイルログ
 - リクエストフィルタープラグイン（`papycli.request_filters` エントリポイント）によるリクエスト処理の拡張
+- レスポンスフィルタープラグイン（`papycli.response_filters` エントリポイント）によるレスポンスの参照・変換
 
 ## 必要環境
 
@@ -265,6 +266,44 @@ my-filter = "my_plugin:request_filter"
 
 ---
 
+## レスポンスフィルタープラグイン
+
+レスポンスフィルタープラグインを作成することで、受信後のレスポンスを参照・変換できます。
+
+フィルターは `ResponseContext` を受け取り、変更した `ResponseContext` を返す callable です：
+
+```python
+# my_plugin.py
+from papycli.request_filter import ResponseContext
+
+def response_filter(ctx: ResponseContext) -> ResponseContext:
+    if isinstance(ctx.body, dict):
+        ctx.body["_status"] = ctx.status_code
+    return ctx
+```
+
+パッケージの `pyproject.toml` にエントリポイントを登録します：
+
+```toml
+[project.entry-points."papycli.response_filters"]
+my-filter = "my_plugin:response_filter"
+```
+
+パッケージをインストールすると、すべてのレスポンスに対してフィルターがプラグイン名の昇順で自動適用されます。
+
+`ResponseContext` のフィールド：
+
+| フィールド | 型 | 説明 |
+|-----------|-----|------|
+| `method` | `str` | リクエストに使用した HTTP メソッド（小文字）。 |
+| `url` | `str` | リクエストに使用した完全 URL。 |
+| `status_code` | `int` | HTTP レスポンスステータスコード。 |
+| `reason` | `str` | HTTP レスポンスの理由フレーズ（例：`"OK"`、`"Not Found"`）。 |
+| `headers` | `dict[str, str]` | レスポンスヘッダー。 |
+| `body` | `dict \| list \| str \| int \| float \| bool \| None` | パース済みレスポンスボディ。このフィールドを変更するとレスポンスボディを差し替えられる。 |
+
+---
+
 ## 制限事項
 
 - リクエストボディは `application/json` のみ対応

{papycli-0.6.0 → papycli-0.7.0}/README.md

@@ -12,6 +12,7 @@
 - Automatically coerces `-p` values to the correct JSON type (integer, number, boolean) based on the API spec
 - Log requests and responses to a file with `papycli config log`
 - Extend request processing with request filter plugins (`papycli.request_filters` entry point)
+- Inspect and transform responses with response filter plugins (`papycli.response_filters` entry point)
 
 ## Requirements
 
@@ -266,6 +267,44 @@ Install the package and filters are applied automatically on every request, sort
 
 ---
 
+## Response Filter Plugins
+
+You can inspect and transform incoming responses by writing a response filter plugin.
+
+A filter is a callable that receives a `ResponseContext` and returns a modified `ResponseContext`:
+
+```python
+# my_plugin.py
+from papycli.request_filter import ResponseContext
+
+def response_filter(ctx: ResponseContext) -> ResponseContext:
+    if isinstance(ctx.body, dict):
+        ctx.body["_status"] = ctx.status_code
+    return ctx
+```
+
+Register it in your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."papycli.response_filters"]
+my-filter = "my_plugin:response_filter"
+```
+
+Install the package and the filters are applied automatically after every response, sorted by plugin name.
+
+`ResponseContext` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `method` | `str` | HTTP method used for the request (lowercase). |
+| `url` | `str` | Full URL of the request. |
+| `status_code` | `int` | HTTP response status code. |
+| `reason` | `str` | HTTP response reason phrase (e.g. `"OK"`, `"Not Found"`). |
+| `headers` | `dict[str, str]` | Response headers. |
+| `body` | `dict \| list \| str \| int \| float \| bool \| None` | Parsed response body. Modify this field to replace the response body. |
+
+---
+
 ## Limitations
 
 - Request bodies are `application/json` only

papycli-0.7.0/examples/request_filter/README.md

@@ -0,0 +1,82 @@
+# papycli-debug-filter
+
+A minimal example of a [papycli](https://github.com/tmonj1/papycli) request filter plugin.
+
+This plugin prints the outgoing `RequestContext` to **stderr** before each request — useful as a starting point for writing your own filter.
+
+> **Warning:** This plugin is intended for **debugging and development only**.
+> It prints request headers without redaction, which may expose sensitive values such as
+> Authorization tokens or API keys. Do NOT use this plugin in production environments.
+
+## What it does
+
+Before every `papycli` API call, it writes to stderr:
+
+```
+[papycli-debug-filter]
+  Method : GET
+  URL    : http://localhost:8080/api/v3/store/inventory
+  Query  : (none)
+  Body   : (none)
+  Headers: (none)
+```
+
+## Installation
+
+Install papycli and this plugin into the same Python environment:
+
+```bash
+pip install papycli
+pip install -e /path/to/papycli/examples/request_filter
+```
+
+Once installed, the filter is picked up automatically — no additional configuration needed.
+
+## Usage
+
+Run any papycli command. The filter output appears on **stderr**, while the API response is printed to **stdout** as usual:
+
+```bash
+papycli get /store/inventory
+```
+
+```
+# stderr:
+[papycli-debug-filter]
+  Method : GET
+  URL    : http://localhost:8080/api/v3/store/inventory
+  Query  : (none)
+  Body   : (none)
+  Headers: (none)
+
+# stdout:
+{
+  "approved": 1,
+  ...
+}
+```
+
+Because debug output goes to stderr, stdout remains machine-readable and piping still works:
+
+```bash
+papycli get /store/inventory | jq '.approved'
+```
+
+## How it works
+
+The plugin is registered via the `papycli.request_filters` entry point in `pyproject.toml`:
+
+```toml
+[project.entry-points."papycli.request_filters"]
+debug = "papycli_debug_filter:request_filter"
+```
+
+papycli discovers all installed plugins in this group, sorts them by name, and calls each one before sending the request. The filter receives a `RequestContext` and must return a (possibly modified) `RequestContext`.
+
+## Writing your own filter
+
+1. Copy this directory as a starting point.
+2. Edit `src/papycli_debug_filter/__init__.py` — modify `ctx` fields as needed and return it.
+3. Change the package name in `pyproject.toml` and re-install with `pip install -e .`.
+
+See the [papycli README](../../README.md#request-filter-plugins) for the full `RequestContext` field reference.

papycli-0.7.0/examples/request_filter/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "papycli-debug-filter"
+version = "0.1.0"
+description = "A papycli request filter plugin that prints request context to stderr"
+requires-python = ">=3.12"
+dependencies = [
+    "papycli>=0.6.0",
+]
+
+[project.entry-points."papycli.request_filters"]
+debug = "papycli_debug_filter:request_filter"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/papycli_debug_filter"]

papycli-0.7.0/examples/request_filter/src/papycli_debug_filter/__init__.py

@@ -0,0 +1,46 @@
+"""papycli request filter plugin — debug filter.
+
+Prints the outgoing RequestContext to stderr before each request.
+
+WARNING: This plugin is intended for debugging and development only.
+         It prints request headers without redaction, which may expose
+         sensitive values such as Authorization tokens or API keys.
+         Do NOT use this plugin in production environments.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from papycli.request_filter import RequestContext
+
+
+def _to_json(value: object) -> str:
+    """Serialize value to a JSON string, falling back to repr() on TypeError."""
+    try:
+        return json.dumps(value, ensure_ascii=False)
+    except TypeError:
+        return repr(value)
+
+
+def request_filter(ctx: RequestContext) -> RequestContext:
+    """Print request context fields to stderr and return it unchanged."""
+    q_dict: dict[str, object] = {}
+    for k, v in ctx.query_params:
+        existing = q_dict.get(k)
+        if existing is None:
+            q_dict[k] = v
+        elif isinstance(existing, list):
+            existing.append(v)
+        else:
+            q_dict[k] = [existing, v]
+
+    print("[papycli-debug-filter]", file=sys.stderr)
+    print(f"  Method : {ctx.method.upper()}", file=sys.stderr)
+    print(f"  URL    : {ctx.url}", file=sys.stderr)
+    print(f"  Query  : {_to_json(q_dict) if q_dict else '(none)'}", file=sys.stderr)
+    print(f"  Body   : {_to_json(ctx.body) if ctx.body is not None else '(none)'}", file=sys.stderr)
+    print(f"  Headers: {_to_json(ctx.headers) if ctx.headers else '(none)'}", file=sys.stderr)
+
+    return ctx

papycli-0.7.0/examples/response_filter/README.md

@@ -0,0 +1,82 @@
+# papycli-debug-response-filter
+
+A minimal example of a [papycli](https://github.com/tmonj1/papycli) response filter plugin.
+
+This plugin prints the received `ResponseContext` to **stderr** after each request — useful as a starting point for writing your own filter.
+
+> **Warning:** This plugin is intended for **debugging and development only**.
+> It prints response headers without redaction, which may expose sensitive values such as
+> Set-Cookie headers or authentication tokens. Do NOT use this plugin in production environments.
+
+## What it does
+
+After every `papycli` API call, it writes to stderr:
+
+```
+[papycli-debug-response-filter]
+  Method  : GET
+  URL     : http://localhost:8080/api/v3/store/inventory
+  Status  : 200 OK
+  Headers : {"Content-Type": "application/json", ...}
+  Body    : {"approved": 1, ...}
+```
+
+## Installation
+
+Install papycli and this plugin into the same Python environment:
+
+```bash
+pip install papycli
+pip install -e /path/to/papycli/examples/response_filter
+```
+
+Once installed, the filter is picked up automatically — no additional configuration needed.
+
+## Usage
+
+Run any papycli command. The filter output appears on **stderr**, while the API response is printed to **stdout** as usual:
+
+```bash
+papycli get /store/inventory
+```
+
+```
+# stderr:
+[papycli-debug-response-filter]
+  Method  : GET
+  URL     : http://localhost:8080/api/v3/store/inventory
+  Status  : 200 OK
+  Headers : {"Content-Type": "application/json; charset=utf-8"}
+  Body    : {"approved": 1, "sold": 2}
+
+# stdout:
+{
+  "approved": 1,
+  "sold": 2
+}
+```
+
+Because debug output goes to stderr, stdout remains machine-readable and piping still works:
+
+```bash
+papycli get /store/inventory | jq '.approved'
+```
+
+## How it works
+
+The plugin is registered via the `papycli.response_filters` entry point in `pyproject.toml`:
+
+```toml
+[project.entry-points."papycli.response_filters"]
+debug = "papycli_debug_response_filter:response_filter"
+```
+
+papycli discovers all installed plugins in this group, sorts them by name, and calls each one after receiving the response. The filter receives a `ResponseContext` and must return a (possibly modified) `ResponseContext`.
+
+## Writing your own filter
+
+1. Copy this directory as a starting point.
+2. Edit `src/papycli_debug_response_filter/__init__.py` — inspect or modify `ctx` fields as needed and return it.
+3. Change the package name in `pyproject.toml` and re-install with `pip install -e .`.
+
+See the [papycli README](../../README.md#response-filter-plugins) for the full `ResponseContext` field reference.

papycli-0.7.0/examples/response_filter/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "papycli-debug-response-filter"
+version = "0.1.0"
+description = "A papycli response filter plugin that prints response context to stderr"
+requires-python = ">=3.12"
+dependencies = [
+    "papycli>=0.7.0",
+]
+
+[project.entry-points."papycli.response_filters"]
+debug = "papycli_debug_response_filter:response_filter"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/papycli_debug_response_filter"]

papycli-0.7.0/examples/response_filter/src/papycli_debug_response_filter/__init__.py

@@ -0,0 +1,42 @@
+"""papycli response filter plugin — debug filter.
+
+Prints the received ResponseContext to stderr after each request.
+
+WARNING: This plugin is intended for debugging and development only.
+         It prints response headers without redaction, which may expose
+         sensitive values such as Set-Cookie or authentication tokens.
+         Do NOT use this plugin in production environments.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from papycli.request_filter import ResponseContext
+
+
+def _to_json(value: object) -> str:
+    """Serialize value to a JSON string, falling back to repr() on TypeError."""
+    try:
+        return json.dumps(value, ensure_ascii=False)
+    except TypeError:
+        return repr(value)
+
+
+def response_filter(ctx: ResponseContext) -> ResponseContext:
+    """Print response context fields to stderr and return it unchanged."""
+    print("[papycli-debug-response-filter]", file=sys.stderr)
+    print(f"  Method  : {ctx.method.upper()}", file=sys.stderr)
+    print(f"  URL     : {ctx.url}", file=sys.stderr)
+    print(f"  Status  : {ctx.status_code} {ctx.reason}", file=sys.stderr)
+    print(
+        f"  Headers : {_to_json(ctx.headers) if ctx.headers else '(none)'}",
+        file=sys.stderr,
+    )
+    print(
+        f"  Body    : {_to_json(ctx.body) if ctx.body is not None else '(none)'}",
+        file=sys.stderr,
+    )
+
+    return ctx

{papycli-0.6.0 → papycli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "papycli"
-version = "0.6.0"
+version = "0.7.0"
 description = "A CLI tool to call REST APIs defined in OpenAPI 3.0 specs"
 readme = "README.md"
 license = {text = "MIT"}

{papycli-0.6.0 → papycli-0.7.0}/src/papycli/api_call.py

@@ -262,7 +262,14 @@ def call_api(
     logfile: str | None = None,
 ) -> requests.Response:
     """API を呼び出し、レスポンスを返す。"""
-    from papycli.request_filter import RequestContext, apply_filters, load_filters
+    from papycli.request_filter import (
+        RequestContext,
+        ResponseContext,
+        apply_filters,
+        apply_response_filters,
+        load_filters,
+        load_response_filters,
+    )
 
     if not base_url:
         raise RuntimeError(
@@ -318,8 +325,89 @@ def call_api(
     )
 
     if logfile:
-        # ログにはフィルター適用前の値を使う。フィルタープラグインが追加した
-        # URL・クエリ・ボディ・ヘッダーには機密情報が含まれる可能性があるため記録しない。
+        # ログにはリクエスト側フィルター適用前の値（url/query/body/headers）とサーバーが
+        # 返した元のレスポンス（レスポンスフィルター適用前）を記録する。
         _write_log(logfile, method, url, list(query_params), json_body, headers, resp)
 
+    # レスポンスフィルターを事前にロードし、フィルターが存在する場合のみ
+    # レスポンスボディのパースと ResponseContext 構築を行う。
+    response_filters = load_response_filters()
+    if response_filters:
+        content_type = resp.headers.get("Content-Type", "").lower()
+        if "application/json" in content_type:
+            try:
+                resp_body: (
+                    dict[str, Any] | list[Any] | str | int | float | bool | None
+                ) = resp.json()
+            except ValueError:
+                resp_body = resp.text or None
+        else:
+            resp_body = resp.text or None
+
+        resp_ctx = ResponseContext(
+            method=method,
+            url=resp.url,
+            status_code=resp.status_code,
+            reason=resp.reason or "",
+            headers=dict(resp.headers),
+            body=resp_body,
+        )
+        resp_ctx = apply_response_filters(resp_ctx, response_filters)
+
+        # フィルターがフィールドを変更した場合、resp に反映する。
+        # ボディ: 値の等価比較で変更を検出し、_content・encoding・Content-Type を更新する。
+        # json.dumps が TypeError を送出した場合（非シリアライズ可能な値が含まれる場合等）は
+        # 警告を出力して元のレスポンスを維持する。
+        if resp_ctx.body != resp_body:
+            is_json_body = resp_ctx.body is not None and not isinstance(resp_ctx.body, str)
+            try:
+                if resp_ctx.body is None:
+                    new_content: bytes = b""
+                elif isinstance(resp_ctx.body, str):
+                    new_content = resp_ctx.body.encode("utf-8")
+                else:
+                    new_content = json.dumps(resp_ctx.body, ensure_ascii=False).encode("utf-8")
+            except (TypeError, ValueError) as e:
+                print(
+                    f"Warning: response filter returned a non-serializable body ({e});"
+                    " keeping original response",
+                    file=sys.stderr,
+                )
+            else:
+                resp._content = new_content
+                resp.encoding = "utf-8"
+                # Content-Length を新しいバイト長に更新する。
+                resp_ctx.headers["Content-Length"] = str(len(new_content))
+                # Content-Type をボディのシリアライズ方式にあわせて更新する。
+                # resp_ctx.headers を更新し、後続ヘッダー処理で一括して resp.headers に適用する。
+                ct = resp_ctx.headers.get("Content-Type", "")
+                if is_json_body:
+                    # dict/list 等は JSON シリアライズされるため application/json に設定する。
+                    resp_ctx.headers["Content-Type"] = "application/json; charset=utf-8"
+                else:
+                    # str/None ボディは既存の Content-Type を尊重しつつ charset だけ更新する。
+                    if ct:
+                        parts = [p.strip() for p in ct.split(";") if p.strip()]
+                        if parts:
+                            base_type = parts[0]
+                            base_type_lower = base_type.lower()
+                            is_text = base_type_lower.startswith("text/")
+                            if is_text or base_type_lower == "application/json":
+                                other_params = [
+                                    p for p in parts[1:]
+                                    if not p.lower().startswith("charset=")
+                                ]
+                                resp_ctx.headers["Content-Type"] = "; ".join(
+                                    [base_type, *other_params, "charset=utf-8"]
+                                )
+                    else:
+                        resp_ctx.headers["Content-Type"] = "text/plain; charset=utf-8"
+        # ステータスコード・理由フレーズ・ヘッダー: 変更があれば resp に反映する。
+        if resp_ctx.status_code != resp.status_code:
+            resp.status_code = resp_ctx.status_code
+        if resp_ctx.reason != (resp.reason or ""):
+            resp.reason = resp_ctx.reason
+        if resp_ctx.headers != dict(resp.headers):
+            resp.headers = requests.structures.CaseInsensitiveDict(resp_ctx.headers)
+
     return resp