GHGA Service Commons

7.0.1 verified Sat May 09 auth: no python

A library providing common functionality for GHGA services, including FastAPI utilities, authentication, config management, and custom HTTPX transports (caching, retry, rate limiting). Current version: 7.0.1. Requires Python >=3.10. Release cadence: irregular, with breaking changes in major versions (6.0.0, 7.0.0).

pip install ghga-service-commons

Common errors

error ModuleNotFoundError: No module named 'ghga_service_commons.utils.health' ↓

cause Incorrect import path for health check utilities.

fix

Use: from ghga_service_commons.utils.health_check import HealthEndpointConfig

error AttributeError: module 'ghga_service_commons' has no attribute 'transports' ↓

cause The transports subpackage is only available with the optional dependency.

fix

Install the 'transports' extra: pip install ghga-service-commons[transports]

error ImportError: cannot import name 'CompositeRetryAndRateLimitTransport' from 'ghga_service_commons' ↓

cause Wrong import path for transport classes.

fix

Use: from ghga_service_commons.transports import CompositeRetryAndRateLimitTransport

error FastAPI returning 403 instead of 401 for unauthenticated requests (after upgrade to 7.0.0) ↓

cause FastAPI behavior changed due to an update; the library now respects 401.

fix

Update your client code to handle 401 status codes instead of 403.

Warnings

breaking Version 7.0.0 introduced potentially breaking changes: FastAPI now returns 401 instead of 403 for missing authentication. Also Hishel was upgraded to a stable version, removing some caching features. ↓

fix Review your FastAPI error handling: expect 401 instead of 403 for auth failures. If using caching, check Hishel compatibility.

breaking Version 6.0.0 introduced changes to the transport layer. CompositeRetryAndRateLimitTransport and other custom transports may require updated instantiation patterns. ↓

fix See the migration guide in the GitHub release notes for 6.0.0.

gotcha The transports subpackage requires the optional dependency 'transports' extra. Install with 'pip install ghga-service-commons[transports]'. ↓

fix Add the 'transports' extra to your dependency.

deprecated Old import paths like 'ghga_service_commons.utils.health' are deprecated. Use 'ghga_service_commons.utils.health_check' instead. ↓

fix Update imports to the correct submodules.

Install

pip install ghga-service-commons[transports]

Imports

HealthEndpointConfig

wrong

from ghga_service_commons.utils.health import HealthEndpointConfig

correct

from ghga_service_commons.utils.health_check import HealthEndpointConfig

wrong module path

AuthContext

wrong

from ghga_service_commons.auth import AuthContext

correct

from ghga_service_commons.auth.context import AuthContext

AuthContext is in the context submodule

CompositeRetryAndRateLimitTransport

from ghga_service_commons.transports import CompositeRetryAndRateLimitTransport

Quickstart

Basic usage: health endpoint configuration and auth context creation.

import os
from ghga_service_commons.utils.health_check import HealthEndpointConfig
from ghga_service_commons.auth.context import AuthContext

# Example: configure health endpoint
config = HealthEndpointConfig()
print(f"Health endpoint configured: {config}")

# Example: create an auth context
# (requires GHGA credentials or use environment variable)
auth = AuthContext()
print(f"Auth context: {auth}")