harborapi

Python async client for the Harbor REST API v2.0 based on the official Harbor REST API specification.

NOTE: The official Harbor API spec is hand-written, and numerous errors and inconsistencies have been found in it. This library attempts to work around these issues as much as possible, but errors may still occur. If you find any errors, please open an issue.

Features

• Async API
• Extensive type hint coverage
• Data validation with Pydantic
• Built-in retry functionality with backoff
• Optional Rich support

Installation

pip install harborapi

Documentation

Documentation is available here. The documentation is still a work in progress, and you may have to dig around a bit to find what you're looking for.

Creating proper documentation for the Pydantic models is priority number one right now, but is largely blocked by the lack of inheritance support in the mkdocstrings python plugin.

Quick Start

Authentication

from harborapi import HarborAsyncClient

client = HarborAsyncClient(
    url="https://demo.goharbor.io/api/v2.0/",
    username="username",
    secret="secret",
    # OR
    basicauth="base64-basic-auth-credentials",
    # OR
    credentials_file="/path/to/robot-credentials-file.json",
)

Get all projects

import asyncio

from harborapi import HarborAsyncClient

client = HarborAsyncClient(
    # ...
)

async def main() -> None:
    # Get all projects
    projects = await client.get_projects()
    for project in projects:
        print(project.name)

    # If you have rich installed:
    import rich

    for project in projects:
        rich.print(project)

asyncio.run(main())

Create a project

import asyncio

from harborapi import HarborAsyncClient
from harborapi.models import ProjectReq, ProjectMetadata

client = HarborAsyncClient(
    # ...
)

async def main() -> None:
    project_path = await client.create_project(
        ProjectReq(
            project_name="test-project",
            metadata=ProjectMetadata(
                public=True,
            ),
        )
    )
    print(f"Project created: {project_path}")

asyncio.run(main())

All endpoints are documented in the endpoints documentation.

Disclaimer

harborapi makes use of code generation for its data models, but it doesn't entirely rely on it like, for example, githubkit. Thus, while the library is based on the Harbor REST API specification, it is not beholden to it. The official schema contains several inconsistencies and errors, and this package takes steps to rectify some of these locally until they are fixed in the official Harbor API spec.

harborapi attempts to improve endpoint descriptions where possible and fix models with fields given the wrong type or wrongly marked as required. Without these changes, the validation provided by the library would be unusable for certain endpoints, as these endpoints can, in certain cases, return data that is inconsistent with the official API specification, thus breaking the model validation.

To return the raw API responses without validation and type conversion, set raw=True when instantiating the client. For more information, check the documentation on validation.

TODO

Endpoints

• [ ] Preheat