Registry

The UPath registry system manages filesystem-specific path implementations. It allows you to register custom UPath subclasses for different protocols and retrieve the appropriate implementation for a given protocol.

Functions

get_upath_class cached

get_upath_class(
    protocol: Literal["simplecache"],
) -> type[SimpleCachePath]

get_upath_class(
    protocol: Literal["s3", "s3a"],
) -> type[S3Path]

get_upath_class(
    protocol: Literal["gcs", "gs"],
) -> type[GCSPath]

get_upath_class(
    protocol: Literal["abfs", "abfss", "adl", "az"],
) -> type[AzurePath]

get_upath_class(
    protocol: Literal["data"],
) -> type[DataPath]

get_upath_class(protocol: Literal['ftp']) -> type[FTPPath]

get_upath_class(
    protocol: Literal["github"],
) -> type[GitHubPath]

get_upath_class(
    protocol: Literal["hdfs"],
) -> type[HDFSPath]

get_upath_class(protocol: Literal['hf']) -> type[HfPath]

get_upath_class(
    protocol: Literal["http", "https"],
) -> type[HTTPPath]

get_upath_class(
    protocol: Literal["file", "local"],
) -> type[FilePath]

get_upath_class(
    protocol: Literal["memory"],
) -> type[MemoryPath]

get_upath_class(
    protocol: Literal["sftp", "ssh"],
) -> type[SFTPPath]

get_upath_class(protocol: Literal['smb']) -> type[SMBPath]

get_upath_class(protocol: Literal['tar']) -> type[TarPath]

get_upath_class(
    protocol: Literal["webdav"],
) -> type[WebdavPath]

get_upath_class(protocol: Literal['zip']) -> type[ZipPath]

get_upath_class(
    protocol: Literal[""],
) -> type[WindowsUPath]

get_upath_class(protocol: Literal['']) -> type[PosixUPath]

get_upath_class(
    protocol: str, *, fallback: bool = ...
) -> type[UPath] | None

get_upath_class(
    protocol: str, *, fallback: bool = True
) -> type[UPath] | None

Return the upath cls for the given protocol.

Returns None if no matching protocol can be found.

PARAMETER	DESCRIPTION
protocol	The protocol string TYPE: str
fallback	If fallback is False, don't return UPath instances for fsspec filesystems that don't have an implementation registered. TYPE: bool DEFAULT: True

Source code in upath/registry.py

@lru_cache  # type: ignore[misc] # see: https://github.com/python/typeshed/issues/11280
def get_upath_class(
    protocol: str,
    *,
    fallback: bool = True,
) -> type[upath.UPath] | None:
    """Return the upath cls for the given protocol.

    Returns `None` if no matching protocol can be found.

    Parameters
    ----------
    protocol:
        The protocol string
    fallback:
        If fallback is False, don't return UPath instances for fsspec
        filesystems that don't have an implementation registered.
    """
    try:
        return _registry[protocol]
    except KeyError:
        if not protocol:
            if os.name == "nt":
                from upath.implementations.local import WindowsUPath

                return WindowsUPath  # type: ignore[return-value]
            else:
                from upath.implementations.local import PosixUPath

                return PosixUPath  # type: ignore[return-value]
        if not fallback:
            return None
        try:
            get_filesystem_class(protocol)
        except ValueError:
            return None  # this is an unknown protocol
        else:
            warnings.warn(
                f"UPath {protocol!r} filesystem not explicitly implemented."
                " Falling back to default implementation."
                " This filesystem may not be tested.",
                UserWarning,
                stacklevel=2,
            )
            import upath.implementations._experimental as upath_experimental

            cls_name = f"_{protocol.title()}Path"
            cls = type(
                cls_name,
                (upath.UPath,),
                {"__module__": "upath.implementations._experimental"},
            )
            setattr(upath_experimental, cls_name, cls)
            return cls

register_implementation

register_implementation(
    protocol: str,
    cls: type[UPath] | str,
    *,
    clobber: bool = False,
) -> None

register a UPath implementation with a protocol

PARAMETER	DESCRIPTION
protocol	Protocol name to associate with the class TYPE: str
cls	The UPath subclass for the protocol or a str representing the full path to an implementation class like package.module.class. TYPE: type[UPath] | str
clobber	Whether to overwrite a protocol with the same name; if False, will raise instead. TYPE: bool DEFAULT: False

Source code in upath/registry.py

def register_implementation(
    protocol: str,
    cls: type[upath.UPath] | str,
    *,
    clobber: bool = False,
) -> None:
    """register a UPath implementation with a protocol

    Parameters
    ----------
    protocol:
        Protocol name to associate with the class
    cls:
        The UPath subclass for the protocol or a str representing the
        full path to an implementation class like package.module.class.
    clobber:
        Whether to overwrite a protocol with the same name; if False,
        will raise instead.
    """
    if not re.match(r"^[a-z][a-z0-9+_.]+$", protocol):
        raise ValueError(f"{protocol!r} is not a valid URI scheme")
    if not clobber and protocol in _registry:
        raise ValueError(f"{protocol!r} is already in registry and clobber is False!")
    _registry[protocol] = cls

available_implementations

available_implementations(
    *, fallback: bool = False
) -> list[str]

return a list of protocols for available implementations

PARAMETER	DESCRIPTION
fallback	If True, also return protocols for fsspec filesystems without an implementation in universal_pathlib. TYPE: bool DEFAULT: False

Source code in upath/registry.py

def available_implementations(*, fallback: bool = False) -> list[str]:
    """return a list of protocols for available implementations

    Parameters
    ----------
    fallback:
        If True, also return protocols for fsspec filesystems without
        an implementation in universal_pathlib.
    """
    if not fallback:
        return list(_registry)
    else:
        return list({*_registry, *_fsspec_registry, *_fsspec_known_implementations})

---

See Also

• UPath - Main UPath class documentation
• Implementations - Built-in UPath subclasses
• Extensions - Extending UPath functionality