Skip to content

yggdrasil.enums.scheme

scheme

Centralized URL-scheme enum for :class:URLBased dispatch.

Across Yggdrasil, anything addressable by a URL — a filesystem path (file://, s3://, dbfs://, dbfs+volume://), an in-memory buffer (mem://), a Databricks workspace object (dbfs+workspace://), an HTTP endpoint (http:// / https://) — exposes itself as a :class:yggdrasil.url.URLBased subclass. That base owns a single registry keyed by :class:Scheme, and URLBased.from_url(url) dispatches to the concrete subclass for url.scheme without the caller knowing which sub-package owns it.

This module centralizes the scheme tokens and the lazy-import shape so a caller can hand off a URL without first guessing which sub-package implements it: :meth:Scheme.path_class imports the backend module on demand, the import side-effect wires the subclass into the URLBased registry, and the resolved class is returned.

The enum exposes:

  • canonical members for every shipped backend (FILE, MEMORY, DBFS, DATABRICKS_VOLUME, DATABRICKS_WORKSPACE, S3, HTTP, HTTPS);
  • :meth:from_ — forgiving coercion (string / :class:Scheme / None) with alias support ("file://" / "FILE" / "s3a" all land on the right member);
  • :meth:path_class — lazy import of the concrete subclass;
  • :meth:resolve — the from_(...) → path_class() shortcut.

Each backend's class declares scheme = Scheme.DBFS (etc.) on the class body; :meth:URLBased.__init_subclass__ reads that member and registers the class into the cross-cutting registry.

Scheme

Bases: str, Enum

Canonical URL-scheme token for a Yggdrasil :class:URLBased subclass.

Subclasses :class:str so a member is interchangeable with its scheme token everywhere a string is expected (url.scheme == Scheme.DBFS works, f"{Scheme.S3}://bucket/key" reads naturally). The lazy-import resolver lives on :meth:path_class.

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Scheme'

Coerce value to a :class:Scheme member.

Accepts:

  • :class:Scheme (returned as-is);
  • a scheme string — case-insensitive, trailing :// and whitespace tolerated, common aliases ("s3a" → :attr:S3, "local" → :attr:FILE, "memory" → :attr:MEMORY);
  • None — returns default if supplied, else raises.

default swallows unknown / unparseable input. Without it, unknown tokens raise :class:ValueError and unsupported types raise :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would succeed for value.

path_class 

path_class() -> 'type[URLBased]'

Return the concrete :class:URLBased subclass for this scheme.

Lazy: the backend module is imported on first use, which fires the :meth:URLBased.__init_subclass__ side-effect that registers the class. Subsequent calls hit the per-process cache.

Raises :class:ImportError when the backend's optional dependencies aren't installed (databricks-sdk for the Databricks schemes, boto3 for s3, …) — the message names the missing extra so the caller can install it.

resolve classmethod 

resolve(value: Any, *, default: Any = ...) -> 'type[URLBased]'

Shortcut: cls.from_(value).path_class().

Useful where the caller has a raw scheme string (or URL) and just wants the concrete URLBased class. default is forwarded to :meth:from_ for forgiving lookup; it does not catch :class:ImportError from :meth:path_class.