API reference#

safir Module#

safir.arq Package#

An arq client with a mock for testing.

Functions#

build_arq_redis_settings(url, password)

Construct Redis settings for arq.

Classes#

ArqJobError(message, job_id)

A base class for errors related to arq jobs.

ArqMode(value[, names, module, qualname, ...])

Mode configuration for the Arq queue.

ArqQueue(*[, default_queue_name])

A common interface for working with an arq queue that can be implemented either with a real Redis backend, or an in-memory repository for testing.

JobMetadata(id, name, args, kwargs, ...)

Information about a queued job.

JobNotFound(job_id)

A job cannot be found.

JobNotQueued(job_id)

The job was not successfully queued.

JobResult(id, name, args, kwargs, ...)

The full result of a job, as well as its metadata.

JobResultUnavailable(job_id)

The job's result is unavailable.

MockArqQueue(*[, default_queue_name])

A mocked queue for testing API services.

RedisArqQueue(pool, *[, default_queue_name])

A distributed queue, based on arq and Redis.

WorkerSettings(functions, redis_settings, ...)

Configuration class for an arq worker.

Class Inheritance Diagram#

Inheritance diagram of safir.arq._exceptions.ArqJobError, safir.arq._models.ArqMode, safir.arq._queue.ArqQueue, safir.arq._models.JobMetadata, safir.arq._exceptions.JobNotFound, safir.arq._exceptions.JobNotQueued, safir.arq._models.JobResult, safir.arq._exceptions.JobResultUnavailable, safir.arq._queue.MockArqQueue, safir.arq._queue.RedisArqQueue, safir.arq._config.WorkerSettings

safir.arq.uws Module#

Construction of UWS backend workers.

Functions#

build_worker(worker, config, logger)

Construct an arq worker for the provided backend function.

Classes#

WorkerConfig(arq_mode, arq_queue_url, ...)

Minimal configuration needed for building a UWS backend worker.

WorkerError(message[, detail, add_traceback])

An error occurred during background task processing.

WorkerErrorType(value[, names, module, ...])

Types of errors that may be reported by a worker.

WorkerFatalError(message[, detail, ...])

Fatal error occurred during worker processing.

WorkerJobInfo(job_id, user, token, timeout)

Metadata about the job that may be useful to the backend.

WorkerResult

A single result from the job.

WorkerTimeoutError(elapsed, timeout)

Transient error occurred during worker processing.

WorkerTransientError(message[, detail, ...])

Transient error occurred during worker processing.

WorkerUsageError(message[, detail, ...])

Parameters sent by the user were invalid.

Variables#

UWS_QUEUE_NAME

Name of the arq queue for internal UWS messages.

Class Inheritance Diagram#

Inheritance diagram of safir.arq.uws.WorkerConfig, safir.arq.uws.WorkerError, safir.arq.uws.WorkerErrorType, safir.arq.uws.WorkerFatalError, safir.arq.uws.WorkerJobInfo, safir.arq.uws.WorkerResult, safir.arq.uws.WorkerTimeoutError, safir.arq.uws.WorkerTransientError, safir.arq.uws.WorkerUsageError

safir.asyncio Package#

Utility functions for asyncio code.

Functions#

run_with_asyncio(f)

Run the decorated function with asyncio.run.

Classes#

AsyncMultiQueue()

An asyncio multiple reader, multiple writer queue.

AsyncMultiQueueError

Invalid sequence of calls when writing to AsyncMultiQueue.

Class Inheritance Diagram#

Inheritance diagram of safir.asyncio._multiqueue.AsyncMultiQueue, safir.asyncio._multiqueue.AsyncMultiQueueError

safir.click Package#

Click command-line interface support.

Functions#

display_help(main, ctx[, topic, subtopic])

Show help for a Click command.

safir.database Package#

Utility functions for database management.

Functions#

create_async_session(engine[, logger, statement])

Create a new async database session.

create_database_engine(url, password, *[, ...])

Create a new async database engine.

datetime_from_db(time)

Add the UTC time zone to a naive datetime from the database.

datetime_to_db(time)

Strip time zone for storing a datetime in the database.

drop_database(engine, schema)

Drop all tables from the database.

initialize_database(engine, logger, *, schema)

Create and initialize a new database.

is_database_current(engine[, logger, ...])

Check whether the database schema is at the current version.

retry_async_transaction([__func, delay, ...])

Retry if a transaction failed.

run_migrations_offline(metadata, url)

Run Alembic migrations in offline mode.

run_migrations_online(metadata, url, password)

Run Alembic migrations online using an async backend.

stamp_database(config_path)

Mark the database as updated to the head of the given Alembic config.

stamp_database_async(engine[, config_path])

Mark the database as updated to the head of the given Alembic config.

unstamp_database(engine)

Clear the Alembic version from the database.

Classes#

AlembicConfigError

The Alembic configuration was missing or invalid.

CountedPaginatedList(entries, next_cursor, ...)

Paginated SQL results with pagination metadata and total count.

CountedPaginatedQueryRunner(entry_type, ...)

Run database queries that return paginated results with counts.

DatabaseInitializationError

Database initialization failed.

DatetimeIdCursor(previous, time, id)

Pagination cursor using a datetime and unique column ID.

InvalidCursorError(message)

The provided cursor was invalid.

PaginatedList(entries, next_cursor, prev_cursor)

Paginated SQL results with accompanying pagination metadata.

PaginatedQueryRunner(entry_type, cursor_type)

Run database queries that return paginated results.

PaginationCursor(previous)

Generic pagnination cursor for keyset pagination.

PaginationLinkData(prev_url, next_url, first_url)

Holds the data returned in an RFC 8288 Link header.

Class Inheritance Diagram#

Inheritance diagram of safir.database._alembic.AlembicConfigError, safir.database._pagination.CountedPaginatedList, safir.database._pagination.CountedPaginatedQueryRunner, safir.database._initialize.DatabaseInitializationError, safir.database._pagination.DatetimeIdCursor, safir.database._pagination.InvalidCursorError, safir.database._pagination.PaginatedList, safir.database._pagination.PaginatedQueryRunner, safir.database._pagination.PaginationCursor, safir.database._pagination.PaginationLinkData

safir.datetime Package#

Date and time manipulation utility functions.

Functions#

current_datetime(*[, microseconds])

Construct a datetime for the current time.

format_datetime_for_logging(timestamp)

Format a datetime for logging and human readabilty.

isodatetime(timestamp)

Format a timestamp in UTC in a standard ISO date format.

parse_isodatetime(time_string)

Parse a string in a standard ISO date format.

parse_timedelta(text)

Parse a string into a datetime.timedelta.

safir.dependencies.arq Module#

A FastAPI dependency that supplies a Redis connection for arq.

Classes#

ArqDependency()

A FastAPI dependency that maintains a Redis client for enqueuing tasks to the worker pool.

Variables#

arq_dependency

Singleton instance of ArqDependency that serves as a FastAPI dependency.

Class Inheritance Diagram#

Inheritance diagram of safir.dependencies.arq.ArqDependency

safir.dependencies.db_session Module#

Manage an async database session.

Classes#

DatabaseSessionDependency()

Manages an async per-request SQLAlchemy session.

Variables#

db_session_dependency

The dependency that will return the async session proxy.

Class Inheritance Diagram#

Inheritance diagram of safir.dependencies.db_session.DatabaseSessionDependency

safir.dependencies.gafaelfawr Module#

Gafaelfawr authentication dependencies.

Functions#

auth_delegated_token_dependency(...)

Retrieve Gafaelfawr delegated token from HTTP headers.

auth_dependency(x_auth_request_user)

Retrieve authentication information from HTTP headers.

auth_logger_dependency(user, logger)

Logger bound to the authenticated user.

safir.dependencies.http_client Module#

HTTP client dependency for FastAPI.

Classes#

HTTPClientDependency()

Provides an httpx.AsyncClient as a dependency.

Variables#

DEFAULT_HTTP_TIMEOUT

Default timeout (in seconds) for outbound HTTP requests.

http_client_dependency

The dependency that will return the HTTP client.

Class Inheritance Diagram#

Inheritance diagram of safir.dependencies.http_client.HTTPClientDependency

safir.dependencies.logger Module#

Logger dependency for FastAPI.

Provides a structlog logger as a FastAPI dependency. The logger will incorporate information from the request in its bound context.

Classes#

LoggerDependency()

Provides a structlog logger configured with request information.

Variables#

logger_dependency

The dependency that will return the logger for the current request.

Class Inheritance Diagram#

Inheritance diagram of safir.dependencies.logger.LoggerDependency

safir.dependencies.metrics Module#

Dependencies for metrics functionality.

Classes#

EventDependency(event_maker)

Provides EventManager-managed events for apps to publish.

EventMaker()

A blueprint for an event publisher container class.

Class Inheritance Diagram#

Inheritance diagram of safir.dependencies.metrics.EventDependency, safir.dependencies.metrics.EventMaker

safir.fastapi Package#

Helper code for FastAPI (other than dependencies and middleware).

Functions#

client_request_error_handler(request, exc)

Exception handler for exceptions derived from ClientRequestError.

Classes#

ClientRequestError(message[, location, ...])

Represents an error in a client request.

Class Inheritance Diagram#

Inheritance diagram of safir.fastapi._errors.ClientRequestError

safir.gcs Package#

Utilities for interacting with Google Cloud Storage.

Classes#

SignedURLService(service_account[, lifetime])

Generate signed URLs for Google Cloud Storage blobs.

Class Inheritance Diagram#

Inheritance diagram of safir.gcs._signing.SignedURLService

safir.github Package#

GitHub API client factory and Pydantic models.

Classes#

GitHubAppClientFactory(*, id, key, name, ...)

Factory for creating GitHub App clients authenticated either as an app or as an installation of that app.

Class Inheritance Diagram#

Inheritance diagram of safir.github._client.GitHubAppClientFactory

safir.github.models Module#

Pydantic models for GitHub v3 REST API resources.

Classes#

GitHubBlobModel

A Pydantic model for a blob, returned by the GitHub blob endpoint.

GitHubBranchCommitModel

A Pydantic model for the commit field found in GitHubBranchModel.

GitHubBranchModel

A Pydantic model for a GitHub branch.

GitHubCheckRunAnnotationLevel(value[, ...])

The level of a check run output annotation.

GitHubCheckRunConclusion(value[, names, ...])

The check run conclusion state.

GitHubCheckRunModel

A Pydantic model for the "check_run" field in a check_run webhook payload (GitHubCheckRunEventModel).

GitHubCheckRunOutput

Check run output report.

GitHubCheckRunPrInfoModel

A Pydantic model of the pull_requests[] items in a check run GitHub API model (GitHubCheckRunModel).

GitHubCheckRunStatus(value[, names, module, ...])

The check run status.

GitHubCheckSuiteConclusion(value[, names, ...])

The conclusion state of a GitHub check suite.

GitHubCheckSuiteId

Brief information about a check suite in the GitHubCheckRunModel.

GitHubCheckSuiteModel

A Pydantic model for the check_suite field in a check_suite webhook (GitHubCheckSuiteEventModel).

GitHubCheckSuiteStatus(value[, names, ...])

The status of a GitHub check suite.

GitHubPullRequestHeadModel

A Pydantic model for the last commit to the head branch of a PR.

GitHubPullRequestModel

A Pydantic model for a GitHub Pull Request.

GitHubPullState(value[, names, module, ...])

The state of a GitHub pull request (PR).

GitHubRepoOwnerModel

A Pydantic model for the owner field found in repository objects.

GitHubRepositoryModel

A Pydantic model for the repository field, often found in webhook payloads.

GitHubUserModel

A Pydantic model for the user field found in GitHub API resources.

Class Inheritance Diagram#

Inheritance diagram of safir.github.models.GitHubBlobModel, safir.github.models.GitHubBranchCommitModel, safir.github.models.GitHubBranchModel, safir.github.models.GitHubCheckRunAnnotationLevel, safir.github.models.GitHubCheckRunConclusion, safir.github.models.GitHubCheckRunModel, safir.github.models.GitHubCheckRunOutput, safir.github.models.GitHubCheckRunPrInfoModel, safir.github.models.GitHubCheckRunStatus, safir.github.models.GitHubCheckSuiteConclusion, safir.github.models.GitHubCheckSuiteId, safir.github.models.GitHubCheckSuiteModel, safir.github.models.GitHubCheckSuiteStatus, safir.github.models.GitHubPullRequestHeadModel, safir.github.models.GitHubPullRequestModel, safir.github.models.GitHubPullState, safir.github.models.GitHubRepoOwnerModel, safir.github.models.GitHubRepositoryModel, safir.github.models.GitHubUserModel

safir.github.webhooks Module#

Pydantic models for GitHub webhook payloads.

Classes#

GitHubAppInstallationEventAction(value[, ...])

The action performed on an GitHub App installation webhook (GitHubAppInstallationEventModel).

GitHubAppInstallationEventModel

A Pydantic model for an installation webhook.

GitHubAppInstallationEventRepoModel

A pydantic model for repository objects used by GitHubAppInstallationRepositoriesEventModel.

GitHubAppInstallationModel

A Pydantic model for the installation field found in webhook payloads for GitHub Apps.

GitHubAppInstallationRepositoriesEventAction(value)

The action performed on a GitHub App installation_repositories webhook (GitHubAppInstallationRepositoriesEventModel).

GitHubAppInstallationRepositoriesEventModel

A Pydantic model for a installation_repositories webhook.

GitHubCheckRunEventAction(value[, names, ...])

The action performed in a GitHub check_run webhook (GitHubCheckRunEventModel).

GitHubCheckRunEventModel

A Pydantic model for the check_run webhook payload.

GitHubCheckSuiteEventAction(value[, names, ...])

The action performed in a GitHub check_suite webhook (GitHubCheckSuiteEventModel).

GitHubCheckSuiteEventModel

A Pydantic model for the check_suite webhook payload.

GitHubPullRequestEventAction(value[, names, ...])

The action performed on a GitHub pull_request webhook (GitHubPullRequestEventModel).

GitHubPullRequestEventModel

A Pydantic model for a pull_request webhook.

GitHubPushEventModel

A Pydantic model for the push event webhook when a commit or tag is pushed.

Class Inheritance Diagram#

Inheritance diagram of safir.github.webhooks.GitHubAppInstallationEventAction, safir.github.webhooks.GitHubAppInstallationEventModel, safir.github.webhooks.GitHubAppInstallationEventRepoModel, safir.github.webhooks.GitHubAppInstallationModel, safir.github.webhooks.GitHubAppInstallationRepositoriesEventAction, safir.github.webhooks.GitHubAppInstallationRepositoriesEventModel, safir.github.webhooks.GitHubCheckRunEventAction, safir.github.webhooks.GitHubCheckRunEventModel, safir.github.webhooks.GitHubCheckSuiteEventAction, safir.github.webhooks.GitHubCheckSuiteEventModel, safir.github.webhooks.GitHubPullRequestEventAction, safir.github.webhooks.GitHubPullRequestEventModel, safir.github.webhooks.GitHubPushEventModel

safir.kafka Package#

Classes#

AIOKafkaParams

Type for parameters to the constructor of an aiokafka client.

Compatibility(value[, names, module, ...])

Schema registry compatibility types.

FastStreamBrokerParams

Type for parameters to the constructor of a FastStream broker.

IncompatibleSchemaError

A schema is incompatible with the latest version in the registry.

InvalidAvroNameError

The decalred name or namespace for an Avro schema is not valid.

InvalidMetadataError

The Meta inner class on a model has unexpected values in fields.

KafkaConnectionSettings

Settings for connecting to Kafka.

PlaintextSettings

Subset of settings required for Plaintext auth.

PydanticSchemaManager(registry[, suffix, logger])

A manager for schemas that are represented as Pydantic models in Python, and translated into Avro for the Confluent Schema Registry.

SaslMechanism(value[, names, module, ...])

Kafka SASL mechanisms.

SaslPlaintextSettings

Subset of settings required for SASL SSLauth.

SaslSslSettings

Subset of settings required for SASL PLAINTEXT auth.

SchemaInfo(schema, schema_id, subject)

Schema and registry metadata.

SchemaManagerSettings

Settings for constructing a PydanticSchemaManager.

SchemaRegistryClientParams

Kwargs used to construct an AsyncSchemaRegistryClient.

SecurityProtocol(value[, names, module, ...])

Kafka SASL security protocols.

SslSettings

Subset of settings required for SSL auth.

UnknownDeserializeError

The schema registry client returns None when deserializing.

UnknownSchemaError(data, subject)

A schema is not managed by the Registry, and therefore cannot be serialized into a native Python object.

Class Inheritance Diagram#

Inheritance diagram of safir.kafka._kafka_config.AIOKafkaParams, safir.kafka._manager.Compatibility, safir.kafka._kafka_config.FastStreamBrokerParams, safir.kafka._exceptions.IncompatibleSchemaError, safir.kafka._exceptions.InvalidAvroNameError, safir.kafka._exceptions.InvalidMetadataError, safir.kafka._kafka_config.KafkaConnectionSettings, safir.kafka._kafka_config.PlaintextSettings, safir.kafka._manager.PydanticSchemaManager, safir.kafka._kafka_config.SaslMechanism, safir.kafka._kafka_config.SaslPlaintextSettings, safir.kafka._kafka_config.SaslSslSettings, safir.kafka._manager.SchemaInfo, safir.kafka._schema_registry_config.SchemaManagerSettings, safir.kafka._schema_registry_config.SchemaRegistryClientParams, safir.kafka._kafka_config.SecurityProtocol, safir.kafka._kafka_config.SslSettings, safir.kafka._exceptions.UnknownDeserializeError, safir.kafka._exceptions.UnknownSchemaError

safir.kubernetes Package#

Utilities for configuring a Kubernetes client.

Functions#

initialize_kubernetes()

Load the Kubernetes configuration.

safir.logging Package#

Utilities for configuring structlog-based logging.

Functions#

add_log_severity(logger, method_name, event_dict)

Add the log level to the event dict as severity.

configure_alembic_logging([log_level])

Set up logging for Alembic.

configure_logging(*, name[, profile, ...])

Configure logging and structlog.

configure_uvicorn_logging([log_level])

Set up logging.

Classes#

LogLevel(value[, names, module, qualname, ...])

Python logging level.

Profile(value[, names, module, qualname, ...])

Logging profile for the application.

Class Inheritance Diagram#

Inheritance diagram of safir.logging._models.LogLevel, safir.logging._models.Profile

safir.metadata Package#

Standardized metadata for Roundtable and Phalanx HTTP services.

Functions#

get_metadata(*, package_name, application_name)

Retrieve metadata for the application.

get_project_url(meta, label)

Get a specific URL from a package's project_urls metadata.

Classes#

Metadata

Metadata about a package.

Class Inheritance Diagram#

Inheritance diagram of safir.metadata._models.Metadata

safir.metrics Package#

Functions#

initialize_arq_metrics(event_manager, ctx)

Create Arq metrics publishers and inject them into the Arq context.

make_on_job_start(queue_name)

Make a function that publishes an event for every job execution.

metrics_configuration_factory()

Choose an appropriate metrics configuration based on the environment.

publish_queue_stats(queue, redis_settings, ...)

Publish an event containing statistics about an Arq queue.

Classes#

ArqEvents()

Container for Arq metrics event publishers.

ArqQueueJobEvent

Metrics for every job run by Arq.

ArqQueueStatsEvent

Statistics for an Arq queue.

BaseAssertionError(expected, actual, ...)

Base assertion error with common attributes and messaging.

BaseMetricsConfiguration

Metrics configuration, including the required Kafka configuration.

DisabledMetricsConfiguration

Metrics configuration when metrics reporting is disabled.

DuplicateEventError(name)

Two publishers were registered with the same name.

EventManager(topic[, logger])

Interface for a client for publishing application metrics events.

EventManagerUnintializedError

An attempt to create a publisher after manager has been initialized.

EventManagerUsageError

These exceptions should be raised even in abandonable methods.

EventMetadata

Common fields for all metrics events.

EventPayload

All event payloads should inherit from this.

EventPublisher(application, event_class)

Interface for event publishers.

EventsConfiguration

Configuration for emitting events.

FailedEventPublisher(application, ...)

Event publisher that logs error messages instead of publishing.

KafkaEventManager(*, application, ...[, ...])

A tool for publishing application metrics events.

KafkaEventPublisher(*, application, manager, ...)

Publishes one type of event.

KafkaMetricsConfiguration

Metrics configuration when enabled, including Kafka configuration.

KafkaTopicError(topic)

A topic does not exist in Kafka, or we don't have access to it.

MockEventManager(application, topic_prefix)

An event manager that creates mock publishers that record all publishes.

MockEventPublisher(application, event_class, ...)

Event publisher that quietly does nothing and records all payloads.

MockMetricsConfiguration

Metrics configuration when metrics publishing is mocked.

NoopEventManager(application, topic_prefix)

An event manager that creates publishers that quietly do nothing.

NoopEventPublisher(application, event_class, ...)

Event publisher that quietly does nothing.

NotPublishedConsecutivelyError(expected, ...)

Expected events were not published consecutively.

NotPublishedError(*, expected, actual, ...)

Some expected items were not published.

PublishedCountError(expected, actual, ...)

Expected has a different number of items than were published.

PublishedList([iterable])

A list of event payload models with assertion helpers.

PublishedTooFewError(expected, actual, ...)

Expected more events than have actually been published.

UnsupportedAvroSchemaError

Event model is not serializable to Avro.

Variables#

ANY

A helper object that compares equal to everything.

ARQ_EVENTS_CONTEXT_KEY

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

NOT_NONE

A helper object that compares equal to everything except None.

MetricsConfiguration

Type alias.

Class Inheritance Diagram#

Inheritance diagram of safir.metrics._arq.ArqEvents, safir.metrics._arq.ArqQueueJobEvent, safir.metrics._arq.ArqQueueStatsEvent, safir.metrics._testing.BaseAssertionError, safir.metrics._config.BaseMetricsConfiguration, safir.metrics._config.DisabledMetricsConfiguration, safir.metrics._exceptions.DuplicateEventError, safir.metrics._event_manager.EventManager, safir.metrics._exceptions.EventManagerUnintializedError, safir.metrics._exceptions.EventManagerUsageError, safir.metrics._models.EventMetadata, safir.metrics._models.EventPayload, safir.metrics._event_manager.EventPublisher, safir.metrics._config.EventsConfiguration, safir.metrics._event_manager.FailedEventPublisher, safir.metrics._event_manager.KafkaEventManager, safir.metrics._event_manager.KafkaEventPublisher, safir.metrics._config.KafkaMetricsConfiguration, safir.metrics._exceptions.KafkaTopicError, safir.metrics._event_manager.MockEventManager, safir.metrics._event_manager.MockEventPublisher, safir.metrics._config.MockMetricsConfiguration, safir.metrics._event_manager.NoopEventManager, safir.metrics._event_manager.NoopEventPublisher, safir.metrics._testing.NotPublishedConsecutivelyError, safir.metrics._testing.NotPublishedError, safir.metrics._testing.PublishedCountError, safir.metrics._testing.PublishedList, safir.metrics._testing.PublishedTooFewError, safir.metrics._exceptions.UnsupportedAvroSchemaError

safir.models Package#

Standard models for FastAPI applications.

Notes

FastAPI does not appear to export its error response model in a usable form, so define a copy of it so that we can reference it in API definitions to generate good documentation.

Classes#

ErrorDetail

The detail of the error message.

ErrorLocation(value[, names, module, ...])

Possible locations for an error.

ErrorModel

A structured API error message.

Class Inheritance Diagram#

Inheritance diagram of safir.models._errors.ErrorDetail, safir.models._errors.ErrorLocation, safir.models._errors.ErrorModel

safir.middleware.ivoa Module#

Middleware for IVOA services.

Classes#

CaseInsensitiveFormMiddleware(app)

Make POST parameter keys all lowercase.

CaseInsensitiveQueryMiddleware(app)

Make query parameter keys all lowercase.

Class Inheritance Diagram#

Inheritance diagram of safir.middleware.ivoa.CaseInsensitiveFormMiddleware, safir.middleware.ivoa.CaseInsensitiveQueryMiddleware

safir.middleware.x_forwarded Module#

Update the request based on X-Forwarded-For headers.

Classes#

XForwardedMiddleware(app, *[, proxies])

ASGI middleware to update the request based on X-Forwarded-For.

Class Inheritance Diagram#

Inheritance diagram of safir.middleware.x_forwarded.XForwardedMiddleware

safir.pydantic Package#

Utilities for Pydantic models.

Functions#

normalize_datetime(v)

Pydantic field validator for datetime fields.

normalize_isodatetime(v)

Pydantic field validator for datetime fields in ISO format.

to_camel_case(string)

Convert a string to camel case.

validate_exactly_one_of(*settings)

Generate a model validator imposing a one and only one constraint.

Classes#

CamelCaseModel

pydantic.BaseModel configured to accept camel-case input.

Class Inheritance Diagram#

Inheritance diagram of safir.pydantic._camel.CamelCaseModel

safir.redis Package#

Redis database support.

Classes#

DeserializeError(msg, key, error)

Raised when a stored Pydantic object in Redis cannot be decoded (and possibly decrypted) or deserialized.

EncryptedPydanticRedisStorage(*, datatype, ...)

A Pydantic-based Redis store that encrypts data.

PydanticRedisStorage(*, datatype, redis[, ...])

JSON-serialized encrypted storage in Redis.

Class Inheritance Diagram#

Inheritance diagram of safir.redis._storage.DeserializeError, safir.redis._storage.EncryptedPydanticRedisStorage, safir.redis._storage.PydanticRedisStorage

safir.sentry Package#

Sentry helpers.

Functions#

before_send_handler(event, hint)

Add the env to the fingerprint, and enrich from SentryException.

duration(span)

Return the time spent in a span (to the present if not finished).

fingerprint_env_handler(event, _)

Add the environment to the event fingerprint.

sentry_exception_handler(event, hint)

Add tags and context from SentryException.

Classes#

SentryException(message)

Enriches the Sentry context when paired with the enrich handler.

SentryWebException(message, *[, method, ...])

Parent class of exceptions arising from HTTPX failures.

Class Inheritance Diagram#

Inheritance diagram of safir.sentry._exceptions.SentryException, safir.sentry._exceptions.SentryWebException

safir.slack.blockkit Module#

Slack Block Kit message models.

Classes#

SlackBaseBlock

Base class for any Slack Block Kit block.

SlackBaseField

Base class for Slack Block Kit blocks for the fields section.

SlackCodeBlock

A component of a Slack message with a heading and a code block.

SlackCodeField

An attachment in a Slack message with a heading and text body.

SlackException(message[, user, failed_at])

Parent class of exceptions that can be reported to Slack.

SlackMessage

Message to post to Slack.

SlackTextBlock

A component of a Slack message with a heading and a text body.

SlackTextField

One field in a Slack message with a heading and text body.

SlackWebException(message, *[, failed_at, ...])

Parent class of exceptions arising from HTTPX failures.

Class Inheritance Diagram#

Inheritance diagram of safir.slack.blockkit.SlackBaseBlock, safir.slack.blockkit.SlackBaseField, safir.slack.blockkit.SlackCodeBlock, safir.slack.blockkit.SlackCodeField, safir.slack.blockkit.SlackException, safir.slack.blockkit.SlackMessage, safir.slack.blockkit.SlackTextBlock, safir.slack.blockkit.SlackTextField, safir.slack.blockkit.SlackWebException

safir.slack.webhook Module#

Send messages to Slack.

Classes#

SlackIgnoredException

Parent class for exceptions that should not be reported to Slack.

SlackRouteErrorHandler(path, endpoint, *[, ...])

Custom fastapi.routing.APIRoute that reports exceptions to Slack.

SlackWebhookClient(hook_url, application, logger)

Send messages to a Slack webhook.

Class Inheritance Diagram#

Inheritance diagram of safir.slack.webhook.SlackIgnoredException, safir.slack.webhook.SlackRouteErrorHandler, safir.slack.webhook.SlackWebhookClient

safir.testing.containers Package#

Safir-provided test containers.

Classes#

FullKafkaContainer([image, port, ssl_port, ...])

Kafka container.

SchemaRegistryContainer(network[, ...])

A Testcontainers Confluent schema registry container.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.containers._kafka.FullKafkaContainer, safir.testing.containers._schema_registry.SchemaRegistryContainer

safir.testing.gcs Package#

Mock Google Cloud Storage API for testing.

Functions#

patch_google_storage(*[, ...])

Replace the Google Cloud Storage API with a mock class.

Classes#

MockBlob(name[, expected_expiration])

Mock version of google.cloud.storage.blob.Blob.

MockBucket(bucket_name[, ...])

Mock version of google.cloud.storage.bucket.Bucket.

MockStorageClient([expected_expiration, ...])

Mock version of google.cloud.storage.Client.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.gcs._mock.MockBlob, safir.testing.gcs._mock.MockBucket, safir.testing.gcs._mock.MockStorageClient

safir.testing.kubernetes Package#

Mock Kubernetes API and utility functions for testing.

Functions#

patch_kubernetes()

Replace the Kubernetes API with a mock class.

strip_none(model)

Strip None values from a serialized Kubernetes object.

Classes#

MockKubernetesApi()

Mock Kubernetes API for testing.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.kubernetes._mock.MockKubernetesApi

safir.testing.logging Package#

Helper functions for testing logging.

Functions#

parse_log_tuples(logger_name, record_tuples, *)

Parse JSON log record tuples into structured data.

safir.testing.sentry Package#

Helpers for testing Sentry reporting.

Functions#

capture_events_fixture(monkeypatch)

Return a function that returns a container with items sent to Sentry.

sentry_init_fixture()

Return an init function that injects a no-op transport.

Classes#

Attachment(filename, bytes, content_type)

Contents and metadata of a Sentry attachment.

Captured(errors, transactions, attachments)

A container for interesting items sent to Sentry.

TestTransport()

A transport that doesn't actually transport anything.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.sentry._mocks.Attachment, safir.testing.sentry._mocks.Captured, safir.testing.sentry._mocks.TestTransport

safir.testing.slack Package#

Mock Slack server for testing Slack messaging.

Functions#

mock_slack_webhook(hook_url, respx_mock)

Set up a mocked Slack server.

Classes#

MockSlackWebhook(url)

Represents a Slack incoming webhook and remembers what was posted.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.slack._mocks.MockSlackWebhook

safir.testing.uvicorn Package#

Utility functions for managing an external Uvicorn test process.

Functions#

spawn_uvicorn(*, working_directory[, app, ...])

Spawn an ASGI app as a separate Uvicorn process.

Classes#

ServerNotListeningError

Timeout waiting for the server to start listening.

UvicornProcess(process, url)

Properties of the running Uvicorn service.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.uvicorn._spawn.ServerNotListeningError, safir.testing.uvicorn._spawn.UvicornProcess

safir.testing.uws Package#

Mocks and functions for testing services using the Safir UWS support.

Functions#

assert_job_summary_equal(job_summary_type, ...)

Assert that two job XML documents are equal.

patch_wobbly(respx_mock, wobbly_url)

Set up the mock for a Wobbly server.

Classes#

MockUWSJobRunner(config, arq_queue)

Simulate execution of jobs with a mock queue.

MockWobbly()

Mock the Wobbly web service, which stores UWS job information.

Class Inheritance Diagram#

Inheritance diagram of safir.testing.uws._mocks.MockUWSJobRunner, safir.testing.uws._mocks.MockWobbly

safir.uws Package#

Support library for writing UWS-enabled services.

Classes#

Job

A single UWS job with deserialized parameters.

JobBase

Fields common to all variations of the job record.

JobCreate

Information required to create a new UWS job (Wobbly format).

JobError

Failure information about a job.

JobResult

A single result from a job.

JobUpdateAborted

Input model when aborting a job.

JobUpdateCompleted

Input model when marking a job as complete.

JobUpdateError

Input model when marking a job as failed.

JobUpdateExecuting

Input model when marking a job as executing.

JobUpdateMetadata

Input model when updating job metadata.

JobUpdateQueued

Input model when marking a job as queued.

ParameterError(message[, detail])

Unsupported value passed to a parameter.

ParametersModel

Defines the interface for a model suitable for job parameters.

SerializedJob

A single UWS job (Wobbly format).

UWSAppSettings

Settings common to all applications using the UWS library.

UWSApplication(config)

Glue between a FastAPI application and the UWS implementation.

UWSConfig(arq_mode, arq_redis_settings, ...)

Configuration for the UWS service.

UWSError(error_code, message[, detail])

An error with an associated error code.

UWSRoute(dependency, summary[, description])

Defines a FastAPI dependency to get the UWS job parameters.

UsageError(message[, detail])

Invalid parameters were passed to a UWS API.

Class Inheritance Diagram#

Inheritance diagram of safir.uws._models.Job, safir.uws._models.JobBase, safir.uws._models.JobCreate, safir.uws._models.JobError, safir.uws._models.JobResult, safir.uws._models.JobUpdateAborted, safir.uws._models.JobUpdateCompleted, safir.uws._models.JobUpdateError, safir.uws._models.JobUpdateExecuting, safir.uws._models.JobUpdateMetadata, safir.uws._models.JobUpdateQueued, safir.uws._exceptions.ParameterError, safir.uws._models.ParametersModel, safir.uws._models.SerializedJob, safir.uws._config.UWSAppSettings, safir.uws._app.UWSApplication, safir.uws._config.UWSConfig, safir.uws._exceptions.UWSError, safir.uws._config.UWSRoute, safir.uws._exceptions.UsageError