dockerhub-api 0.1.0__py3-none-any.whl

dockerhub_api/api/api_client_orgs.py

@@ -0,0 +1,149 @@
+"""Organization endpoints: settings, members, and invites.
+
+CONCEPT:HUB-1.0 — core wrapper.
+CONCEPT:HUB-1.3 — destructive-action gating (member removal, invite deletion,
+org-settings writes).
+"""
+
+from typing import Any
+
+from dockerhub_api.api.api_client_base import DockerHubApiBase
+from dockerhub_api.dockerhub_input_models import (
+    BulkInviteModel,
+    InviteModel,
+    OrgMemberListModel,
+    OrgMemberModel,
+    OrgMemberUpdateModel,
+    OrgSettingsModel,
+)
+from dockerhub_api.dockerhub_response_models import (
+    BulkInviteResult,
+    InvitePage,
+    OrgMember,
+    OrgMemberPage,
+    OrgSettings,
+    validate_lenient,
+)
+
+
+class DockerHubApiOrgs(DockerHubApiBase):
+    """``/v2/orgs/{org}/settings``, ``/members``, and ``/v2/invites``."""
+
+    # ----------------------------- settings ----------------------------- #
+
+    def get_org_settings(self, org: str) -> dict[str, Any]:
+        """Get an organization's settings (restricted images policy)."""
+        envelope = self._request("GET", f"/v2/orgs/{org}/settings")
+        envelope["data"] = validate_lenient(OrgSettings, envelope["data"])
+        return envelope
+
+    def update_org_settings(
+        self,
+        org: str,
+        restricted_images_enabled: bool,
+        allow_official_images: bool = True,
+        allow_verified_publishers: bool = True,
+    ) -> dict[str, Any]:
+        """Replace an organization's settings. Destructive — gated.
+
+        Controls ``restricted_images``: whether members may only pull
+        org-approved images, with carve-outs for Docker Official Images and
+        Verified Publisher images.
+        """
+        self._guard_destructive("update_org_settings")
+        model = OrgSettingsModel(
+            org=org,
+            restricted_images_enabled=restricted_images_enabled,
+            allow_official_images=allow_official_images,
+            allow_verified_publishers=allow_verified_publishers,
+        )
+        envelope = self._request(
+            "PUT", f"/v2/orgs/{model.org}/settings", json=model.payload
+        )
+        envelope["data"] = validate_lenient(OrgSettings, envelope["data"])
+        return envelope
+
+    # ----------------------------- members ------------------------------ #
+
+    def get_org_members(
+        self,
+        org: str,
+        search: str | None = None,
+        member_type: str | None = None,
+        role: str | None = None,
+        page: int | None = None,
+        page_size: int | None = None,
+    ) -> dict[str, Any]:
+        """List organization members (filter by search/type/role; paginated)."""
+        model = OrgMemberListModel(
+            org=org,
+            search=search,
+            member_type=member_type,
+            role=role,
+            page=page,
+            page_size=page_size,
+        )
+        envelope = self._request(
+            "GET", f"/v2/orgs/{model.org}/members", params=model.api_parameters
+        )
+        envelope["data"] = validate_lenient(OrgMemberPage, envelope["data"])
+        return envelope
+
+    def export_org_members(self, org: str) -> dict[str, Any]:
+        """Export the member list as CSV (``GET /members/export``)."""
+        return self._request("GET", f"/v2/orgs/{org}/members/export", accept="text/csv")
+
+    def update_org_member(self, org: str, username: str, role: str) -> dict[str, Any]:
+        """Set a member's org role (``owner``, ``editor``, or ``member``)."""
+        model = OrgMemberUpdateModel(org=org, username=username, role=role)
+        envelope = self._request(
+            "PUT",
+            f"/v2/orgs/{model.org}/members/{model.username}",
+            json=model.payload,
+        )
+        envelope["data"] = validate_lenient(OrgMember, envelope["data"])
+        return envelope
+
+    def remove_org_member(self, org: str, username: str) -> dict[str, Any]:
+        """Remove a member from the organization. Destructive — gated."""
+        self._guard_destructive("remove_org_member")
+        model = OrgMemberModel(org=org, username=username)
+        return self._request("DELETE", f"/v2/orgs/{model.org}/members/{model.username}")
+
+    # ----------------------------- invites ------------------------------ #
+
+    def get_org_invites(self, org: str) -> dict[str, Any]:
+        """List an organization's pending invites."""
+        envelope = self._request("GET", f"/v2/orgs/{org}/invites")
+        envelope["data"] = validate_lenient(InvitePage, envelope["data"])
+        return envelope
+
+    def delete_invite(self, invite_id: str) -> dict[str, Any]:
+        """Cancel an invite. Destructive — gated."""
+        self._guard_destructive("delete_invite")
+        model = InviteModel(invite_id=invite_id)
+        return self._request("DELETE", f"/v2/invites/{model.invite_id}")
+
+    def resend_invite(self, invite_id: str) -> dict[str, Any]:
+        """Resend an invite (``PATCH /v2/invites/{id}/resend``)."""
+        model = InviteModel(invite_id=invite_id)
+        return self._request("PATCH", f"/v2/invites/{model.invite_id}/resend")
+
+    def bulk_invite(
+        self,
+        org: str,
+        invitees: list[str],
+        team: str | None = None,
+        role: str = "member",
+        dry_run: bool = False,
+    ) -> dict[str, Any]:
+        """Invite many users/emails at once (``POST /v2/invites/bulk``).
+
+        ``dry_run=True`` validates the invitees without sending invites.
+        """
+        model = BulkInviteModel(
+            org=org, invitees=invitees, team=team, role=role, dry_run=dry_run
+        )
+        envelope = self._request("POST", "/v2/invites/bulk", json=model.payload)
+        envelope["data"] = validate_lenient(BulkInviteResult, envelope["data"])
+        return envelope

dockerhub_api/api/api_client_repositories.py

@@ -0,0 +1,217 @@
+"""Repository and tag endpoints (``/v2/namespaces/{ns}/repositories``).
+
+CONCEPT:HUB-1.0 — core wrapper. Repository creation is the primary
+provisioning use case (creating image repos for releases) and is therefore
+*not* destructive-gated.
+"""
+
+from typing import Any
+
+from dockerhub_api.api.api_client_base import DockerHubApiBase
+from dockerhub_api.dockerhub_input_models import (
+    ImmutableTagsPatchModel,
+    ImmutableTagsVerifyModel,
+    RepositoryCreateModel,
+    RepositoryGroupModel,
+    RepositoryListModel,
+    RepositoryModel,
+    TagListModel,
+    TagModel,
+)
+from dockerhub_api.dockerhub_response_models import (
+    ImmutableTagsSettings,
+    ImmutableTagsVerification,
+    Repository,
+    RepositoryGroup,
+    RepositoryPage,
+    Tag,
+    TagPage,
+    validate_lenient,
+)
+
+
+class DockerHubApiRepositories(DockerHubApiBase):
+    """Repositories, tags, immutable tags, and repo-team permissions."""
+
+    def get_repositories(
+        self,
+        namespace: str,
+        name: str | None = None,
+        ordering: str | None = None,
+        page: int | None = None,
+        page_size: int | None = None,
+    ) -> dict[str, Any]:
+        """List a namespace's repositories (name filter + ordering enum)."""
+        model = RepositoryListModel(
+            namespace=namespace,
+            name=name,
+            ordering=ordering,
+            page=page,
+            page_size=page_size,
+        )
+        envelope = self._request(
+            "GET",
+            f"/v2/namespaces/{model.namespace}/repositories",
+            params=model.api_parameters,
+        )
+        envelope["data"] = validate_lenient(RepositoryPage, envelope["data"])
+        return envelope
+
+    def create_repository(
+        self,
+        namespace: str,
+        name: str,
+        description: str | None = None,
+        full_description: str | None = None,
+        registry: str = "docker",
+        is_private: bool = False,
+    ) -> dict[str, Any]:
+        """Create an image repository in a namespace."""
+        model = RepositoryCreateModel(
+            namespace=namespace,
+            name=name,
+            description=description,
+            full_description=full_description,
+            registry=registry,
+            is_private=is_private,
+        )
+        envelope = self._request(
+            "POST",
+            f"/v2/namespaces/{model.namespace}/repositories",
+            json=model.payload,
+        )
+        envelope["data"] = validate_lenient(Repository, envelope["data"])
+        return envelope
+
+    def get_repository(self, namespace: str, repository: str) -> dict[str, Any]:
+        """Get one repository."""
+        model = RepositoryModel(namespace=namespace, repository=repository)
+        envelope = self._request(
+            "GET", f"/v2/namespaces/{model.namespace}/repositories/{model.repository}"
+        )
+        envelope["data"] = validate_lenient(Repository, envelope["data"])
+        return envelope
+
+    def check_repository(self, namespace: str, repository: str) -> dict[str, Any]:
+        """HEAD existence check for a repository."""
+        model = RepositoryModel(namespace=namespace, repository=repository)
+        return self._exists(
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}"
+        )
+
+    # ------------------------------- tags -------------------------------- #
+
+    def get_repository_tags(
+        self,
+        namespace: str,
+        repository: str,
+        page: int | None = None,
+        page_size: int | None = None,
+    ) -> dict[str, Any]:
+        """List a repository's tags (paginated)."""
+        model = TagListModel(
+            namespace=namespace, repository=repository, page=page, page_size=page_size
+        )
+        envelope = self._request(
+            "GET",
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}/tags",
+            params=model.api_parameters,
+        )
+        envelope["data"] = validate_lenient(TagPage, envelope["data"])
+        return envelope
+
+    def check_repository_tags(self, namespace: str, repository: str) -> dict[str, Any]:
+        """HEAD check: does the repository have any tags?"""
+        model = RepositoryModel(namespace=namespace, repository=repository)
+        return self._exists(
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}/tags"
+        )
+
+    def get_repository_tag(
+        self, namespace: str, repository: str, tag: str
+    ) -> dict[str, Any]:
+        """Get one tag."""
+        model = TagModel(namespace=namespace, repository=repository, tag=tag)
+        envelope = self._request(
+            "GET",
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}"
+            f"/tags/{model.tag}",
+        )
+        envelope["data"] = validate_lenient(Tag, envelope["data"])
+        return envelope
+
+    def check_repository_tag(
+        self, namespace: str, repository: str, tag: str
+    ) -> dict[str, Any]:
+        """HEAD existence check for one tag."""
+        model = TagModel(namespace=namespace, repository=repository, tag=tag)
+        return self._exists(
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}"
+            f"/tags/{model.tag}"
+        )
+
+    # --------------------------- immutable tags --------------------------- #
+
+    def update_immutable_tags(
+        self,
+        namespace: str,
+        repository: str,
+        enabled: bool,
+        rules: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Patch a repository's immutable-tags settings."""
+        model = ImmutableTagsPatchModel(
+            namespace=namespace, repository=repository, enabled=enabled, rules=rules
+        )
+        envelope = self._request(
+            "PATCH",
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}"
+            "/immutabletags",
+            json=model.payload,
+        )
+        envelope["data"] = validate_lenient(ImmutableTagsSettings, envelope["data"])
+        return envelope
+
+    def verify_immutable_tags(
+        self,
+        namespace: str,
+        repository: str,
+        rules: list[str] | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Verify immutable-tag rules without applying them."""
+        model = ImmutableTagsVerifyModel(
+            namespace=namespace, repository=repository, rules=rules, tags=tags
+        )
+        envelope = self._request(
+            "POST",
+            f"/v2/namespaces/{model.namespace}/repositories/{model.repository}"
+            "/immutabletags/verify",
+            json=model.payload,
+        )
+        envelope["data"] = validate_lenient(ImmutableTagsVerification, envelope["data"])
+        return envelope
+
+    # -------------------------- team permissions -------------------------- #
+
+    def assign_repository_group(
+        self,
+        namespace: str,
+        repository: str,
+        group_id: int | str,
+        permission: str,
+    ) -> dict[str, Any]:
+        """Grant a team (group) ``read``/``write``/``admin`` on a repository."""
+        model = RepositoryGroupModel(
+            namespace=namespace,
+            repository=repository,
+            group_id=group_id,
+            permission=permission,
+        )
+        envelope = self._request(
+            "POST",
+            f"/v2/repositories/{model.namespace}/{model.repository}/groups",
+            json=model.payload,
+        )
+        envelope["data"] = validate_lenient(RepositoryGroup, envelope["data"])
+        return envelope

dockerhub_api/api/api_client_scim.py

@@ -0,0 +1,153 @@
+"""SCIM 2.0 endpoints (``/v2/scim/2.0``).
+
+CONCEPT:HUB-1.5 — SCIM provisioning. All requests/responses use the
+``application/scim+json`` media type and SCIM-style 1-based pagination
+(``startIndex``/``count``).
+"""
+
+from typing import Any
+
+from dockerhub_api.api.api_client_base import SCIM_CONTENT_TYPE, DockerHubApiBase
+from dockerhub_api.dockerhub_input_models import (
+    ScimUserCreateModel,
+    ScimUserListModel,
+    ScimUserModel,
+    ScimUserReplaceModel,
+)
+from dockerhub_api.dockerhub_response_models import (
+    ScimListResponse,
+    ScimResourceType,
+    ScimSchema,
+    ScimServiceProviderConfig,
+    ScimUser,
+    validate_lenient,
+)
+
+SCIM_BASE = "/v2/scim/2.0"
+
+
+class DockerHubApiScim(DockerHubApiBase):
+    """SCIM service discovery and user provisioning."""
+
+    def _scim_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict | None = None,
+        json: Any | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            method,
+            endpoint,
+            params=params,
+            json=json,
+            content_type=SCIM_CONTENT_TYPE,
+            accept=SCIM_CONTENT_TYPE,
+        )
+
+    # ----------------------------- discovery ----------------------------- #
+
+    def get_scim_service_provider_config(self) -> dict[str, Any]:
+        """Get the SCIM ServiceProviderConfig."""
+        envelope = self._scim_request("GET", f"{SCIM_BASE}/ServiceProviderConfig")
+        envelope["data"] = validate_lenient(ScimServiceProviderConfig, envelope["data"])
+        return envelope
+
+    def get_scim_resource_types(self) -> dict[str, Any]:
+        """List the SCIM ResourceTypes."""
+        envelope = self._scim_request("GET", f"{SCIM_BASE}/ResourceTypes")
+        envelope["data"] = validate_lenient(ScimListResponse, envelope["data"])
+        return envelope
+
+    def get_scim_resource_type(self, name: str) -> dict[str, Any]:
+        """Get one SCIM ResourceType by name."""
+        envelope = self._scim_request("GET", f"{SCIM_BASE}/ResourceTypes/{name}")
+        envelope["data"] = validate_lenient(ScimResourceType, envelope["data"])
+        return envelope
+
+    def get_scim_schemas(self) -> dict[str, Any]:
+        """List the SCIM Schemas."""
+        envelope = self._scim_request("GET", f"{SCIM_BASE}/Schemas")
+        envelope["data"] = validate_lenient(ScimListResponse, envelope["data"])
+        return envelope
+
+    def get_scim_schema(self, schema_id: str) -> dict[str, Any]:
+        """Get one SCIM Schema by id (URN)."""
+        envelope = self._scim_request("GET", f"{SCIM_BASE}/Schemas/{schema_id}")
+        envelope["data"] = validate_lenient(ScimSchema, envelope["data"])
+        return envelope
+
+    # ------------------------------- users ------------------------------- #
+
+    def get_scim_users(
+        self,
+        start_index: int | None = None,
+        count: int | None = None,
+        filter: str | None = None,
+        sort_by: str | None = None,
+        sort_order: str | None = None,
+    ) -> dict[str, Any]:
+        """List SCIM users (``startIndex``/``count``/``filter``/``sortBy``/``sortOrder``)."""
+        model = ScimUserListModel(
+            start_index=start_index,
+            count=count,
+            filter=filter,
+            sort_by=sort_by,
+            sort_order=sort_order,
+        )
+        envelope = self._scim_request(
+            "GET", f"{SCIM_BASE}/Users", params=model.api_parameters
+        )
+        envelope["data"] = validate_lenient(ScimListResponse, envelope["data"])
+        return envelope
+
+    def create_scim_user(
+        self,
+        user_name: str,
+        given_name: str | None = None,
+        family_name: str | None = None,
+        email: str | None = None,
+        active: bool = True,
+    ) -> dict[str, Any]:
+        """Provision a SCIM user."""
+        model = ScimUserCreateModel(
+            user_name=user_name,
+            given_name=given_name,
+            family_name=family_name,
+            email=email,
+            active=active,
+        )
+        envelope = self._scim_request("POST", f"{SCIM_BASE}/Users", json=model.payload)
+        envelope["data"] = validate_lenient(ScimUser, envelope["data"])
+        return envelope
+
+    def get_scim_user(self, user_id: str) -> dict[str, Any]:
+        """Get one SCIM user by id."""
+        model = ScimUserModel(user_id=user_id)
+        envelope = self._scim_request("GET", f"{SCIM_BASE}/Users/{model.user_id}")
+        envelope["data"] = validate_lenient(ScimUser, envelope["data"])
+        return envelope
+
+    def replace_scim_user(
+        self,
+        user_id: str,
+        user_name: str,
+        given_name: str | None = None,
+        family_name: str | None = None,
+        email: str | None = None,
+        active: bool = True,
+    ) -> dict[str, Any]:
+        """Replace a SCIM user resource (``PUT``)."""
+        model = ScimUserReplaceModel(
+            user_id=user_id,
+            user_name=user_name,
+            given_name=given_name,
+            family_name=family_name,
+            email=email,
+            active=active,
+        )
+        envelope = self._scim_request(
+            "PUT", f"{SCIM_BASE}/Users/{model.user_id}", json=model.payload
+        )
+        envelope["data"] = validate_lenient(ScimUser, envelope["data"])
+        return envelope

dockerhub_api/api_client.py

@@ -0,0 +1,35 @@
+"""The composed Docker Hub API client.
+
+CONCEPT:HUB-1.0 — core wrapper. ``Api`` is assembled from per-domain mixins,
+all sharing the transport/auth/rate-limit plumbing in
+:class:`~dockerhub_api.api.api_client_base.DockerHubApiBase`.
+"""
+
+from agent_utilities.base_utilities import get_logger
+
+from dockerhub_api.api.api_client_access_tokens import DockerHubApiAccessTokens
+from dockerhub_api.api.api_client_audit_logs import DockerHubApiAuditLogs
+from dockerhub_api.api.api_client_auth import DockerHubApiAuth
+from dockerhub_api.api.api_client_groups import DockerHubApiGroups
+from dockerhub_api.api.api_client_org_access_tokens import DockerHubApiOrgAccessTokens
+from dockerhub_api.api.api_client_orgs import DockerHubApiOrgs
+from dockerhub_api.api.api_client_repositories import DockerHubApiRepositories
+from dockerhub_api.api.api_client_scim import DockerHubApiScim
+
+logger = get_logger(__name__)
+
+
+class Api(
+    DockerHubApiAuth,
+    DockerHubApiAccessTokens,
+    DockerHubApiOrgAccessTokens,
+    DockerHubApiAuditLogs,
+    DockerHubApiOrgs,
+    DockerHubApiRepositories,
+    DockerHubApiGroups,
+    DockerHubApiScim,
+):
+    """Full Docker Hub API surface: auth, tokens, repos, orgs, teams,
+    audit logs, and SCIM."""
+
+    __slots__ = ()