pyholded 0.1.0__py3-none-any.whl

pyholded/__init__.py

@@ -0,0 +1,55 @@
+"""pyholded — a modular Python client and CLI for the complete Holded API."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from ._registry import Endpoint, Resource
+from .client import HoldedClient
+from .config import Config, resolve_accounts, resolve_config, resolve_token
+from .endpoints import REGISTRY
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigError,
+    EndpointNotFoundError,
+    HoldedError,
+    NotFoundError,
+    RateLimitError,
+)
+from .multi import MultiClient
+from .output import OutputFormat, render, to_json, to_toon
+
+
+def _detect_version() -> str:
+    try:
+        return metadata.version("pyholded")
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+__version__ = _detect_version()
+
+__all__ = [
+    "REGISTRY",
+    "APIError",
+    "AuthenticationError",
+    "Config",
+    "ConfigError",
+    "Endpoint",
+    "EndpointNotFoundError",
+    "HoldedClient",
+    "HoldedError",
+    "MultiClient",
+    "NotFoundError",
+    "OutputFormat",
+    "RateLimitError",
+    "Resource",
+    "__version__",
+    "render",
+    "resolve_accounts",
+    "resolve_config",
+    "resolve_token",
+    "to_json",
+    "to_toon",
+]

pyholded/_proxies.py

@@ -0,0 +1,73 @@
+"""Attribute-based dispatch for the registry-driven clients.
+
+These proxies turn ``caller.<resource>.<operation>(**kwargs)`` into a single
+:meth:`call` on whatever caller they are bound to. They hold no API knowledge
+of their own — the endpoint registry is the single source of truth — and work
+identically for the single-account :class:`~pyholded.client.HoldedClient` and
+the fan-out :class:`~pyholded.multi.MultiClient`, since both expose the same
+:meth:`call` contract.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from ._registry import Endpoint, Resource
+
+
+class _Caller(Protocol):
+    """Anything the proxies can dispatch a registered operation to."""
+
+    def call(
+        self,
+        resource: str,
+        operation: str,
+        *,
+        path_params: dict[str, str] | None = ...,
+        params: dict[str, Any] | None = ...,
+        data: Any = ...,
+        paginate: bool = ...,
+    ) -> Any: ...
+
+
+class ResourceProxy:
+    """Attribute access wrapper for a single resource's operations."""
+
+    def __init__(self, caller: _Caller, resource: Resource) -> None:
+        self._caller = caller
+        self._resource = resource
+
+    def __getattr__(self, name: str) -> OperationProxy:
+        endpoint = self._resource.get(name)
+        if endpoint is None:
+            raise AttributeError(name)
+        return OperationProxy(self._caller, self._resource.name, endpoint)
+
+    def __dir__(self) -> list[str]:
+        return [*super().__dir__(), *self._resource.operations]
+
+
+class OperationProxy:
+    """A bound, callable API operation."""
+
+    def __init__(self, caller: _Caller, resource: str, endpoint: Endpoint) -> None:
+        self._caller = caller
+        self._resource = resource
+        self._endpoint = endpoint
+
+    def __call__(
+        self,
+        *,
+        params: dict[str, Any] | None = None,
+        data: Any = None,
+        paginate: bool = False,
+        **path_params: str,
+    ) -> Any:
+        return self._caller.call(
+            self._resource,
+            self._endpoint.name,
+            path_params=path_params,
+            params=params,
+            data=data,
+            paginate=paginate,
+        )

pyholded/_registry.py

@@ -0,0 +1,84 @@
+"""Declarative model for the Holded API surface.
+
+Every endpoint is described once, as data. Both the high-level client
+(:mod:`pyholded.client`) and the command-line interface (:mod:`pyholded.cli`)
+are generated from this registry, so the API surface has a single source of truth.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+_PLACEHOLDER = re.compile(r"\{([^}]+)\}")
+
+HTTPMethod = str  # one of GET, POST, PUT, DELETE
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    """A single API operation within a resource."""
+
+    name: str
+    method: HTTPMethod
+    path: str
+    description: str = ""
+    query_params: tuple[str, ...] = ()
+    has_body: bool = False
+    binary: bool = False
+
+    @property
+    def path_params(self) -> tuple[str, ...]:
+        """Names of the ``{placeholder}`` segments in :attr:`path`."""
+        return tuple(_PLACEHOLDER.findall(self.path))
+
+
+@dataclass(frozen=True, slots=True)
+class Resource:
+    """A named group of related endpoints belonging to one API module."""
+
+    module: str
+    name: str
+    description: str
+    endpoints: tuple[Endpoint, ...]
+    operations: dict[str, Endpoint] = field(init=False, default_factory=dict, compare=False)
+
+    def __post_init__(self) -> None:
+        # frozen dataclass: populate the lookup table without reassigning the field.
+        self.operations.update({ep.name: ep for ep in self.endpoints})
+
+    def get(self, operation: str) -> Endpoint | None:
+        return self.operations.get(operation)
+
+
+def build_index(resources: tuple[Resource, ...]) -> dict[str, Resource]:
+    """Index resources by name, rejecting duplicates."""
+    index: dict[str, Resource] = {}
+    for resource in resources:
+        if resource.name in index:
+            raise ValueError(f"Duplicate resource name: {resource.name}")
+        index[resource.name] = resource
+    return index
+
+
+def render_path(template: str, path_params: dict[str, str]) -> str:
+    """Substitute ``{placeholders}`` in ``template`` with ``path_params`` values.
+
+    Each value is percent-encoded as a single path segment, so an id containing
+    ``/``, ``#`` or ``?`` cannot corrupt the request URL.
+    """
+    missing: list[str] = []
+
+    def _sub(match: re.Match[str]) -> str:
+        key = match.group(1)
+        value = path_params.get(key)
+        if value is None or value == "":
+            missing.append(key)
+            return ""
+        return quote(str(value), safe="")
+
+    rendered = _PLACEHOLDER.sub(_sub, template)
+    if missing:
+        raise KeyError(f"Missing path parameter(s): {', '.join(missing)}")
+    return rendered.lstrip("/")

pyholded/cli.py

@@ -0,0 +1,329 @@
+"""Command-line interface for the Holded API.
+
+The CLI mirrors the endpoint registry: every resource is a command group and
+every operation a subcommand whose path/query parameters are flags. Output is
+selectable per invocation (``--output rich|json|toon``)::
+
+    holded invoices list --limit 50
+    holded contacts get --id 0123456789abcdef01234567 --output json
+    holded --account acme contacts list          # one named account
+    holded --all-accounts contacts list          # fan out to every account
+    holded accounts                               # list configured accounts
+    holded raw GET taxes --output toon
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+from ._registry import Endpoint, Resource
+from .client import HoldedClient
+from .config import resolve_accounts
+from .endpoints import REGISTRY
+from .exceptions import HoldedError
+from .multi import MultiClient
+from .output import OutputFormat, render
+
+
+class _Context:
+    """Shared CLI state carried on the click context object."""
+
+    def __init__(
+        self,
+        token: str | None,
+        config: Path | None,
+        base_url: str | None,
+        output: str,
+        timeout: float,
+        account: str | None,
+        all_accounts: bool,
+    ) -> None:
+        self.token = token
+        self.config = config
+        self.base_url = base_url
+        self.output = OutputFormat(output)
+        self.timeout = timeout
+        self.account = account
+        self.all_accounts = all_accounts
+
+    def client(self) -> HoldedClient:
+        return HoldedClient(
+            self.token,
+            account=self.account,
+            base_url=self.base_url,
+            config_path=self.config,
+            timeout=self.timeout,
+        )
+
+    def multi(self) -> MultiClient:
+        return MultiClient.from_accounts(config_path=self.config, timeout=self.timeout)
+
+    def run_call(self, resource: str, operation: str, **kwargs: Any) -> Any:
+        """Run an operation on the selected account, or fan out to all accounts."""
+        if self.all_accounts:
+            with self.multi() as multi:
+                return multi.call(resource, operation, **kwargs)
+        with self.client() as client:
+            return client.call(resource, operation, **kwargs)
+
+    def run_request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if self.all_accounts:
+            with self.multi() as multi:
+                return multi.request(method, path, **kwargs)
+        with self.client() as client:
+            return client.request(method, path, **kwargs)
+
+    def resolve_format(self, override: str | None) -> OutputFormat:
+        """Per-command --output wins over the group-level default."""
+        return OutputFormat(override) if override else self.output
+
+
+_OUTPUT_CHOICES = [fmt.value for fmt in OutputFormat]
+
+
+def _output_option() -> click.Option:
+    return click.Option(
+        ["-o", "--output"],
+        type=click.Choice(_OUTPUT_CHOICES),
+        default=None,
+        help="Output format (overrides the global default).",
+    )
+
+
+def _to_flag(name: str) -> str:
+    out = [name[0].lower()]
+    for char in name[1:]:
+        if char.isupper():
+            out.append("-")
+            out.append(char.lower())
+        else:
+            out.append(char)
+    return "--" + "".join(out).replace("_", "-")
+
+
+def _dest(name: str) -> str:
+    return _to_flag(name)[2:].replace("-", "_")
+
+
+def _kebab(name: str) -> str:
+    return _to_flag(name)[2:]
+
+
+def _parse_data(data: str | None, fields: tuple[str, ...]) -> Any:
+    body: Any = None
+    if data is not None:
+        if data.startswith("@"):
+            path = Path(data[1:])
+            try:
+                text = path.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise click.BadParameter(f"cannot read {path}: {exc}", param_hint="--data") from exc
+        else:
+            text = data
+        try:
+            body = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise click.BadParameter(f"invalid JSON: {exc}", param_hint="--data") from exc
+    if fields:
+        merged: dict[str, str] = body if isinstance(body, dict) else {}
+        for item in fields:
+            key, _, value = item.partition("=")
+            merged[key] = value
+        body = merged
+    return body
+
+
+def _operation_command(resource: Resource, endpoint: Endpoint) -> click.Command:
+    params: list[click.Parameter] = []
+    path_dests = {name: _dest(name) for name in endpoint.path_params}
+    query_dests = {name: _dest(name) for name in endpoint.query_params}
+
+    for name in endpoint.path_params:
+        params.append(click.Option([_to_flag(name)], required=True, help="path parameter"))
+    for name in endpoint.query_params:
+        params.append(click.Option([_to_flag(name)], required=False, help="query parameter"))
+    if endpoint.has_body:
+        params.append(
+            click.Option(
+                ["--data"],
+                required=False,
+                help="JSON request body, or @file.json to read from a file",
+            )
+        )
+        params.append(
+            click.Option(
+                ["--field", "fields"],
+                multiple=True,
+                help="body field as key=value (repeatable)",
+            )
+        )
+    paginates = endpoint.method == "GET" and not endpoint.binary
+    if paginates:
+        params.append(
+            click.Option(
+                ["--all", "fetch_all"],
+                is_flag=True,
+                help="follow the cursor and fetch every page",
+            )
+        )
+    params.append(_output_option())
+
+    def callback(**kwargs: Any) -> None:
+        ctx = click.get_current_context()
+        state: _Context = ctx.obj
+        path_params = {
+            name: kwargs[dest] for name, dest in path_dests.items() if kwargs.get(dest) is not None
+        }
+        query = {
+            name: kwargs[dest] for name, dest in query_dests.items() if kwargs.get(dest) is not None
+        }
+        data = (
+            _parse_data(kwargs.get("data"), kwargs.get("fields", ())) if endpoint.has_body else None
+        )
+        result = state.run_call(
+            resource.name,
+            endpoint.name,
+            path_params=path_params,
+            params=query or None,
+            data=data,
+            paginate=bool(kwargs.get("fetch_all")),
+        )
+        render(result, state.resolve_format(kwargs.get("output")))
+
+    return click.Command(
+        name=_kebab(endpoint.name),
+        params=params,
+        callback=callback,
+        help=endpoint.description or f"{endpoint.method} {endpoint.path}",
+        short_help=endpoint.description,
+    )
+
+
+def _resource_group(resource: Resource) -> click.Group:
+    group = click.Group(
+        name=resource.name,
+        help=f"[{resource.module}] {resource.description}",
+    )
+    for endpoint in resource.endpoints:
+        group.add_command(_operation_command(resource, endpoint))
+    return group
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("--token", envvar="HOLDED_TOKEN", help="Holded API token (PAT).")
+@click.option("-a", "--account", help="Use a named account from env/config.")
+@click.option("--all-accounts", is_flag=True, help="Run on every configured account.")
+@click.option(
+    "--config",
+    type=click.Path(exists=False, dir_okay=False, path_type=Path),
+    help="Path to a TOML config file.",
+)
+@click.option("--base-url", help="Override the API base URL.")
+@click.option(
+    "-o",
+    "--output",
+    type=click.Choice(_OUTPUT_CHOICES),
+    default=OutputFormat.RICH.value,
+    show_default=True,
+    help="Default output format.",
+)
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="HTTP timeout (s).")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    token: str | None,
+    account: str | None,
+    all_accounts: bool,
+    config: Path | None,
+    base_url: str | None,
+    output: str,
+    timeout: float,
+) -> None:
+    """Modular command-line client for the complete Holded API."""
+    ctx.obj = _Context(token, config, base_url, output, timeout, account, all_accounts)
+
+
+@cli.command(name="resources")
+@click.option("-o", "--output", type=click.Choice(_OUTPUT_CHOICES), default=None)
+@click.pass_context
+def list_resources(ctx: click.Context, output: str | None) -> None:
+    """List every resource and its operations."""
+    state: _Context = ctx.obj
+    overview = {
+        resource.name: {
+            "module": resource.module,
+            "operations": [ep.name for ep in resource.endpoints],
+        }
+        for resource in REGISTRY
+    }
+    render(overview, state.resolve_format(output))
+
+
+@cli.command(name="raw")
+@click.argument("method")
+@click.argument("path")
+@click.option("--param", "params", multiple=True, help="query parameter key=value (repeatable)")
+@click.option("--data", help="JSON request body, or @file.json")
+@click.option("--binary", is_flag=True, help="treat the response as raw bytes")
+@click.option("-o", "--output", type=click.Choice(_OUTPUT_CHOICES), default=None)
+@click.pass_context
+def raw(
+    ctx: click.Context,
+    method: str,
+    path: str,
+    params: tuple[str, ...],
+    data: str | None,
+    binary: bool,
+    output: str | None,
+) -> None:
+    """Call an arbitrary endpoint: METHOD and PATH (relative to the API base URL)."""
+    state: _Context = ctx.obj
+    query = dict(item.partition("=")[::2] for item in params) or None
+    body = _parse_data(data, ()) if data else None
+    result = state.run_request(method, path.lstrip("/"), params=query, json=body, binary=binary)
+    if binary and isinstance(result, bytes):
+        sys.stdout.buffer.write(result)
+        return
+    render(result, state.resolve_format(output))
+
+
+@cli.command(name="accounts")
+@click.option("-o", "--output", type=click.Choice(_OUTPUT_CHOICES), default=None)
+@click.pass_context
+def list_accounts(ctx: click.Context, output: str | None) -> None:
+    """List configured accounts (names and base URLs; tokens are never shown)."""
+    state: _Context = ctx.obj
+    accounts = resolve_accounts(state.config)
+    overview = [
+        {"account": name, "base_url": cfg.base_url} for name, cfg in sorted(accounts.items())
+    ]
+    render(overview, state.resolve_format(output))
+
+
+def _register_resources() -> None:
+    for resource in REGISTRY:
+        cli.add_command(_resource_group(resource))
+
+
+def main() -> None:
+    """Console-script entry point."""
+    _register_resources()
+    try:
+        cli.main(standalone_mode=False)
+    except HoldedError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    except click.ClickException as exc:
+        exc.show()
+        sys.exit(exc.exit_code)
+    except click.exceptions.Abort:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

pyholded/client.py

@@ -0,0 +1,159 @@
+"""High-level Holded client.
+
+Resources and their operations are exposed as attributes generated from the
+endpoint registry::
+
+    client = HoldedClient()                       # token from env or config file
+    invoices = client.invoices.list(params={"limit": 50})
+    contact = client.contacts.get(id="0123456789abcdef01234567")
+
+Any endpoint can also be reached generically via :meth:`HoldedClient.request`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ._proxies import ResourceProxy
+from ._registry import Endpoint, Resource, build_index, render_path
+from .config import resolve_config
+from .endpoints import REGISTRY
+from .exceptions import EndpointNotFoundError
+from .transport import DEFAULT_TIMEOUT, Transport
+
+
+class HoldedClient:
+    """Entry point to the Holded API."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        account: str | None = None,
+        base_url: str | None = None,
+        config_path: Path | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Transport | None = None,
+    ) -> None:
+        config = resolve_config(token, base_url=base_url, config_path=config_path, account=account)
+        self._account = config.name
+        self._transport = transport or Transport(
+            config.token, base_url=config.base_url, timeout=timeout
+        )
+        self._resources = build_index(REGISTRY)
+
+    @property
+    def account(self) -> str:
+        """The name of the account this client is bound to."""
+        return self._account
+
+    @property
+    def resources(self) -> dict[str, Resource]:
+        """The full resource index, keyed by resource name."""
+        return self._resources
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        binary: bool = False,
+    ) -> Any:
+        """Call an arbitrary endpoint (escape hatch for anything not modelled)."""
+        return self._transport.request(method, path, params=params, json=json, binary=binary)
+
+    def call(
+        self,
+        resource: str,
+        operation: str,
+        *,
+        path_params: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        data: Any = None,
+        paginate: bool = False,
+    ) -> Any:
+        """Invoke a registered operation by name (used by the CLI).
+
+        When ``paginate`` is true on a GET that returns a cursor-paginated
+        ``{items, cursor, has_more}`` body, every page is fetched and the
+        merged ``items`` list is returned.
+        """
+        endpoint = self._lookup(resource, operation)
+        path_params = path_params or {}
+        unknown = set(path_params) - set(endpoint.path_params)
+        if unknown:
+            raise TypeError(
+                f"unexpected argument(s) {sorted(unknown)} for {resource}.{operation}; "
+                f"pass query parameters via params=, the request body via data="
+            )
+        path = render_path(endpoint.path, path_params)
+        if paginate and endpoint.method == "GET" and not endpoint.binary:
+            return self._paginate(path, params)
+        return self._invoke(endpoint, path, params, data)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> HoldedClient:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def __getattr__(self, name: str) -> ResourceProxy:
+        # Only reached for attributes not found normally.
+        resources = self.__dict__.get("_resources", {})
+        resource = resources.get(name)
+        if resource is None:
+            raise AttributeError(name)
+        return ResourceProxy(self, resource)
+
+    def __dir__(self) -> list[str]:
+        return [*super().__dir__(), *self._resources]
+
+    def _lookup(self, resource: str, operation: str) -> Endpoint:
+        res = self._resources.get(resource)
+        if res is None:
+            raise EndpointNotFoundError(f"Unknown resource: {resource}")
+        endpoint = res.get(operation)
+        if endpoint is None:
+            raise EndpointNotFoundError(f"Unknown operation '{operation}' on resource '{resource}'")
+        return endpoint
+
+    def _invoke(
+        self,
+        endpoint: Endpoint,
+        path: str,
+        params: dict[str, Any] | None,
+        data: Any,
+    ) -> Any:
+        body = data if endpoint.has_body else None
+        return self._transport.request(
+            endpoint.method,
+            path,
+            params=params,
+            json=body,
+            binary=endpoint.binary,
+        )
+
+    def _paginate(self, path: str, params: dict[str, Any] | None) -> list[Any]:
+        items: list[Any] = []
+        query = dict(params or {})
+        seen_cursors: set[str] = set()
+        while True:
+            page = self._transport.request("GET", path, params=query)
+            if not isinstance(page, dict) or "items" not in page:
+                # Not a paginated shape; hand the raw body back as a single item.
+                return [page]
+            items.extend(page["items"])
+            cursor = page.get("cursor")
+            if not page.get("has_more") or not cursor:
+                return items
+            # Defend against an API that keeps returning the same cursor.
+            if cursor in seen_cursors:
+                return items
+            seen_cursors.add(cursor)
+            query["cursor"] = cursor