papycli 0.6.0__tar.gz → 0.8.0__tar.gz

{papycli-0.6.0 → papycli-0.8.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.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: papycli
-Version: 0.6.0
+Version: 0.8.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
 
@@ -70,6 +71,17 @@ eval "$(papycli config completion-script bash)"
 eval "$(papycli config completion-script zsh)"
 ```
 
+**Git Bash (Windows):**
+
+Git Bash uses MSYS path conversion, which can mangle the output of `$()` command substitution.
+Disable it before running the `eval` command:
+
+```bash
+# Add to ~/.bashrc or ~/.bash_profile
+export MSYS_NO_PATHCONV=1
+eval "$(papycli config completion-script bash)"
+```
+
 Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc` to apply.
 
 ---
@@ -218,6 +230,7 @@ papycli config completion-script <bash|zsh>  Print a shell completion script
 
 # Inspection commands
 papycli spec [resource]             Show the raw internal API spec (filter by resource path)
+papycli spec --full [resource]      Output the stored OpenAPI spec (filter by resource path if given)
 papycli summary [resource]          List available endpoints (filter by resource prefix)
                                       Required params marked with *, array params with []
 papycli summary --csv               Output endpoints in CSV format
@@ -230,7 +243,10 @@ Methods:
 
 Options:
   -H <header: value>      Custom HTTP header (repeatable)
-  -q <name> <value>       Query parameter (repeatable)
+  -q <name> <value>       Query parameter (repeatable).
+                            You can also embed query parameters directly in the
+                            resource path: "/pet/findByStatus?status=available"
+                            Inline parameters are sent before any -q parameters.
   -p <name> <value>       Body parameter (repeatable)
                             - Values are coerced to the correct JSON type
                               (integer, number, boolean) based on the API spec.
@@ -293,6 +309,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.8.0}/README.ja.md

@@ -12,6 +12,7 @@
 - API 仕様に基づいて `-p` の値を適切な JSON 型（integer / number / boolean）に自動変換
 - `papycli config log` によるリクエスト/レスポンスのファイルログ
 - リクエストフィルタープラグイン（`papycli.request_filters` エントリポイント）によるリクエスト処理の拡張
+- レスポンスフィルタープラグイン（`papycli.response_filters` エントリポイント）によるレスポンスの参照・変換
 
 ## 必要環境
 
@@ -43,6 +44,17 @@ eval "$(papycli config completion-script bash)"
 eval "$(papycli config completion-script zsh)"
 ```
 
+**Git Bash（Windows）の場合：**
+
+Git Bash は MSYS のパス変換機能を持つため、`$()` コマンド置換の出力が変換されて `eval` が正しく動作しないことがあります。
+`eval` を実行する前にパス変換を無効にしてください：
+
+```bash
+# ~/.bashrc または ~/.bash_profile に追加
+export MSYS_NO_PATHCONV=1
+eval "$(papycli config completion-script bash)"
+```
+
 設定を反映するためにシェルを再起動するか `source ~/.bashrc` / `source ~/.zshrc` を実行してください。
 
 ---
@@ -191,6 +203,7 @@ papycli config completion-script <bash|zsh>  シェル補完スクリプトを
 
 # 確認コマンド
 papycli spec [resource]             内部 API スペックを表示する（リソースパスでフィルタ可能）
+papycli spec --full [resource]      内部に保存された OpenAPI spec を出力する（RESOURCE 指定で絞り込み可能）
 papycli summary [resource]          利用可能なエンドポイントを表示する（リソースでフィルタ可能）
                                       必須パラメータは * 付き、配列パラメータは [] 付きで表示
 papycli summary --csv               CSV フォーマットでエンドポイントを表示する
@@ -204,6 +217,9 @@ papycli <method> <resource> [options]
 オプション:
   -H <header: value>      カスタム HTTP ヘッダー（繰り返し可）
   -q <name> <value>       クエリパラメータ（繰り返し可）
+                            リソースパスにクエリ文字列を直接埋め込むことも可能:
+                            '/pet/findByStatus?status=available'
+                            インラインパラメータは -q より先に送信される
   -p <name> <value>       ボディパラメータ（繰り返し可）
                             - API 仕様に基づいて値を適切な JSON 型（integer / number /
                               boolean）に自動変換する。文字列はそのまま送信される。
@@ -265,6 +281,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.8.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
 
@@ -43,6 +44,17 @@ eval "$(papycli config completion-script bash)"
 eval "$(papycli config completion-script zsh)"
 ```
 
+**Git Bash (Windows):**
+
+Git Bash uses MSYS path conversion, which can mangle the output of `$()` command substitution.
+Disable it before running the `eval` command:
+
+```bash
+# Add to ~/.bashrc or ~/.bash_profile
+export MSYS_NO_PATHCONV=1
+eval "$(papycli config completion-script bash)"
+```
+
 Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc` to apply.
 
 ---
@@ -191,6 +203,7 @@ papycli config completion-script <bash|zsh>  Print a shell completion script
 
 # Inspection commands
 papycli spec [resource]             Show the raw internal API spec (filter by resource path)
+papycli spec --full [resource]      Output the stored OpenAPI spec (filter by resource path if given)
 papycli summary [resource]          List available endpoints (filter by resource prefix)
                                       Required params marked with *, array params with []
 papycli summary --csv               Output endpoints in CSV format
@@ -203,7 +216,10 @@ Methods:
 
 Options:
   -H <header: value>      Custom HTTP header (repeatable)
-  -q <name> <value>       Query parameter (repeatable)
+  -q <name> <value>       Query parameter (repeatable).
+                            You can also embed query parameters directly in the
+                            resource path: "/pet/findByStatus?status=available"
+                            Inline parameters are sent before any -q parameters.
   -p <name> <value>       Body parameter (repeatable)
                             - Values are coerced to the correct JSON type
                               (integer, number, boolean) based on the API spec.
@@ -266,6 +282,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.8.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.8.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.8.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.8.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.8.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.8.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.8.0}/pyproject.toml

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