dockerhub-api 0.1.0__py3-none-any.whl

dockerhub_api/__init__.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+from typing import Any
+
+__all__: list[str] = []
+
+CORE_MODULES: list[str] = [
+    "dockerhub_api.dockerhub_input_models",
+    "dockerhub_api.dockerhub_response_models",
+    "dockerhub_api.api_client",
+    "dockerhub_api.auth",
+]
+
+OPTIONAL_MODULES = {
+    "dockerhub_api.agent_server": "agent",
+    "dockerhub_api.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+# Eagerly import core modules (keeps API wrappers fast & light)
+for module_name in CORE_MODULES:
+    if module_name:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+
+# Dynamic/lazy loading of optional modules (agent_server, mcp_server)
+_loaded_optional_modules: dict[str, Any] = {}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    # Handle availability flags dynamically without eager imports
+    if name == "_MCP_AVAILABLE":
+        mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
+        if mcp_key:
+            return _import_module_safely(mcp_key) is not None
+        return False
+    if name == "_AGENT_AVAILABLE":
+        agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
+        if agent_key:
+            return _import_module_safely(agent_key) is not None
+        return False
+
+    # Check optional modules
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            if module is not None:
+                _loaded_optional_modules[module_name] = module
+                _expose_members(module)
+
+        module = _loaded_optional_modules.get(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

dockerhub_api/__main__.py

@@ -0,0 +1,4 @@
+from dockerhub_api.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

dockerhub_api/agent_server.py

@@ -0,0 +1,92 @@
+#!/usr/bin/python
+"""Docker Hub A2A agent server.
+
+CONCEPT:HUB-1.6 — A2A agent server. A Pydantic-AI graph agent over the
+Docker Hub MCP tool surface, exposed via agent-utilities'
+``create_agent_server`` (A2A + AG-UI web interface).
+"""
+
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.1.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv(
+        "DEFAULT_AGENT_NAME", meta.get("name", "Dockerhub Api")
+    )
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get(
+            "description",
+            "AI agent for Docker Hub management.",
+        ),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    print(f"{DEFAULT_AGENT_NAME} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    # Start server using the auto-discovery pattern (from mcp_config.json)
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()

dockerhub_api/api/__init__.py

@@ -0,0 +1 @@
+"""Per-domain Docker Hub API client mixins."""

dockerhub_api/api/api_client_access_tokens.py

@@ -0,0 +1,77 @@
+"""Personal access token endpoints (``/v2/access-tokens``).
+
+CONCEPT:HUB-1.1 — JWT auth lifecycle (PAT management).
+"""
+
+from typing import Any
+
+from dockerhub_api.api.api_client_base import DockerHubApiBase
+from dockerhub_api.dockerhub_input_models import (
+    AccessTokenCreateModel,
+    AccessTokenListModel,
+    AccessTokenModel,
+    AccessTokenPatchModel,
+)
+from dockerhub_api.dockerhub_response_models import (
+    AccessToken,
+    AccessTokenPage,
+    validate_lenient,
+)
+
+
+class DockerHubApiAccessTokens(DockerHubApiBase):
+    """CRUD for personal access tokens."""
+
+    def get_access_tokens(
+        self, page: int | None = None, page_size: int | None = None
+    ) -> dict[str, Any]:
+        """List the personal access tokens of the authenticated user."""
+        model = AccessTokenListModel(page=page, page_size=page_size)
+        envelope = self._request(
+            "GET", "/v2/access-tokens", params=model.api_parameters
+        )
+        envelope["data"] = validate_lenient(AccessTokenPage, envelope["data"])
+        return envelope
+
+    def create_access_token(
+        self, token_label: str, scopes: list[str]
+    ) -> dict[str, Any]:
+        """Create a personal access token.
+
+        Valid scopes: ``repo:admin``, ``repo:write``, ``repo:read``,
+        ``repo:public_read``. The plaintext token is only returned once,
+        in this response.
+        """
+        model = AccessTokenCreateModel(token_label=token_label, scopes=scopes)
+        envelope = self._request("POST", "/v2/access-tokens", json=model.payload)
+        envelope["data"] = validate_lenient(AccessToken, envelope["data"])
+        return envelope
+
+    def get_access_token(self, uuid: str) -> dict[str, Any]:
+        """Get one personal access token by UUID."""
+        model = AccessTokenModel(uuid=uuid)
+        envelope = self._request("GET", f"/v2/access-tokens/{model.uuid}")
+        envelope["data"] = validate_lenient(AccessToken, envelope["data"])
+        return envelope
+
+    def update_access_token(
+        self,
+        uuid: str,
+        token_label: str | None = None,
+        is_active: bool | None = None,
+    ) -> dict[str, Any]:
+        """Patch a personal access token's label and/or active state."""
+        model = AccessTokenPatchModel(
+            uuid=uuid, token_label=token_label, is_active=is_active
+        )
+        envelope = self._request(
+            "PATCH", f"/v2/access-tokens/{model.uuid}", json=model.payload
+        )
+        envelope["data"] = validate_lenient(AccessToken, envelope["data"])
+        return envelope
+
+    def delete_access_token(self, uuid: str) -> dict[str, Any]:
+        """Delete a personal access token. Destructive — gated."""
+        self._guard_destructive("delete_access_token")
+        model = AccessTokenModel(uuid=uuid)
+        return self._request("DELETE", f"/v2/access-tokens/{model.uuid}")

dockerhub_api/api/api_client_audit_logs.py

@@ -0,0 +1,56 @@
+"""Audit log endpoints (``/v2/auditlogs``).
+
+CONCEPT:HUB-1.0 — core wrapper.
+"""
+
+from typing import Any
+
+from dockerhub_api.api.api_client_base import DockerHubApiBase
+from dockerhub_api.dockerhub_input_models import AuditLogModel
+from dockerhub_api.dockerhub_response_models import (
+    AuditLogActions,
+    AuditLogPage,
+    validate_lenient,
+)
+
+
+class DockerHubApiAuditLogs(DockerHubApiBase):
+    """Read access to an account's audit trail."""
+
+    def get_audit_logs(
+        self,
+        account: str,
+        action: str | None = None,
+        name: str | None = None,
+        actor: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        page: int | None = None,
+        page_size: int | None = None,
+    ) -> dict[str, Any]:
+        """List audit-log events for a namespace.
+
+        Filters: ``action``, ``name`` (object), ``actor`` (username), and a
+        ``from_date``/``to_date`` RFC 3339 window (sent as ``from``/``to``).
+        """
+        model = AuditLogModel(
+            account=account,
+            action=action,
+            name=name,
+            actor=actor,
+            from_date=from_date,
+            to_date=to_date,
+            page=page,
+            page_size=page_size,
+        )
+        envelope = self._request(
+            "GET", f"/v2/auditlogs/{model.account}", params=model.api_parameters
+        )
+        envelope["data"] = validate_lenient(AuditLogPage, envelope["data"])
+        return envelope
+
+    def get_audit_log_actions(self, account: str) -> dict[str, Any]:
+        """List the audit-log action names available for a namespace."""
+        envelope = self._request("GET", f"/v2/auditlogs/{account}/actions")
+        envelope["data"] = validate_lenient(AuditLogActions, envelope["data"])
+        return envelope

dockerhub_api/api/api_client_auth.py

@@ -0,0 +1,80 @@
+"""Docker Hub authentication endpoints.
+
+CONCEPT:HUB-1.1 — JWT auth lifecycle (endpoint wrappers).
+"""
+
+import warnings
+from typing import Any
+
+from dockerhub_api.api.api_client_base import DockerHubApiBase
+from dockerhub_api.dockerhub_input_models import (
+    AuthTokenModel,
+    LoginModel,
+    TwoFactorLoginModel,
+)
+from dockerhub_api.dockerhub_response_models import (
+    JwtToken,
+    LoginResult,
+    validate_lenient,
+)
+
+
+class DockerHubApiAuth(DockerHubApiBase):
+    """``/v2/auth/token``, ``/v2/users/login``, ``/v2/users/2fa-login``."""
+
+    def create_auth_token(self, identifier: str, secret: str) -> dict[str, Any]:
+        """Mint a short-lived JWT bearer from an identifier + secret.
+
+        The secret may be an account password, a personal access token
+        (``dckr_pat_*``), or an organization access token.
+        """
+        model = AuthTokenModel(identifier=identifier, secret=secret)
+        envelope = self._request("POST", "/v2/auth/token", json=model.payload)
+        envelope["data"] = validate_lenient(JwtToken, envelope["data"])
+        return envelope
+
+    def login(self, username: str, password: str) -> dict[str, Any]:
+        """Authenticate via the legacy login endpoint.
+
+        .. deprecated:: 0.1.0
+            ``POST /v2/users/login`` is deprecated by Docker Hub — prefer
+            :meth:`create_auth_token` (``POST /v2/auth/token``). Kept for
+            parity with the published API surface and for the 2FA flow.
+        """
+        warnings.warn(
+            "POST /v2/users/login is deprecated by Docker Hub; "
+            "use create_auth_token (POST /v2/auth/token) instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        model = LoginModel(username=username, password=password)
+        envelope = self._request(
+            "POST", "/v2/users/login", json=model.payload, raise_for_status=False
+        )
+        # A 401 carrying a login_2fa_token is the expected second-factor
+        # challenge, not an error.
+        data = envelope["data"]
+        if envelope["status_code"] >= 400 and not (
+            isinstance(data, dict) and data.get("login_2fa_token")
+        ):
+            self._raise_for_status_envelope(envelope)
+        envelope["data"] = validate_lenient(LoginResult, data)
+        return envelope
+
+    def two_factor_login(self, login_2fa_token: str, code: str) -> dict[str, Any]:
+        """Complete a 2FA login with the TOTP code (``POST /v2/users/2fa-login``)."""
+        model = TwoFactorLoginModel(login_2fa_token=login_2fa_token, code=code)
+        envelope = self._request("POST", "/v2/users/2fa-login", json=model.payload)
+        envelope["data"] = validate_lenient(LoginResult, envelope["data"])
+        return envelope
+
+    def _raise_for_status_envelope(self, envelope: dict[str, Any]) -> None:
+        from agent_utilities.core.exceptions import ApiError, AuthError
+
+        status_code = envelope["status_code"]
+        detail = ""
+        if isinstance(envelope["data"], dict):
+            detail = str(envelope["data"].get("detail") or "")
+        if status_code in (401, 403):
+            raise AuthError(f"Login failed (HTTP {status_code}): {detail}")
+        raise ApiError(f"Login failed (HTTP {status_code}): {detail}")