Skip to content

yggdrasil.url.based

based

URLBased

Bases: ABC

Mixin for any class addressable by a :class:URL.

Subclasses declare a class-level scheme: ClassVar[Scheme | None] on the class body; on subclass creation :meth:__init_subclass__ registers the class against that :class:Scheme member in the global :data:_URL_BASED_REGISTRY. The registry is the single source of truth for "what class handles s3://" / "dbfs://" / …; callers either look it up directly (URLBased.for_scheme(...)) or hand a URL to :meth:URLBased.dispatch and let URLBased pick the right subclass.

The two abstract hooks every subclass implements:

  • :meth:from_url(cls, url, **kwargs) — build an instance of the subclass from a :class:URL. Concrete subclasses typically forward to their own __init__.
  • :meth:to_url(self) -> URL — render this instance back to its canonical URL form.

Together these make a :class:URLBased round-trippable through a URL: cls.from_url(obj.to_url()) is the identity for any well-behaved subclass.

for_scheme classmethod 

for_scheme(scheme: Any) -> 'type[URLBased]'

Return the :class:URLBased subclass registered for scheme.

Lazy: if no subclass is registered yet, this routes through :meth:Scheme.path_class which imports the backend module on demand (firing :meth:__init_subclass__ as a side effect).

Raises :class:ValueError for an unknown scheme and :class:ImportError when the backend's optional dependencies aren't installed.

dispatch classmethod 

dispatch(url: Any, **kwargs: Any) -> 'URLBased'

Build the right :class:URLBased subclass from url.

Looks up the subclass via :meth:for_scheme, then delegates to that subclass's :meth:from_url. Used as the cross-cutting entry point when the caller has a URL but doesn't know (or care) which concrete class owns its scheme.

URL.from_(url).scheme drives the lookup; an empty scheme falls back to the file:// handler so bare paths work.