papycli 0.4.0__py3-none-any.whl

papycli/__init__.py

@@ -0,0 +1,5 @@
+"""papycli — OpenAPI 3.0 REST API を操作する CLI ツール."""
+
+from importlib.metadata import version
+
+__version__ = version("papycli")

papycli/api_call.py

@@ -0,0 +1,192 @@
+"""HTTP リクエスト実行・パステンプレートマッチング・パラメータ構築."""
+
+import json
+import os
+import re
+from collections.abc import Sequence
+from typing import Any
+
+import requests
+
+
+# ---------------------------------------------------------------------------
+# パステンプレートマッチング
+# ---------------------------------------------------------------------------
+
+
+def _template_to_regex(template: str) -> tuple[str, list[str]]:
+    """/pet/{petId} → (r'/pet/([^/]+)', ['petId']) に変換する。"""
+    param_names: list[str] = []
+    parts = re.split(r"\{([^}]+)\}", template)
+    pattern_parts: list[str] = []
+    for i, part in enumerate(parts):
+        if i % 2 == 0:
+            pattern_parts.append(re.escape(part))
+        else:
+            param_names.append(part)
+            pattern_parts.append("([^/]+)")
+    return "".join(pattern_parts), param_names
+
+
+def match_path_template(
+    resource: str, templates: list[str]
+) -> tuple[str, dict[str, str]] | None:
+    """resource をテンプレート一覧にマッチさせる。
+
+    完全一致を優先し、次にテンプレート変数が少ない（具体的な）順。
+    マッチしない場合は None を返す。
+    """
+    if resource in templates:
+        return resource, {}
+
+    matches: list[tuple[str, dict[str, str], int]] = []
+    for template in templates:
+        pattern, param_names = _template_to_regex(template)
+        m = re.fullmatch(pattern, resource)
+        if m:
+            path_params = dict(zip(param_names, m.groups()))
+            matches.append((template, path_params, len(param_names)))
+
+    if not matches:
+        return None
+
+    matches.sort(key=lambda x: x[2])
+    template, path_params, _ = matches[0]
+    return template, path_params
+
+
+def expand_path(template: str, path_params: dict[str, str]) -> str:
+    """/pet/{petId} + {petId: '99'} → /pet/99"""
+    result = template
+    for name, value in path_params.items():
+        result = result.replace(f"{{{name}}}", value)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# パラメータ構築
+# ---------------------------------------------------------------------------
+
+
+def _set_or_append(obj: dict[str, Any], key: str, value: str) -> None:
+    """dict にキーが既存なら配列に、なければ単値として設定する。"""
+    if key not in obj:
+        obj[key] = value
+    elif isinstance(obj[key], list):
+        obj[key].append(value)
+    else:
+        obj[key] = [obj[key], value]
+
+
+def build_body(pairs: Sequence[tuple[str, str]]) -> dict[str, Any]:
+    """(-p name value) ペアから JSON ボディ dict を構築する。
+
+    - 同じキーを繰り返すと JSON 配列になる
+    - ドット記法 (category.id) で 1 レベルのネストオブジェクトになる
+    """
+    result: dict[str, Any] = {}
+    for name, value in pairs:
+        if "." in name:
+            parent, child = name.split(".", 1)
+            if parent not in result:
+                result[parent] = {}
+            parent_obj = result[parent]
+            if not isinstance(parent_obj, dict):
+                raise ValueError(
+                    f"Cannot use dot notation on '{parent}': already a scalar or array"
+                )
+            _set_or_append(parent_obj, child, value)
+        else:
+            _set_or_append(result, name, value)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# ヘッダー解析
+# ---------------------------------------------------------------------------
+
+
+def parse_headers(
+    header_strings: Sequence[str],
+    custom_header_env: str | None = None,
+) -> dict[str, str]:
+    """"-H Header: Value" 文字列と PAPYCLI_CUSTOM_HEADER 環境変数からヘッダー dict を構築する。
+
+    環境変数より -H オプションが優先される。
+    """
+    headers: dict[str, str] = {}
+
+    if custom_header_env:
+        for line in custom_header_env.splitlines():
+            line = line.strip()
+            if line and ":" in line:
+                k, _, v = line.partition(":")
+                headers[k.strip()] = v.strip()
+
+    for h in header_strings:
+        if ":" not in h:
+            raise ValueError(f"Invalid header format: {h!r} (expected 'Name: Value')")
+        k, _, v = h.partition(":")
+        headers[k.strip()] = v.strip()
+
+    return headers
+
+
+# ---------------------------------------------------------------------------
+# HTTP 実行
+# ---------------------------------------------------------------------------
+
+
+def call_api(
+    method: str,
+    resource: str,
+    base_url: str,
+    apidef: dict[str, Any],
+    *,
+    query_params: Sequence[tuple[str, str]] = (),
+    body_params: Sequence[tuple[str, str]] = (),
+    raw_body: str | None = None,
+    extra_headers: Sequence[str] = (),
+) -> requests.Response:
+    """API を呼び出し、レスポンスを返す。"""
+    if not base_url:
+        raise RuntimeError(
+            "Base URL is not configured. Edit papycli.conf and set the 'url' field."
+        )
+
+    templates = list(apidef.keys())
+    match = match_path_template(resource, templates)
+    if match is None:
+        raise ValueError(
+            f"No matching path for '{resource}'.\n"
+            f"Available paths: {', '.join(templates)}"
+        )
+    template, path_params = match
+
+    ops: list[dict[str, Any]] = apidef[template]
+    if not any(op["method"] == method for op in ops):
+        available = [op["method"] for op in ops]
+        raise ValueError(
+            f"Method '{method}' is not defined for '{template}'. "
+            f"Available: {', '.join(available)}"
+        )
+
+    expanded = expand_path(template, path_params)
+    url = base_url.rstrip("/") + expanded
+
+    custom_env = os.environ.get("PAPYCLI_CUSTOM_HEADER")
+    headers = parse_headers(extra_headers, custom_env)
+
+    json_body: dict[str, Any] | None = None
+    if raw_body is not None:
+        json_body = json.loads(raw_body)
+    elif body_params:
+        json_body = build_body(body_params)
+
+    return requests.request(
+        method=method.upper(),
+        url=url,
+        params=list(query_params),
+        json=json_body,
+        headers=headers,
+    )

papycli/completion.py

@@ -0,0 +1,168 @@
+"""シェル補完ロジックとスクリプト生成。
+
+補完の仕組み:
+  bash/zsh スクリプトが `papycli _complete <current_index> <words...>` を呼び出す。
+  `_complete` コマンドが補完候補を 1 行 1 候補の形式で標準出力に返す。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+METHODS = ["get", "post", "put", "patch", "delete"]
+MANAGEMENT_COMMANDS = ["init", "use", "conf", "summary", "completion-script"]
+ALL_COMMANDS = METHODS + MANAGEMENT_COMMANDS
+
+# ---------------------------------------------------------------------------
+# シェルスクリプトテンプレート
+# ---------------------------------------------------------------------------
+
+BASH_SCRIPT = """\
+_papycli_completion() {
+    local IFS=$'\\n'
+    COMPREPLY=($(papycli _complete "${COMP_CWORD}" "${COMP_WORDS[@]}" 2>/dev/null))
+}
+complete -o nospace -F _papycli_completion papycli
+"""
+
+ZSH_SCRIPT = """\
+_papycli() {
+    local -a completions
+    completions=(${(f)"$(papycli _complete "$((CURRENT - 1))" "${words[@]}" 2>/dev/null)"})
+    if [[ ${#completions[@]} -gt 0 ]]; then
+        _describe '' completions
+    fi
+}
+compdef _papycli papycli
+"""
+
+
+def generate_script(shell: str) -> str:
+    """指定シェル向けの補完スクリプトを返す。"""
+    if shell == "bash":
+        return BASH_SCRIPT
+    return ZSH_SCRIPT
+
+
+# ---------------------------------------------------------------------------
+# 補完ロジック（純粋関数 — apidef を引数で受け取る）
+# ---------------------------------------------------------------------------
+
+
+def _find_op(
+    apidef: dict[str, Any], method: str, resource: str
+) -> dict[str, Any] | None:
+    """resource にマッチするテンプレートを探し、指定 method の operation を返す。"""
+    from papycli.api_call import match_path_template
+
+    match = match_path_template(resource, list(apidef.keys()))
+    if match is None:
+        return None
+    template, _ = match
+    return next((o for o in apidef[template] if o["method"] == method), None)
+
+
+def _complete_resources(apidef: dict[str, Any], incomplete: str) -> list[str]:
+    return [p for p in sorted(apidef.keys()) if p.startswith(incomplete)]
+
+
+def _complete_param_names(
+    apidef: dict[str, Any],
+    method: str,
+    resource: str,
+    kind: str,
+    incomplete: str,
+) -> list[str]:
+    op = _find_op(apidef, method, resource)
+    if op is None:
+        return []
+    key = "query_parameters" if kind == "query" else "post_parameters"
+    return [p["name"] for p in op.get(key, []) if p["name"].startswith(incomplete)]
+
+
+def _complete_enum_values(
+    apidef: dict[str, Any],
+    method: str,
+    resource: str,
+    kind: str,
+    param_name: str,
+    incomplete: str,
+) -> list[str]:
+    op = _find_op(apidef, method, resource)
+    if op is None:
+        return []
+    key = "query_parameters" if kind == "query" else "post_parameters"
+    for p in op.get(key, []):
+        if p["name"] == param_name and "enum" in p:
+            return [str(v) for v in p["enum"] if str(v).startswith(incomplete)]
+    return []
+
+
+def completions_for_context(
+    words: list[str],
+    current: int,
+    apidef: dict[str, Any] | None,
+) -> list[str]:
+    """コマンドラインのコンテキストに応じた補完候補を返す。
+
+    Args:
+        words:   コマンドライントークンのリスト（words[0] = "papycli"）
+        current: 補完中の単語のインデックス（0 始まり）
+        apidef:  現在の API 定義 dict。None の場合は空リストを返す。
+    """
+    incomplete = words[current] if current < len(words) else ""
+
+    # サブコマンド名の補完
+    if current == 1:
+        return [c for c in ALL_COMMANDS if c.startswith(incomplete)]
+
+    # words[1] が HTTP メソッドでない場合は補完なし
+    if len(words) < 2 or words[1] not in METHODS:
+        return []
+
+    method = words[1]
+
+    # リソースパスの補完
+    if current == 2:
+        if apidef is None:
+            return []
+        return _complete_resources(apidef, incomplete)
+
+    resource = words[2] if len(words) > 2 else ""
+    prev = words[current - 1] if current >= 1 else ""
+    prev_prev = words[current - 2] if current >= 2 else ""
+
+    if apidef is None:
+        return []
+
+    # -q NAME → クエリパラメータ名
+    if prev == "-q":
+        return _complete_param_names(apidef, method, resource, "query", incomplete)
+
+    # -q NAME VALUE → enum 値
+    if prev_prev == "-q":
+        return _complete_enum_values(apidef, method, resource, "query", prev, incomplete)
+
+    # -p NAME → ボディパラメータ名
+    if prev == "-p":
+        return _complete_param_names(apidef, method, resource, "body", incomplete)
+
+    # -p NAME VALUE → enum 値
+    if prev_prev == "-p":
+        return _complete_enum_values(apidef, method, resource, "body", prev, incomplete)
+
+    # オプション名
+    opts = ["-q", "-p", "-d", "-H", "--summary"]
+    return [o for o in opts if o.startswith(incomplete)]
+
+
+def get_completions(words: list[str], current: int, conf_dir: Path | None = None) -> list[str]:
+    """apidef をディスクから読み込んで補完候補を返す。失敗した場合は空リスト。"""
+    from papycli.config import get_conf_dir, load_current_apidef
+
+    try:
+        apidef, _ = load_current_apidef(conf_dir or get_conf_dir())
+    except Exception:
+        apidef = None
+    return completions_for_context(words, current, apidef)

papycli/config.py

@@ -0,0 +1,93 @@
+"""設定ファイル (papycli.conf) の読み書き."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+CONF_FILENAME = "papycli.conf"
+APIS_DIRNAME = "apis"
+
+
+def get_conf_dir() -> Path:
+    """設定ディレクトリを返す。PAPYCLI_CONF_DIR 環境変数 or ~/.papycli"""
+    env = os.environ.get("PAPYCLI_CONF_DIR")
+    if env:
+        return Path(env)
+    return Path.home() / ".papycli"
+
+
+def get_conf_path(conf_dir: Path | None = None) -> Path:
+    return (conf_dir or get_conf_dir()) / CONF_FILENAME
+
+
+def get_apis_dir(conf_dir: Path | None = None) -> Path:
+    return (conf_dir or get_conf_dir()) / APIS_DIRNAME
+
+
+def load_conf(conf_dir: Path | None = None) -> dict[str, Any]:
+    """設定ファイルを読み込む。存在しない場合は空の dict を返す。"""
+    path = get_conf_path(conf_dir)
+    if not path.exists():
+        return {}
+    with path.open(encoding="utf-8") as f:
+        return json.load(f)  # type: ignore[no-any-return]
+
+
+def save_conf(conf: dict[str, Any], conf_dir: Path | None = None) -> None:
+    """設定ファイルを保存する。ディレクトリが存在しない場合は作成する。"""
+    path = get_conf_path(conf_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(conf, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def register_api(
+    conf: dict[str, Any],
+    name: str,
+    openapispec: str,
+    apidef: str,
+    url: str,
+) -> None:
+    """設定に API エントリを追加・更新する。default が未設定の場合は自動設定する。"""
+    conf[name] = {"openapispec": openapispec, "apidef": apidef, "url": url}
+    if "default" not in conf:
+        conf["default"] = name
+
+
+def set_default_api(conf: dict[str, Any], name: str) -> None:
+    """デフォルト API を変更する。"""
+    conf["default"] = name
+
+
+def get_default_api(conf: dict[str, Any]) -> str | None:
+    """現在のデフォルト API 名を返す。未設定の場合は None。"""
+    return conf.get("default")  # type: ignore[return-value]
+
+
+def load_current_apidef(conf_dir: Path | None = None) -> tuple[dict[str, Any], str]:
+    """現在のデフォルト API の (apidef dict, base_url) を返す。"""
+    resolved_dir = conf_dir or get_conf_dir()
+    conf = load_conf(resolved_dir)
+    api_name = get_default_api(conf)
+    if not api_name:
+        raise RuntimeError("No default API configured. Run 'papycli init <spec>' first.")
+
+    api_entry = conf.get(api_name)
+    if not isinstance(api_entry, dict):
+        raise RuntimeError(f"Invalid configuration for API '{api_name}'.")
+
+    base_url = str(api_entry.get("url", ""))
+    apidef_filename = str(api_entry.get("apidef", f"{api_name}.json"))
+    apidef_path = get_apis_dir(resolved_dir) / apidef_filename
+
+    if not apidef_path.exists():
+        raise RuntimeError(
+            f"API definition file not found: {apidef_path}\n"
+            "Run 'papycli init <spec>' to regenerate it."
+        )
+
+    with apidef_path.open(encoding="utf-8") as f:
+        apidef: dict[str, Any] = json.load(f)
+    return apidef, base_url

papycli/init_cmd.py

@@ -0,0 +1,43 @@
+"""--init コマンドの処理: OpenAPI spec を内部形式に変換して保存する。"""
+
+import json
+from pathlib import Path
+
+from papycli.config import get_apis_dir, register_api
+from papycli.spec_loader import extract_base_url, load_spec, resolve_refs, spec_to_apidef
+
+
+def init_api(spec_path: Path, conf_dir: Path) -> tuple[str, str]:
+    """OpenAPI spec を読み込み、内部形式に変換して保存する。
+
+    Returns:
+        (api_name, base_url) のタプル
+    """
+    raw_spec = load_spec(spec_path)
+    resolved_spec = resolve_refs(raw_spec, raw_spec)
+    apidef = spec_to_apidef(resolved_spec)
+
+    api_name = spec_path.stem
+    base_url = extract_base_url(resolved_spec)
+
+    apis_dir = get_apis_dir(conf_dir)
+    apis_dir.mkdir(parents=True, exist_ok=True)
+
+    apidef_path = apis_dir / f"{api_name}.json"
+    with apidef_path.open("w", encoding="utf-8") as f:
+        json.dump(apidef, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+    return api_name, base_url
+
+
+def register_initialized_api(
+    conf: dict,  # type: ignore[type-arg]
+    api_name: str,
+    spec_path: Path,
+    base_url: str,
+) -> None:
+    """init 後に設定ファイルへ API エントリを登録する。"""
+    spec_filename = spec_path.name
+    apidef_filename = f"{api_name}.json"
+    register_api(conf, api_name, spec_filename, apidef_filename, base_url)

papycli/main.py

@@ -0,0 +1,231 @@
+"""CLI エントリポイント."""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import requests
+
+from papycli import __version__
+from papycli.api_call import call_api, match_path_template
+from papycli.config import (
+    get_conf_dir,
+    get_conf_path,
+    load_conf,
+    load_current_apidef,
+    save_conf,
+    set_default_api,
+)
+from papycli.completion import generate_script, get_completions
+from papycli.init_cmd import init_api, register_initialized_api
+from papycli.summary import format_endpoint_detail, format_summary_csv, print_summary
+
+
+@click.group(invoke_without_command=True, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-V", "--version")
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """papycli — OpenAPI 3.0 仕様から REST API を呼び出す CLI ツール."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ---------------------------------------------------------------------------
+# 設定系コマンド
+# ---------------------------------------------------------------------------
+
+
+@cli.command("init")
+@click.argument("spec_file", metavar="SPEC_FILE", type=click.Path(exists=True, dir_okay=False))
+def cmd_init(spec_file: str) -> None:
+    """OpenAPI spec ファイルから API を初期化する。"""
+    spec_path = Path(spec_file)
+    conf_dir = get_conf_dir()
+
+    try:
+        api_name, base_url = init_api(spec_path, conf_dir)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    conf = load_conf(conf_dir)
+    register_initialized_api(conf, api_name, spec_path, base_url)
+    save_conf(conf, conf_dir)
+
+    click.echo(f"Initialized API '{api_name}'")
+    if base_url:
+        click.echo(f"  Base URL : {base_url}")
+    else:
+        click.echo("  Base URL : (not set — edit papycli.conf to add url)")
+    click.echo(f"  Conf dir : {conf_dir}")
+
+
+@cli.command("use")
+@click.argument("api_name", metavar="API_NAME")
+def cmd_use(api_name: str) -> None:
+    """アクティブな API を切り替える。"""
+    conf_dir = get_conf_dir()
+    conf = load_conf(conf_dir)
+
+    if api_name not in conf:
+        registered = [k for k in conf if k != "default"]
+        if registered:
+            click.echo(f"Error: API '{api_name}' is not registered.", err=True)
+            click.echo(f"Registered APIs: {', '.join(registered)}", err=True)
+        else:
+            click.echo("Error: No APIs registered. Run 'papycli init <spec>' first.", err=True)
+        sys.exit(1)
+
+    set_default_api(conf, api_name)
+    save_conf(conf, conf_dir)
+    click.echo(f"Switched default API to '{api_name}'")
+
+
+@cli.command("conf")
+def cmd_conf() -> None:
+    """現在の設定と環境変数を表示する。"""
+    conf_dir = get_conf_dir()
+    conf_path = get_conf_path(conf_dir)
+
+    click.echo(f"Conf dir  : {conf_dir}")
+    click.echo(f"Conf file : {conf_path}")
+    click.echo("")
+
+    conf = load_conf(conf_dir)
+    if not conf:
+        click.echo("(no configuration — run 'papycli init <spec>' to get started)")
+        return
+
+    click.echo(json.dumps(conf, indent=2, ensure_ascii=False))
+
+
+# ---------------------------------------------------------------------------
+# summary コマンド
+# ---------------------------------------------------------------------------
+
+
+@cli.command("summary")
+@click.argument("resource", required=False, default=None)
+@click.option("--csv", "as_csv", is_flag=True, help="CSV フォーマットで出力する")
+def cmd_summary(resource: str | None, as_csv: bool) -> None:
+    """登録済み API のエンドポイント一覧を表示する。
+
+    RESOURCE を指定するとそのパスプレフィックスで絞り込む。
+    """
+    conf_dir = get_conf_dir()
+    try:
+        apidef, _ = load_current_apidef(conf_dir)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    if as_csv:
+        click.echo(format_summary_csv(apidef), nl=False)
+    else:
+        print_summary(apidef, resource_filter=resource)
+
+
+# ---------------------------------------------------------------------------
+# API 呼び出しコマンド (get / post / put / patch / delete)
+# ---------------------------------------------------------------------------
+
+
+def _print_response(resp: requests.Response) -> None:
+    click.echo(f"HTTP {resp.status_code} {resp.reason}")
+    content_type = resp.headers.get("Content-Type", "")
+    if "application/json" in content_type:
+        try:
+            click.echo(json.dumps(resp.json(), indent=2, ensure_ascii=False))
+            return
+        except ValueError:
+            pass
+    if resp.text:
+        click.echo(resp.text)
+
+
+def _api_command(method: str) -> click.Command:
+    """HTTP メソッドごとの CLI コマンドを生成する。"""
+
+    @click.command(method, help=f"HTTP {method.upper()} リクエストを送信する。")
+    @click.argument("resource")
+    @click.option("-q", "query_params", multiple=True, nargs=2, metavar="NAME VALUE",
+                  help="クエリパラメータ（繰り返し可）")
+    @click.option("-p", "body_params", multiple=True, nargs=2, metavar="NAME VALUE",
+                  help="ボディパラメータ（繰り返し可）")
+    @click.option("-d", "raw_body", default=None, metavar="JSON",
+                  help="生の JSON ボディ（-p を上書き）")
+    @click.option("-H", "extra_headers", multiple=True, metavar="HEADER: VALUE",
+                  help="カスタム HTTP ヘッダー（繰り返し可）")
+    @click.option("--summary", "show_summary", is_flag=True,
+                  help="リクエストを送らずにエンドポイント情報を表示する")
+    def _cmd(
+        resource: str,
+        query_params: tuple[tuple[str, str], ...],
+        body_params: tuple[tuple[str, str], ...],
+        raw_body: str | None,
+        extra_headers: tuple[str, ...],
+        show_summary: bool,
+    ) -> None:
+        conf_dir = get_conf_dir()
+        try:
+            apidef, base_url = load_current_apidef(conf_dir)
+        except Exception as e:
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(1)
+
+        if show_summary:
+            match = match_path_template(resource, list(apidef.keys()))
+            if match is None:
+                click.echo(f"Error: No matching path for '{resource}'", err=True)
+                sys.exit(1)
+            template, _ = match
+            click.echo(format_endpoint_detail(apidef, method, template))
+            return
+
+        try:
+            resp = call_api(
+                method, resource, base_url, apidef,
+                query_params=query_params,
+                body_params=body_params,
+                raw_body=raw_body,
+                extra_headers=extra_headers,
+            )
+        except Exception as e:
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(1)
+
+        _print_response(resp)
+
+    return _cmd
+
+
+for _method in ("get", "post", "put", "patch", "delete"):
+    cli.add_command(_api_command(_method))
+
+
+# ---------------------------------------------------------------------------
+# シェル補完コマンド
+# ---------------------------------------------------------------------------
+
+
+@cli.command("completion-script")
+@click.argument("shell", type=click.Choice(["bash", "zsh"]))
+def cmd_completion_script(shell: str) -> None:
+    """シェル補完スクリプトを出力する。
+
+    使い方 (bash): eval "$(papycli completion-script bash)"
+
+    使い方 (zsh):  eval "$(papycli completion-script zsh)"
+    """
+    click.echo(generate_script(shell), nl=False)
+
+
+@cli.command("_complete", hidden=True, context_settings={"ignore_unknown_options": True})
+@click.argument("current_index", type=int)
+@click.argument("words", nargs=-1, type=click.UNPROCESSED)
+def cmd_complete(current_index: int, words: tuple[str, ...]) -> None:
+    """シェル補完スクリプトから呼ばれる内部コマンド。補完候補を 1 行 1 候補で出力する。"""
+    results = get_completions(list(words), current_index, get_conf_dir())
+    if results:
+        click.echo("\n".join(results))

papycli/spec_loader.py

@@ -0,0 +1,142 @@
+"""OpenAPI spec の読み込み・$ref 解決・内部フォーマット変換."""
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    """JSON または YAML の OpenAPI spec ファイルを読み込む。"""
+    with path.open(encoding="utf-8") as f:
+        if path.suffix in (".yaml", ".yml"):
+            return yaml.safe_load(f)  # type: ignore[no-any-return]
+        return json.load(f)  # type: ignore[no-any-return]
+
+
+def _resolve_json_pointer(ref: str, root: dict[str, Any]) -> Any:
+    """'#/a/b/c' 形式の JSON Pointer を解決する。"""
+    if not ref.startswith("#/"):
+        raise ValueError(f"Unsupported $ref: {ref!r} (only internal '#/...' refs are supported)")
+    parts = ref[2:].split("/")
+    node: Any = root
+    for part in parts:
+        part = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(node, dict) or part not in node:
+            raise KeyError(f"$ref target not found: {ref!r}")
+        node = node[part]
+    return node
+
+
+def resolve_refs(
+    obj: Any,
+    root: dict[str, Any],
+    _visited: frozenset[str] = frozenset(),
+) -> Any:
+    """オブジェクト中のすべての $ref を再帰的に解決する。循環参照は空 dict で打ち切る。"""
+    if isinstance(obj, dict):
+        if "$ref" in obj:
+            ref: str = obj["$ref"]
+            if ref in _visited:
+                return {}  # 循環参照ガード
+            target = _resolve_json_pointer(ref, root)
+            return resolve_refs(copy.deepcopy(target), root, _visited | {ref})
+        return {k: resolve_refs(v, root, _visited) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [resolve_refs(item, root, _visited) for item in obj]
+    return obj
+
+
+def _extract_schema_properties(
+    schema: dict[str, Any],
+) -> tuple[list[str], dict[str, Any]]:
+    """スキーマから (required フィールド名リスト, properties dict) を取り出す。allOf に対応。"""
+    required: list[str] = []
+    properties: dict[str, Any] = {}
+
+    for sub in schema.get("allOf", []):
+        r, p = _extract_schema_properties(sub)
+        required.extend(r)
+        properties.update(p)
+
+    required.extend(schema.get("required", []))
+    properties.update(schema.get("properties", {}))
+    return required, properties
+
+
+def _param_entry(name: str, schema: dict[str, Any], required: bool) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "name": name,
+        "type": schema.get("type", "string"),
+        "required": required,
+    }
+    if "enum" in schema:
+        entry["enum"] = schema["enum"]
+    return entry
+
+
+def spec_to_apidef(spec: dict[str, Any]) -> dict[str, Any]:
+    """解決済み OpenAPI spec を papycli 内部 API 定義フォーマットに変換する。"""
+    apidef: dict[str, Any] = {}
+    paths: dict[str, Any] = spec.get("paths", {})
+
+    for path, path_item in paths.items():
+        # path レベルの共通パラメータ
+        common_params: dict[str, Any] = {
+            p["name"]: p for p in path_item.get("parameters", [])
+        }
+        methods = []
+
+        for method in ("get", "post", "put", "patch", "delete"):
+            operation: dict[str, Any] | None = path_item.get(method)
+            if operation is None:
+                continue
+
+            # path レベル + operation レベルをマージ (operation が優先)
+            merged_params = {**common_params}
+            for p in operation.get("parameters", []):
+                merged_params[p["name"]] = p
+
+            query_parameters = [
+                _param_entry(p["name"], p.get("schema", {}), bool(p.get("required", False)))
+                for p in merged_params.values()
+                if p.get("in") == "query"
+            ]
+
+            # リクエストボディ (application/json のみ)
+            post_parameters: list[dict[str, Any]] = []
+            json_schema = (
+                operation.get("requestBody", {})
+                .get("content", {})
+                .get("application/json", {})
+                .get("schema", {})
+            )
+            if json_schema:
+                req_fields, props = _extract_schema_properties(json_schema)
+                post_parameters = [
+                    _param_entry(name, prop_schema, name in req_fields)
+                    for name, prop_schema in props.items()
+                ]
+
+            methods.append(
+                {
+                    "method": method,
+                    "query_parameters": query_parameters,
+                    "post_parameters": post_parameters,
+                }
+            )
+
+        if methods:
+            apidef[path] = methods
+
+    return apidef
+
+
+def extract_base_url(spec: dict[str, Any]) -> str:
+    """spec から servers[0].url を返す。存在しない場合は空文字。"""
+    servers = spec.get("servers", [])
+    if servers:
+        return str(servers[0].get("url", ""))
+    return ""

papycli/summary.py

@@ -0,0 +1,110 @@
+"""--summary / --summary-csv の出力処理。"""
+
+import csv
+import io
+from typing import Any, TextIO
+
+from rich.console import Console
+from rich.table import Table
+
+
+def _format_param(p: dict[str, Any], flag: str) -> str:
+    """パラメータを表示用文字列に変換する。
+
+    例: -q status*[available|pending|sold]  / -p photoUrls*[]
+    """
+    name = p["name"]
+    annotation = ""
+    if p.get("required"):
+        annotation += "*"
+    if p.get("type") == "array":
+        annotation += "[]"
+    result = f"{flag} {name}{annotation}"
+    if "enum" in p:
+        enum_str = "|".join(str(e) for e in p["enum"])
+        result += f"[{enum_str}]"
+    return result
+
+
+def build_rows(
+    apidef: dict[str, Any],
+    resource_filter: str | None = None,
+) -> list[tuple[str, str, str]]:
+    """(METHOD, path, params_str) のリストを返す。テストや CSV 生成にも利用。"""
+    rows: list[tuple[str, str, str]] = []
+    for path in sorted(apidef.keys()):
+        if resource_filter and not path.startswith(resource_filter):
+            continue
+        for op in apidef[path]:
+            q_parts = [_format_param(p, "-q") for p in op.get("query_parameters", [])]
+            p_parts = [_format_param(p, "-p") for p in op.get("post_parameters", [])]
+            params_str = "  ".join(q_parts + p_parts)
+            rows.append((op["method"].upper(), path, params_str))
+    return rows
+
+
+def print_summary(
+    apidef: dict[str, Any],
+    resource_filter: str | None = None,
+    *,
+    file: TextIO | None = None,
+) -> None:
+    """エンドポイント一覧を rich テーブルで出力する。"""
+    rows = build_rows(apidef, resource_filter)
+    if not rows:
+        click_echo = print if file is None else lambda s: file.write(s + "\n")
+        click_echo("(no endpoints found)")
+        return
+
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        box=None,
+        pad_edge=False,
+        show_edge=False,
+    )
+    table.add_column("METHOD", min_width=8)
+    table.add_column("PATH", min_width=24)
+    table.add_column("PARAMETERS")
+    for method, path, params in rows:
+        table.add_row(method, path, params)
+
+    Console(file=file, highlight=False, no_color=(file is not None)).print(table)
+
+
+def format_summary_csv(apidef: dict[str, Any]) -> str:
+    """エンドポイント一覧を CSV 文字列で返す。"""
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow(["method", "path", "query_parameters", "post_parameters"])
+    for path in sorted(apidef.keys()):
+        for op in apidef[path]:
+            q_names = ";".join(p["name"] for p in op.get("query_parameters", []))
+            p_names = ";".join(p["name"] for p in op.get("post_parameters", []))
+            writer.writerow([op["method"].upper(), path, q_names, p_names])
+    return buf.getvalue()
+
+
+def format_endpoint_detail(
+    apidef: dict[str, Any],
+    method: str,
+    template: str,
+) -> str:
+    """特定メソッド+パスのエンドポイント詳細を文字列で返す。"""
+    ops = apidef.get(template, [])
+    op = next((o for o in ops if o["method"] == method), None)
+    if op is None:
+        return f"{method.upper()} {template}: not defined"
+
+    lines = [f"{method.upper()} {template}"]
+    if op.get("query_parameters"):
+        lines.append("  Query parameters:")
+        for p in op["query_parameters"]:
+            lines.append(f"    {_format_param(p, '-q')}")
+    if op.get("post_parameters"):
+        lines.append("  Body parameters:")
+        for p in op["post_parameters"]:
+            lines.append(f"    {_format_param(p, '-p')}")
+    if not op.get("query_parameters") and not op.get("post_parameters"):
+        lines.append("  (no parameters)")
+    return "\n".join(lines)

papycli-0.4.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: papycli
+Version: 0.4.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
+Project-URL: Bug Tracker, https://github.com/tmonj1/papycli/issues
+Author-email: tmonj1 <tmonj1@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,cli,http,openapi,rest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.32
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# papycli — Python CLI for OpenAPI 3.0 REST APIs
+
+`papycli` is an interactive CLI that reads OpenAPI 3.0 specs and lets you call REST API endpoints directly from the terminal.
+
+## Features
+
+- Auto-generates a CLI from any OpenAPI 3.0 spec
+- Shell completion for bash and zsh
+- Register and switch between multiple APIs
+
+## Requirements
+
+| Item | Notes |
+|------|-------|
+| Python | 3.12 or later |
+
+No external tools (e.g. `jq`) required. Works with Python and pip alone.
+
+---
+
+## Installation
+
+```bash
+pip install papycli
+```
+
+### Enable Shell Completion
+
+**bash:**
+
+```bash
+# Add to ~/.bashrc or ~/.bash_profile
+eval "$(papycli completion-script bash)"
+```
+
+**zsh:**
+
+```bash
+# Add to ~/.zshrc
+eval "$(papycli completion-script zsh)"
+```
+
+Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc` to apply.
+
+---
+
+## Quick Start — Petstore Demo
+
+This repository includes a demo using the [Swagger Petstore](https://github.com/swagger-api/swagger-petstore).
+
+### 1. Start the Petstore server
+
+```bash
+docker compose -f examples/docker-compose.yml up -d
+```
+
+The API will be available at `http://localhost:8080/api/v3/`.
+
+### 2. Register the API
+
+```bash
+papycli init examples/petstore-oas3.json
+```
+
+### 3. Try some commands
+
+```bash
+# List available endpoints
+papycli summary
+
+# GET /store/inventory
+papycli get /store/inventory
+
+# GET with a path parameter
+papycli get /pet/99
+
+# GET with a query parameter
+papycli get /pet/findByStatus -q status available
+
+# POST with body parameters
+papycli post /pet -p name "My Dog" -p status available -p photoUrls "http://example.com/photo.jpg"
+
+# POST with a raw JSON body
+papycli post /pet -d '{"name": "My Dog", "status": "available", "photoUrls": ["http://example.com/photo.jpg"]}'
+
+# Array parameter (repeat the same key)
+papycli put /pet -p id 1 -p name "My Dog" -p photoUrls "http://example.com/a.jpg" -p photoUrls "http://example.com/b.jpg" -p status available
+
+# Nested object (dot notation)
+papycli put /pet -p id 1 -p name "My Dog" -p category.id 2 -p category.name "Dogs" -p photoUrls "http://example.com/photo.jpg" -p status available
+
+# DELETE /pet/{petId}
+papycli delete /pet/1
+```
+
+### 4. Tab completion
+
+Once shell completion is enabled, tab completion is available:
+
+```
+$ papycli <TAB>
+  get  post  put  delete  patch
+
+$ papycli get <TAB>
+  /pet/findByStatus  /pet/{petId}  /store/inventory  ...
+
+$ papycli get /pet/findByStatus <TAB>
+  -q  --summary  --help
+
+$ papycli get /pet/findByStatus -q <TAB>
+  status
+
+$ papycli get /pet/findByStatus -q status <TAB>
+  available  pending  sold
+```
+
+---
+
+## Adding Your Own API
+
+### Step 1 — Run `init`
+
+```bash
+papycli init your-api-spec.json
+```
+
+This command will:
+
+1. Resolve all `$ref` references in the OpenAPI spec
+2. Convert the spec to papycli's internal API definition format
+3. Save the result to `$PAPYCLI_CONF_DIR/apis/<name>.json`
+4. Create or update `$PAPYCLI_CONF_DIR/papycli.conf`
+
+The API name is derived from the filename (e.g. `your-api-spec.json` → `your-api-spec`).
+
+### Step 2 — Set the base URL
+
+If the spec contains `servers[0].url`, it is used automatically. Otherwise, edit `$PAPYCLI_CONF_DIR/papycli.conf` and set the `url` field:
+
+```json
+{
+  "default": "your-api-spec",
+  "your-api-spec": {
+    "openapispec": "your-api-spec.json",
+    "apidef": "your-api-spec.json",
+    "url": "https://your-api-base-url/"
+  }
+}
+```
+
+### Managing Multiple APIs
+
+```bash
+# Register multiple APIs
+papycli init petstore-oas3.json
+papycli init myapi.json
+
+# Switch the active API
+papycli use myapi
+
+# Show registered APIs and the current default
+papycli conf
+```
+
+---
+
+## Reference
+
+```
+# API management commands
+papycli init <spec-file>            Initialize an API from an OpenAPI spec file
+papycli use <api-name>              Switch the active API
+papycli conf                        Show current configuration
+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
+papycli completion-script <bash|zsh>  Print a shell completion script
+
+# API call commands
+papycli <method> <resource> [options]
+
+Methods:
+  get | post | put | patch | delete
+
+Options:
+  -H <header: value>      Custom HTTP header (repeatable)
+  -q <name> <value>       Query parameter (repeatable)
+  -p <name> <value>       Body parameter (repeatable)
+                            - Repeat the same key to build a JSON array:
+                              -p tags foo -p tags bar  →  {"tags":["foo","bar"]}
+                            - Use dot notation to build a nested object:
+                              -p category.id 1 -p category.name Dogs
+                              →  {"category":{"id":"1","name":"Dogs"}}
+  -d <json>               Raw JSON body (overrides -p)
+  --summary               Show endpoint info without sending a request
+  --version               Show version
+  --help / -h             Show help
+
+Environment variables:
+  PAPYCLI_CONF_DIR        Path to the config directory (default: ~/.papycli)
+  PAPYCLI_CUSTOM_HEADER   Custom HTTP headers applied to every request.
+                            Separate multiple headers with newlines:
+                            export PAPYCLI_CUSTOM_HEADER=$'Authorization: Bearer token\nX-Tenant: acme'
+```
+
+---
+
+## Limitations
+
+- Request bodies are `application/json` only
+- Array parameters support scalar element types only (arrays of objects are not supported)
+- Dot notation for nested objects supports one level of nesting only
+- Pass auth headers via `-H "Authorization: Bearer token"` or the `PAPYCLI_CUSTOM_HEADER` env var
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/tmonj1/papycli.git
+cd papycli
+pip install -e ".[dev]"
+```
+
+See [CLAUDE.md](CLAUDE.md) for details.

papycli-0.4.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+papycli/__init__.py,sha256=eTFWGmWURp7CDwKBSpxW4XRDgrQtKoHSjETJQ3LB_nw,144
+papycli/api_call.py,sha256=N_1h4NJmVpetQDgzCMXuNZfRNHoLebH2I3_44ERdasA,6261
+papycli/completion.py,sha256=ziwxd7-QOlygbAbiD-aWUURpfISCFw-v_yFPAyQXAA8,5508
+papycli/config.py,sha256=XC7YFXhUgnM0xTZ31UGaARflTeFa_J8Oef97grOje68,3153
+papycli/init_cmd.py,sha256=zAhnxXTE1vnjGAv1jhkmCabngEpmh7wciNXh027nq3w,1377
+papycli/main.py,sha256=rneHHmagwLB1j0AWovwKe5_TxFBtNfrY6hiKOUO16bQ,8179
+papycli/spec_loader.py,sha256=tt57BNpQQgfMe1NJzudo6qQmhWPoXf04keHQ0dJ_K_E,4979
+papycli/summary.py,sha256=ukKTl1HCEZEPJh1slOn6PBOg4ChiOGKR_mryvQzR54g,3768
+papycli-0.4.0.dist-info/METADATA,sha256=UFO42F3_JIbDpAnzusK-q5_81FTIsk4NRsfkT6ZHRxs,6826
+papycli-0.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+papycli-0.4.0.dist-info/entry_points.txt,sha256=4zszSs05Ut8mKUexwRtCahzOlMzirVqJ9BpCkByyJV8,45
+papycli-0.4.0.dist-info/licenses/LICENSE,sha256=hXmISiCnU9vO9lfSKZSITZpnIgyXF2FBGaINpvmjLmc,1067
+papycli-0.4.0.dist-info/RECORD,,

papycli-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

papycli-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+papycli = papycli.main:cli

papycli-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taro Monji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.