provcat.uri

Catalog URIs.

A URI has the form scheme://authority/seg/seg?at=kind:value.

The scheme picks a resolver (logical URIs) or a store driver (physical URIs).
The authority is the first name after //. It may be empty, as in file:///tmp. Each store driver and the resolver say whether they need one. It is percent-decoded like a segment.
Segments are percent-decoded. Empty, . and .. segments are refused, so a URI can never climb out of a cache folder. One trailing slash is allowed and dropped, so s3://b/dir/ is s3://b/dir.
The only query parameter is at, the selector. A fragment is refused.

class Selector

Selector(kind: str, value: str)

The ?at=kind:value part of a URI, for example branch:main.

Parameter	Type	Default	Description
`kind`	str	required	The kind of version, such as branch, tag, commit, version, stage or ts
`value`	str	required	The name or the value, such as main

Uri(scheme: str, authority: str, segments: tuple[str, ...] = (), selector: Selector | None = None)

A parsed catalog URI, scheme://authority/seg/seg?at=kind:value. str() writes it back.

Parameter	Type	Default	Description
`scheme`	str	required	A store’s name for a physical URI, or a logical scheme
`authority`	str	required	The first name after //, percent-decoded; it may be empty
`segments`	tuple[str, …]	`()`	The path, one percent-decoded name each
`selector`	Selector \| None	`None`	The ?at= part, or None

Uri.without_selector() -> Uri

Drop the selector.

Parameter	Type	Default	Description
returns	Uri		This URI with no ?at=

Uri.with_selector(selector: Selector | None) -> Uri

Replace the selector.

Parameter	Type	Default	Description
`selector`	Selector \| None	required	The new ?at= part; None drops it
returns	Uri		This URI with the selector replaced

Uri.child(name: str) -> Uri

The URI of a file or folder inside this one; the selector is kept.

Parameter	Type	Default	Description
`name`	str	required	One path segment; empty, ., .., a slash, a backslash or a NUL raises UriError
returns	Uri		This URI with name added to the path

parse(text: str | Uri) -> Uri

Parse a URI string. A Uri passes through unchanged.

Parameter	Type	Default	Description
`text`	str \| Uri	required	The URI as text, or a Uri
returns	Uri		The parsed URI; UriError when the text is not a valid catalog URI