apiforge-sdk 0.1.0__py3-none-any.whl

apiforge/__init__.py

@@ -0,0 +1,40 @@
+"""APIForge — Unified interface for multiple APIs.
+
+A plugin-based framework that provides a single, consistent Python API for
+interacting with many external services (GitHub, Discord, Notion, and many
+more). Authentication, HTTP transport, and plugin discovery are handled
+centrally so individual plugins can focus on the service-specific surface.
+"""
+
+from apiforge.core.client import APIForge
+from apiforge.core.config import APIForgeConfig
+from apiforge.core.credentials import CredentialManager
+from apiforge.core.discovery import PluginRegistry
+from apiforge.core.exceptions import (
+    APIForgeError,
+    AuthenticationError,
+    PluginError,
+    PluginNotFoundError,
+    RateLimitError,
+)
+from apiforge.core.metadata import AuthType, OperationMetadata, PluginMetadata
+from apiforge.plugins.base import BasePlugin
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIForge",
+    "APIForgeConfig",
+    "APIForgeError",
+    "AuthType",
+    "AuthenticationError",
+    "BasePlugin",
+    "CredentialManager",
+    "OperationMetadata",
+    "PluginError",
+    "PluginMetadata",
+    "PluginNotFoundError",
+    "PluginRegistry",
+    "RateLimitError",
+    "__version__",
+]

apiforge/cli/__init__.py

@@ -0,0 +1,11 @@
+"""Command-line interface.
+
+The CLI is intentionally thin: it shells out to the library rather
+than re-implementing logic. Commands are organized as subcommands so
+we can add ``generate``, ``install``, ``update`` in later phases
+without breaking compatibility.
+"""
+
+from apiforge.cli.main import cli
+
+__all__ = ["cli"]

apiforge/cli/main.py

@@ -0,0 +1,197 @@
+"""The ``apiforge`` command.
+
+Subcommands:
+
+* ``apiforge list`` — list registered plugins with one-line summaries.
+* ``apiforge plugins`` — same as ``list`` (alias).
+* ``apiforge info <name>`` — show full metadata for a plugin.
+* ``apiforge generate`` — generate a plugin from an OpenAPI spec. (TODO[Phase 2])
+* ``apiforge install`` — install a plugin package. (TODO[Phase 5])
+* ``apiforge update`` — update a plugin package. (TODO[Phase 5])
+
+The future subcommands are wired with ``NotImplementedError`` calls
+so users get a clear error rather than a silent pass. We also pre-
+register the commands in the parser so ``apiforge generate --help``
+works today.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+
+from apiforge import APIForge
+from apiforge.core.exceptions import APIForgeError, PluginNotFoundError
+
+# ---------------------------------------------------------------------- shared
+
+
+def _make_client() -> APIForge:
+    """Factory used by every subcommand."""
+    return APIForge()
+
+
+# ---------------------------------------------------------------------- list
+
+
+@click.command(name="list")
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+def list_cmd(as_json: bool) -> None:
+    """List all registered plugins."""
+    client = _make_client()
+    plugins = []
+    for name in client.list_plugins():
+        meta = client.get_plugin(name).metadata
+        plugins.append(
+            {
+                "name": meta.name,
+                "version": meta.version,
+                "description": meta.description,
+                "auth_type": meta.auth_type.value,
+            }
+        )
+    if as_json:
+        click.echo(json.dumps(plugins, indent=2))
+        return
+    if not plugins:
+        click.echo("No plugins installed.")
+        click.echo("Install one with: pip install <apiforge-plugin-name>")
+        return
+    # Manual width calculation keeps the table readable without pulling
+    # in a third-party table library for one screen of output.
+    name_w = max(len(p["name"]) for p in plugins)
+    ver_w = max(len(p["version"]) for p in plugins)
+    click.echo(f"{'NAME'.ljust(name_w)}  {'VERSION'.ljust(ver_w)}  AUTH   DESCRIPTION")
+    click.echo("-" * (name_w + ver_w + 60))
+    for p in plugins:
+        click.echo(
+            f"{p['name'].ljust(name_w)}  {p['version'].ljust(ver_w)}  "
+            f"{p['auth_type'].ljust(5)}  {p['description']}"
+        )
+
+
+# `apiforge plugins` is an alias for `apiforge list`; we re-use the
+# same function under a different name.
+plugins_cmd = click.command(name="plugins")(list_cmd.callback)  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------- info
+
+
+@click.command(name="info")
+@click.argument("name")
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+def info_cmd(name: str, as_json: bool) -> None:
+    """Show detailed information about a single plugin."""
+    client = _make_client()
+    try:
+        plugin = client.get_plugin(name)
+    except PluginNotFoundError as exc:
+        raise click.ClickException(str(exc)) from exc
+    meta = plugin.metadata
+    payload: dict[str, Any] = {
+        "name": meta.name,
+        "version": meta.version,
+        "description": meta.description,
+        "auth_type": meta.auth_type.value,
+        "base_url": meta.base_url,
+        "openapi_url": meta.openapi_url,
+        "operations": [
+            {
+                "name": op.name,
+                "description": op.description,
+                "async": op.async_,
+                "parameters": op.parameters,
+            }
+            for op in meta.operations
+        ],
+    }
+    if as_json:
+        click.echo(json.dumps(payload, indent=2))
+        return
+    click.echo(f"{payload['name']} v{payload['version']}")
+    click.echo(f"  {payload['description']}")
+    click.echo(f"  Auth: {payload['auth_type']}")
+    if payload["base_url"]:
+        click.echo(f"  Base URL: {payload['base_url']}")
+    if payload["openapi_url"]:
+        click.echo(f"  OpenAPI: {payload['openapi_url']}")
+    if payload["operations"]:
+        click.echo("  Operations:")
+        for op in payload["operations"]:
+            params = ", ".join(op["parameters"]) or "<no params>"
+            desc = f" — {op['description']}" if op["description"] else ""
+            click.echo(f"    - {op['name']}({params}){desc}")
+
+
+# ---------------------------------------------------------------------- future commands
+
+
+@click.command(name="generate")
+@click.argument("spec_source")
+@click.option("--name", "plugin_name", default=None, help="Plugin name override.")
+def generate_cmd(spec_source: str, plugin_name: str | None) -> None:
+    """Generate a plugin from an OpenAPI spec.
+
+    TODO[Phase 2]: implement using the OpenAPIGenerator. Today this
+    raises an error so the parser wiring can be tested.
+    """
+    raise click.UsageError(f"Generation from '{spec_source}' is not implemented yet (Phase 2).")
+
+
+@click.command(name="install")
+@click.argument("package")
+def install_cmd(package: str) -> None:
+    """Install a plugin package from PyPI or a local path.
+
+    TODO[Phase 5]: implement.
+    """
+    raise click.UsageError(f"Install of '{package}' is not implemented yet (Phase 5).")
+
+
+@click.command(name="update")
+@click.argument("package", required=False)
+def update_cmd(package: str | None) -> None:
+    """Update installed plugins.
+
+    TODO[Phase 5]: implement.
+    """
+    target = package or "all plugins"
+    raise click.UsageError(f"Update of '{target}' is not implemented yet (Phase 5).")
+
+
+# ---------------------------------------------------------------------- root
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(package_name="apiforge", prog_name="apiforge")
+def cli() -> None:
+    """APIForge — unified interface for many APIs."""
+
+
+# Register subcommands. Order matters for ``--help`` output: list
+# functionality first, future work last.
+cli.add_command(list_cmd)
+cli.add_command(plugins_cmd)
+cli.add_command(info_cmd)
+cli.add_command(generate_cmd)
+cli.add_command(install_cmd)
+cli.add_command(update_cmd)
+
+
+# ---------------------------------------------------------------------- entrypoint
+
+
+def main() -> None:
+    """Console-script entry point. Catches APIForge errors and exits 1."""
+    try:
+        cli(standalone_mode=True)
+    except APIForgeError as exc:
+        click.echo(f"apiforge: {exc}", err=True)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

apiforge/core/__init__.py

@@ -0,0 +1,29 @@
+"""Core abstractions: configuration, credentials, discovery, errors."""
+
+from apiforge.core.client import APIForge
+from apiforge.core.config import APIForgeConfig
+from apiforge.core.credentials import CredentialManager
+from apiforge.core.discovery import PluginRegistry
+from apiforge.core.exceptions import (
+    APIForgeError,
+    AuthenticationError,
+    PluginError,
+    PluginNotFoundError,
+    RateLimitError,
+)
+from apiforge.core.metadata import AuthType, PluginMetadata
+
+__all__ = [
+    "APIForge",
+    "APIForgeConfig",
+    "APIForgeConfig",
+    "APIForgeError",
+    "AuthType",
+    "AuthenticationError",
+    "CredentialManager",
+    "PluginError",
+    "PluginMetadata",
+    "PluginNotFoundError",
+    "PluginRegistry",
+    "RateLimitError",
+]

apiforge/core/client.py

@@ -0,0 +1,255 @@
+"""The :class:`APIForge` client — the user-facing entry point.
+
+The client owns three long-lived resources and shares them with every
+plugin it instantiates:
+
+1. A :class:`~httpx.AsyncClient` for HTTP transport.
+2. A :class:`~apiforge.core.credentials.CredentialManager` for secrets.
+3. A :class:`~apiforge.core.config.APIForgeConfig` for behavior knobs.
+
+Plugins are accessed by attribute (``client.github``). On first access
+we instantiate the plugin, run its ``setup()`` hook, and cache the
+instance. This is the lazy-initialization pattern — it's faster than
+the alternative and lets plugins do per-instance work (token refresh,
+connection pools) at exactly the right moment.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+import httpx
+
+from apiforge.core.config import APIForgeConfig
+from apiforge.core.credentials import CredentialManager
+from apiforge.core.discovery import PluginRegistry
+from apiforge.core.exceptions import PluginError, PluginNotFoundError
+from apiforge.plugins.base import BasePlugin
+
+
+class APIForge:
+    """The unified API client.
+
+    >>> client = APIForge()
+    >>> client.configure(github_token="ghp_xxx")
+    >>> user = await client.github.get_user("octocat")
+
+    Use the client as an async context manager to ensure the underlying
+    HTTP connection pool is closed cleanly::
+
+        async with APIForge() as client:
+            ...
+
+    The client is reusable: calling :meth:`close` (or exiting the
+    context manager) and then making further calls will reopen the
+    transport.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: APIForgeConfig | None = None,
+        credentials: CredentialManager | None = None,
+        registry: PluginRegistry | None = None,
+    ) -> None:
+        # Configuration ----------------------------------------------------------
+        # Each subsystem has a default; users can override any of them.
+        # We keep dependencies explicit so a test can construct an
+        # APIForge with a fake registry and a fake credential manager.
+        self.config = config or APIForgeConfig()
+        self.credentials = credentials or CredentialManager()
+        self.registry = registry or PluginRegistry()
+
+        # State -------------------------------------------------------------------
+        # ``_http`` is created lazily because constructing an httpx
+        # client at import time would require an async context, which
+        # conflicts with synchronous user code paths.
+        self._http: httpx.AsyncClient | None = None
+        self._plugins: dict[str, BasePlugin] = {}
+
+    # ------------------------------------------------------------------ configuration
+
+    def configure(self, **credentials: str) -> None:
+        """Set explicit credentials for one or more plugins.
+
+        Unknown keyword arguments are still recorded under the literal
+        name, so users can pass ``client.configure(my_custom_token="...")``
+        even if no plugin with that exact name is registered yet —
+        this lets a script populate credentials for a plugin installed
+        later in the same process.
+
+        Examples
+        --------
+        >>> client.configure(
+        ...     github_token="ghp_xxx",
+        ...     discord_token="...",
+        ...     notion_token="...",
+        ... )
+        """
+        for key, value in credentials.items():
+            if not isinstance(value, str):
+                msg = f"Credential for '{key}' must be a string, got {type(value).__name__}"
+                raise PluginError(msg)
+            # Strip ``_token`` suffix if present so users can pass
+            # either ``github_token`` or ``github``.
+            name = key.removesuffix("_token")
+            self.credentials.set(name, value)
+
+    # ------------------------------------------------------------------ transport
+
+    @property
+    def http(self) -> httpx.AsyncClient:
+        """The shared :class:`httpx.AsyncClient`.
+
+        Lazily constructed with the configured timeout, SSL, and
+        user-agent. Plugins should use this rather than creating their
+        own clients — sharing the pool avoids socket exhaustion.
+        """
+        if self._http is None:
+            self._http = httpx.AsyncClient(
+                timeout=httpx.Timeout(self.config.timeout),
+                verify=self.config.verify_ssl,
+                headers={"User-Agent": self.config.user_agent},
+                http2=False,  # opt-in via explicit config in the future
+            )
+        return self._http
+
+    async def close(self) -> None:
+        """Close the HTTP client and call ``teardown`` on every plugin.
+
+        Safe to call multiple times.
+        """
+        for name, plugin in list(self._plugins.items()):
+            try:
+                await plugin.teardown()
+            except Exception:  # noqa: S110
+                # A misbehaving teardown should not prevent others
+                # from running, and should not prevent the HTTP
+                # client from closing.
+                pass
+            finally:
+                self._plugins.pop(name, None)
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    async def __aenter__(self) -> APIForge:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    # ------------------------------------------------------------------ plugin access
+
+    def get_plugin(self, name: str) -> BasePlugin:
+        """Return the instantiated plugin for ``name``.
+
+        First access instantiates the plugin and runs its ``setup()``
+        hook; subsequent accesses return the cached instance.
+
+        Raises :class:`PluginNotFoundError` if the name is unknown.
+        """
+        if name in self._plugins:
+            return self._plugins[name]
+        cls = self.registry.get(name)  # raises PluginNotFoundError
+        try:
+            instance = cls(self)
+        except Exception as exc:
+            msg = f"Failed to instantiate plugin '{name}': {exc}"
+            raise PluginError(msg, plugin=name) from exc
+        self._plugins[name] = instance
+        # We deliberately do NOT call setup() synchronously here.
+        # Plugins that need a setup step are usually async (token
+        # refresh, keyring validation). The SyncProxy takes care of
+        # awaiting it lazily on first use.
+        return instance
+
+    def has_plugin(self, name: str) -> bool:
+        """Return ``True`` if a plugin named ``name`` is registered."""
+        return name in self.registry
+
+    def list_plugins(self) -> list[str]:
+        """Return the names of all registered plugins, sorted."""
+        return self.registry.names()
+
+    # ------------------------------------------------------------------ attribute proxy
+
+    def __getattr__(self, name: str) -> Any:
+        # ``__getattr__`` is only called when normal lookup fails, so
+        # methods like ``close`` and properties like ``http`` still
+        # resolve normally. Plugin names are deliberately lower-case
+        # to match the documented example (``client.github``).
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            return SyncProxy(self.get_plugin(name))
+        except PluginNotFoundError:
+            raise AttributeError(
+                f"{type(self).__name__!s} has no attribute {name!r}. "
+                f"Did you mean one of: {', '.join(self.list_plugins()) or '<none>'}?"
+            ) from None
+
+
+class SyncProxy:
+    """Wraps an async plugin so sync callers can use it transparently.
+
+    Every attribute access on the proxy returns a coroutine runner
+    for the corresponding async method on the underlying plugin.
+    This means::
+
+        client.github.get_user("octocat")
+
+    is exactly equivalent to::
+
+        asyncio.run(client.github.get_user("octocat"))
+
+    If the underlying plugin mixes sync and async methods, sync ones
+    are passed through directly. We detect sync methods by checking
+    the class's ``__dict__`` rather than inspecting the coroutine
+    flag, because some plugins may legitimately expose coroutine-
+    returning callables that aren't ``async def`` (e.g. methods
+    built dynamically).
+    """
+
+    __slots__ = ("_plugin",)
+
+    def __init__(self, plugin: BasePlugin) -> None:
+        self._plugin = plugin
+
+    def __getattr__(self, name: str) -> Any:
+        attr = getattr(self._plugin, name)
+        # Non-callable attributes: pass through (e.g. ``plugin.metadata``).
+        if not callable(attr):
+            return attr
+        # Sync methods are passed through untouched. This means a plugin
+        # that mixes sync and async methods just works — the proxy only
+        # wraps the coroutine-returning ones.
+        if not inspect.iscoroutinefunction(attr):
+            return attr
+        return _SyncMethod(self._plugin, name)
+
+    def __repr__(self) -> str:
+        return f"SyncProxy({self._plugin!r})"
+
+
+class _SyncMethod:
+    """A bound, sync-callable wrapper around an async plugin method.
+
+    Holding a reference to the plugin (not the bound method) means
+    that if the plugin instance is re-created we get a fresh method
+    — small but important for tests that swap out the registry.
+    """
+
+    __slots__ = ("_name", "_plugin")
+
+    def __init__(self, plugin: BasePlugin, name: str) -> None:
+        self._plugin = plugin
+        self._name = name
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        # Importing here avoids a top-level asyncio dependency.
+        import asyncio
+
+        method = getattr(self._plugin, self._name)
+        return asyncio.run(method(*args, **kwargs))

apiforge/core/config.py

@@ -0,0 +1,62 @@
+"""Runtime configuration for APIForge.
+
+We use ``pydantic-settings`` so that configuration can be supplied via:
+
+1. ``APIForge.configure(...)`` keyword arguments (highest priority)
+2. Environment variables prefixed with ``APIFORGE_``
+3. A ``.env`` file in the working directory
+
+This layered approach lets scripts and libraries configure explicitly,
+while deployed processes (CI, containers) work via environment without
+any code changes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class APIForgeConfig(BaseSettings):
+    """Global configuration shared by the client and all plugins.
+
+    Per-plugin credentials live on :class:`~apiforge.core.credentials.CredentialManager`,
+    not here — this object holds cross-cutting knobs (timeouts, retries,
+    log level) that affect every plugin uniformly.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="APIFORGE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    timeout: float = Field(
+        default=30.0,
+        description="Default HTTP timeout in seconds for plugin requests.",
+        gt=0,
+    )
+    max_retries: int = Field(
+        default=3,
+        description="Default number of retries for transient failures.",
+        ge=0,
+    )
+    verify_ssl: bool = Field(
+        default=True,
+        description="Whether to verify upstream TLS certificates.",
+    )
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level (DEBUG, INFO, WARNING, ERROR).",
+    )
+    user_agent: str = Field(
+        default="apiforge/0.1.0",
+        description="User-Agent header sent on every request.",
+    )
+    extra: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Free-form key/value bag for plugin-specific settings.",
+    )