Paths and File Access

s2gos_utils.io.paths.PathRef pydantic-model

PathRef(href=None, cid=None, **kwargs)

Bases: BaseModel

Path configuration that preserves credential reference through serialization.

This model allows paths to reference credentials by ID rather than embedding actual credentials. When serialized to JSON it is structurally an OGC Link: {"href": <path/URI>, "x-cid": <credential id>} (only the path and the credential reference are stored, never actual credentials). When deserialized, credentials are resolved from the credential provider (environment variables or .secrets.yaml).

Attributes:

Name	Type	Description
href	str	The actual path/URI (the OGC Link href).
type	str | None	Optional Link media (MIME) type.
options	dict[str, Any] | None	Optional extra client options (serialized as x-options), for opener/storage config beyond credentials.
cid	str | None	Optional reference to a Credential ID in the credential provider. Serialized as the x-cid Link extension.

Example

With credentials

path = PathRef( "https://data.earthdatahub.destine.eu/data.zarr", cid="earthdatahub" )

Without credentials (public or local path)

path = PathRef("/local/path/data.zarr")

Access the authenticated UPath

upath = path.upath

Config:

• frozen: True
• populate_by_name: True
• serialize_by_alias: True

Fields:

• href (str)
• type (str | None)
• options (dict[str, Any] | None)
• cid (str | None)

Validators:

• _coerce

Attributes

cid pydantic-field

cid: str | None = None

Credential ID

href pydantic-field

href: str

Full path URI

options pydantic-field

options: dict[str, Any] | None = None

Extra client options for accessing href in its storage

type pydantic-field

type: str | None = None

Media (MIME) type

upath property

upath: UPath

Get the authenticated UPath by resolving credentials.

If cid is set, retrieves the credential from the credential provider and constructs an authenticated UPath. Otherwise returns a simple UPath without authentication.

Returns:

Type	Description
UPath	UPath object with authentication if cid is set

Raises:

Type	Description
CredentialNotFoundError	If cid is set but the credential is not found in the active provider.

Functions

__str__

__str__() -> str

Return the path value as a string.

__truediv__

__truediv__(other) -> PathRef

Returns the joined path, preserving the credential id.

to_dict

to_dict() -> dict[str, Any]

Alias to model_dump.