Registration and errors

How to add support for a new URL scheme or a new path library, and the two errors these paths can raise.

bagof.paths.register_protocol

register_protocol(scheme: str, *, bucketed: bool = False, absolute: bool = False, aliases: Iterable[str] = (), driver: Callable[..., Any] | None = None, storage_options: Mapping[str, Any] | None = None) -> None

Register (or replace) the traits for a URL scheme.

A later registration replaces an earlier one wholesale: any trait not passed reverts to its default, aliases and all. Use this to define a scheme, not to tweak one. In particular, re-registering a built-in scheme (s3, gs, az) to add storage_options would drop its bucketed/absolute traits and detach its aliases -- to attach connection options to a scheme that already exists, use :func:set_storage_options, which keeps the other traits.

storage_options gives default connection options (endpoint, credentials, ...) forwarded to the driver for every path of this scheme; a per-call storage_options overrides them key by key.

Register at import time -- see the module note on identity.

bagof.paths.set_storage_options

set_storage_options(scheme: str, storage_options: Mapping[str, Any] | None = None) -> None

Set the default connection options for a URL scheme.

Unlike :func:register_protocol, this keeps the scheme's other traits (bucketed, aliases, the preferred driver). It is the way to attach an endpoint or credentials to a scheme that is already understood::

set_storage_options("s3", {"endpoint_url": "https://minio.local"})

The options replace this scheme's current defaults; a per-call storage_options on the constructor still overrides them key by key. Setting them on an alias sets them on the store it names. Call at import time -- see the module note on identity.

bagof.paths.ProtocolTraits

ProtocolTraits(*, bucketed: bool = False, absolute: bool = False, aliases: Iterable[str] = (), driver: Callable[..., Any] | None = None, storage_options: Mapping[str, Any] | None = None)

What varies about a URL scheme, as data.

Parameters:

Name	Type	Description	Default
`bucketed`	`bool`	The first path component is a bucket/container -- drives `bucket` and the drive/root split.	`False`
`absolute`	`bool`	Paths of this scheme are always absolute (most remote stores).	`False`
`aliases`	`Iterable[str]`	Other schemes that name the same store (`s3a` for `s3`); folded onto this scheme for identity so the spellings compare equal.	`()`
`driver`	`Callable[..., Any] \| None`	A preferred factory (a driver class, or a `str -> path` callable) used to build a path of this scheme before the availability order.	`None`
`storage_options`	`Mapping[str, Any] \| None`	Default connection options (endpoint, credentials, ...) forwarded to the driver for every path of this scheme. Per-call `storage_options` override these key by key. Held as data and never printed -- these commonly hold secrets.	`None`

bagof.paths.register_driver

register_driver(base: type, adapter: GenericAdapter) -> None

Register adapter for a driver base class and its subclasses.

A later registration wins over an earlier one for an object matching both, so a small adapter for a specific class overrides a family default.

bagof.paths.NoDriverError

NoDriverError(scheme: str, *, hint: str | None = None)

Bases: ValueError

No installed driver can interpret a URL's scheme.

Raised at construction, when Path("scheme://...") names a scheme that neither an explicit driver= nor any installed backend can build. It is a ValueError -- the constructor's historical error type for a string it cannot interpret -- so existing except ValueError handlers still catch it, and it says nothing about the scheme being unsupportable in principle: installing a backend (or registering one) can make the same string work.

The scheme is available on the scheme attribute.

bagof.paths.UnsupportedPathOperation

UnsupportedPathOperation(operation: str, *, driver: Any = None, hint: str | None = None)

Bases: _Base

A path operation is not supported by the wrapped object.

Raised when the wrapped object does not implement an operation and it cannot be synthesized from what the object does provide. The message names the operation and, where known, the wrapped driver.