harborapi 0.13.1

Async Harbor API v2.0 client

harborapi

---

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

Features

• Async API
• Extensive type hint coverage
• Data validation with Pydantic
• Built-in retry functionality with backoff
• Extensive test coverage powered by Hypothesis
• Optional rich support

Installation

pip install harborapi

Documentation

Documentation is available here

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

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.models import ProjectReq, ProjectMetadata

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 make 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 schema contains several inconsistencies and errors, and the library takes steps to rectify some of these until they are fixed in Harbor's own specification.

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 return data that is inconsistent with the specification, thus making it impossible to construct valid models from the data.

Implemented endpoints

• Artifact
• Auditlog
• Configure
• Garbage Collection
• Health
• Icon
• Immutable
• Label
• Ldap
• OIDC
• Ping
• Preheat
• Project
• Project Metadata
• Purge
• Quota
• Registry
• Replication
• Repository
• Retention
• Robot
• Robotv1
• Scan
• Scan Data Export
• Scanall
• Scanner
• Search
• Statistic
• System CVE Allowlist
• System Info**
• User
• Usergroup
• Webhooks

** /systeminfo/getcert NYI

0.13.1 - 2023-04-03

Fixed

• Pagination URLs containing spaces are now properly handled. This could occur if passing a a query parameter with a list of items, such as ?q=operation={push pull} or ?q=operation=(push pull).

0.13.0 - 2023-03-31

Changed

• HarborAsyncClient.update_project_member_role() now accepts integer arguments for its role_id parameter, since RoleRequest only has a single field (role_id).

Fixed

• Potential bug with models.VulnerabilitySummary if summary is None.
• JSON parsing exception in HarborAsyncClient.get_audit_log_rotation_schedule() that could occur if no schedule exists. The API returns an emtpy 200 OK response, which is now handled correctly (empty ExecHistory object).
• Missing docstring for HarborAsycClient.get_project_members.

0.12.0 - 2023-03-14

Changed

• BREAKING: HarborAsyncClient.export_scan_data() now takes the arguments in the order (criteria, scan_type). Furthermore, scan_type now has a default argument of "application/vnd.security.vulnerability.report; version=1.1", per the blog post describing this new feature. It should not be necessary specify this argument, but it is still possible to do so if you need to.

0.11.2 - 2023-03-14

Fixed

• Actually adds group_name parameter for HarborAsyncClient.get_usergroups() this time.

Added

• Missing group_name and limit parameters for HarborAsyncClient.get_usergroups().

0.11.1 - 2023-03-14

Added

• Missing group_name and limit parameters for HarborAsyncClient.get_usergroups().

0.11.0 - 2023-03-10

Added

• HarborAsyncClient.get_system_certificate()
  • Returns the system certificate. (GET /api/v2.0/systeminfo/getcert)

Changed

• BREAKING: Methods that download files, now return FileResponse instead of a bytes object. FileResponse contains the file contents along with its metadata. The object can be passed to bytes() to get the response contents, otherwise it can be accessed via the FileResponse.content attribute.
• BREAKING: Renamed "purge" methods to better reflect their purpose of audit log rotation:
  • HarborAsyncClient.get_purge_audit_log_status() -> HarborAsyncClient.get_audit_log_rotation()
  • HarborAsyncClient.get_purge_audit_log() -> HarborAsyncClient.get_audit_log_rotation_log()
  • HarborAsyncClient.stop_purge_audit_log() -> HarborAsyncClient.stop_audit_log_rotation()
  • HarborAsyncClient.get_purge_audit_log_schedule() -> HarborAsyncClient.get_audit_log_rotation_schedule()
  • HarborAsyncClient.create_purge_audit_log_schedule() -> HarborAsyncClient.create_audit_log_rotation_schedule()
  • HarborAsyncClient.update_purge_audit_log_schedule() -> HarborAsyncClient.update_audit_log_rotation_schedule()
  • HarborAsyncClient.get_purge_audit_logs() -> HarborAsyncClient.get_audit_log_rotation_history()

0.10.0 - 2023-02-28

Added

• harborapi.ext.artifact.ArtifactInfo.name_with_digest_full which returns the artifact name with the full SHA256 digest, not just the first 15 characters like name_with_digest.
• Audit log purging methods.
  • HarborAsyncClient.get_purge_audit_log_status()
  • HarborAsyncClient.get_purge_audit_log()
  • HarborAsyncClient.stop_purge_audit_log()
  • HarborAsyncClient.get_purge_audit_log_schedule()
  • HarborAsyncClient.create_purge_audit_log_schedule()
  • HarborAsyncClient.update_purge_audit_log_schedule()
  • HarborAsyncClient.get_purge_audit_logs()
• Documentation for HarborAsyncClient.get_project_deletable().
• Webhook methods.
  • HarborAsyncClient.get_webhook_jobs()
  • HarborAsyncClient.get_webhook_policies()
  • HarborAsyncClient.get_webhook_policy()
  • HarborAsyncClient.create_webhook_policy()
  • HarborAsyncClient.update_webhook_policy()
  • HarborAsyncClient.delete_webhook_policy()
  • HarborAsyncClient.get_webhook_policy_last_trigger()
  • HarborAsyncClient.get_webhook_supported_events()
• Scan Data Export Methods
  • HarborAsyncClient.get_scan_export()
  • HarborAsyncClient.get_scan_exports()
  • HarborAsyncClient.export_scan_data()
  • HarborAsyncClient.download_scan_export()
• Icon methods
  • HarborAsyncClient.get_icon()
• Label methods
  • HarborAsyncClient.get_label()
  • HarborAsyncClient.create_label()
  • HarborAsyncClient.delete_label()
  • HarborAsyncClient.get_labels()
• Project member methods
  • HarborAsyncClient.get_project_member()
  • HarborAsyncClient.add_project_member()
  • HarborAsyncClient.add_project_member_user()
  • HarborAsyncClient.add_project_member_group()
  • HarborAsyncClient.update_project_member_role()
  • HarborAsyncClient.remove_project_member()
  • HarborAsyncClient.get_project_members()
• New methods for controlling the size of the response log.
  • harborapi.client.ResponseLog.resize()
  • harborapi.client.ResponseLog.clear()
  • Documented here
• basicauth as a parameter for HarborAsyncClient.__init__() to pass in base64 basic auth credentials.

Changed

• missing_ok parameter for DELETE methods has been deprecated. Manually handle harborapi.exceptions.NotFound instead. This parameter will stop working in version 1.0.0, and be removed altogether in a later release.
• harborapi.models.Repository.split_name() now returns a tuple instead of a list, as its docstring states it should.
• DEPRECATED: Using credentials as a parameter for HarborAsyncClient.__init__ is deprecated. Use basicauth instead.
• HarborAsyncClient.credentials is now a Pydantic SecretStr, which prevents it from being printed in clear text when locals are dumped, such as when printing the client object. To access the value, use HarborAsyncClient.credentials.get_secret_value().

Removed

• Explicit logging calls from HarborAsyncClient.set_user_cli_secret() and HarborAsyncClient.set_user_password(). The exception handler handles logging if configured.

0.9.0 - 2023-02-21

Changed

• Updated harborapi.models to match the latest version of the Harbor API spec goharbor/harbor@d03f0dc.

• harborapi.models.GeneralInfo.with_chartmuseum has been removed from the API spec, but remains on the model for backwards compatibility. In the future, this field will be removed, as the API will never return this it in sufficiently new versions of Harbor.

0.8.6 - 2023-02-20

Fixed

• Models with harborapi.models.ScheduleObj fields are now correctly validated when the Harbor API responds with a value of "Schedule" for the field ScheduleObj.type, which is not a valid value for the enum according to their own spec.

0.8.5 - 2023-02-20

Added

NativeReportSummary.severity_enum which returns the severity of the report as a harborarpi.scanner.Severity enum, which can be used for comparisons between reports.

Fixed

harborarpi.scanner.Severity enum not having a None value, which is observed when a report has no vulnerabilities.

0.8.4 - 2023-02-14

Fixed

• Certain resource enumeration methods missing the limit parameter.
• HarborAsyncClient.get_gc_jobs() ignoring user parameters.

0.8.3 - 2023-02-14

Changed

• BREAKING: HarborAsyncClient.update_robot_token renamed to HarborAsyncClient.refresh_robot_token to better reflect the API endpoint name and purpose.

Fixed

• Pagination failing when one or more query parameter values included a comma.
• Certain HarborAsyncClient methods having missing or incomplete docstrings.

0.8.2 - 2023-02-09

Fixed

• HarborAsyncClient.get_registry_providers now returns a RegistryProviders object, which is a model whose only attribute providers is a dict of RegistryProviderInfo objects. Previously this method attempted to return a list of RegistryProviderInfo objects, but this was incorrect.

0.8.1 - 2023-02-09

Changed

• Backoff handlers for HTTP methods now handle a more strict subset of httpx.RequestError exceptions. This is to avoid retrying on exceptions that will never succeed such as httpx.UnsupportedProtocol.

0.8.0 - 2023-02-08

Added

• limit parameter for all methods that return a list of items. This parameter is used to limit the number of items returned by the API. See the docs for more details.

Removed

• retrieve_all parameter for all methods that return a list of items. Use the new limit parameter to control the number of results to retrieve. Passing retrieve_all to these methods will be silently ignored. In the future this will raise a DeprecationWarning.

0.7.1 - 2023-02-07

Added

• New parameters raw and validate to HarborAsyncClient and HarborClient to control whether the client returns the raw data from the API, and whether the client validates the data from the API, respectively. See the docs for more details.

0.7.0 - 2023-02-06

Added

• New models from 2022-11-28 spec update.

Changed

• Updated models from 2022-11-28 spec update.
• Generated models are now defined in models._models and models._scanner, and the overrides for these models are defined in models.models and models.scanner respectively. This is to make it easier to regenerate the models in the future while keeping the extended functionality (such as Repository.project_name, ScanOverview.__new__, etc.) for these classes intact, since that is now declared separately from the generated models. Furthermore, models.models and models.scanner both re-export all the generated models so that the API remains unchanged. See the Justfile for more details on how the models are generated.

Fixed

• HarborAsyncClient.search() raising an error when finding Helm Charts with an empty engine field.

Removed

• BREAKING: HarborAsyncClient.get_internal_config(). This endpoint is meant for internal usage only, and the new model definitions don't seem to play well with it. If you need this endpoint, please open an issue.

0.6.0 - 2023-01-30

Changed

• BREAKING: The max_depth parameter of the as_table() and as_panel() methods on all models now starts counting from 1 instead of 0.
  • max_depth=0 now means "no limit", and max_depth=1 means "only show the top level" (previously max_depth=0 meant "only show the top level" and max_depth=1 meant "show the top level and one level below")

0.5.0 - 2023-01-17

Added

• Changelog
• Rich as optional dependency: pip install harborapi[rich]

Changed

• Use Hatch as build system.