GitHub

PathService

API reference for PathService.

Path over one platform's rules.

Attributes

AttributeTypeDescription
sepstr

The separator between a path's parts (/, or \ on Windows).

delimiterstr

What separates paths in a list such as PATH (:, or ; on Windows).

Functions

__init__

__init__(rules, *, windows) -> None
ParameterTypeDescription
rules_Rules
windowsbool
def __init__(self, rules: _Rules, *, windows: bool) -> None:
    self._rules = rules
    self._windows = windows

basename

basename(path, suffix='') -> str

The last part of path, without suffix when it ends with it (and is more than it).

ParameterTypeDescription
pathstr
suffixstr = ''

Returns str

def basename(self, path: str, suffix: str = "") -> str:
    """The last part of ``path``, without ``suffix`` when it ends with
    it (and is more than it)."""
    return self._rules.basename(path, suffix)

dirname

dirname(path) -> str

path without its last part ("." when nothing is left, the root for the root).

ParameterTypeDescription
pathstr

Returns str

def dirname(self, path: str) -> str:
    """``path`` without its last part (``"."`` when nothing is left,
    the root for the root)."""
    return self._rules.dirname(path)

extname

extname(path) -> str

The extension of the last part, dot included ("" for .bashrc).

ParameterTypeDescription
pathstr

Returns str

def extname(self, path: str) -> str:
    """The extension of the last part, dot included (``""`` for
    ``.bashrc``)."""
    return self._rules.extname(path)

format

format(*, root='', dir='', base='', name='', ext='') -> str

Node's path.format: dir (else root), then base (else name and ext, which gets a dot if it has none).

ParameterTypeDescription
rootstr = ''
dirstr = ''
basestr = ''
namestr = ''
extstr = ''

Returns str

def format(
    self, *, root: str = "", dir: str = "", base: str = "", name: str = "", ext: str = ""
) -> str:
    """Node's ``path.format``: ``dir`` (else ``root``), then ``base``
    (else ``name`` and ``ext``, which gets a dot if it has none)."""
    directory = dir or root
    last = base or name + (ext if not ext or ext[0] == "." else "." + ext)
    if not directory:
        return last
    if directory == root:
        return directory + last
    return directory + self.sep + last

from_file_url

from_file_url(url) -> Effect[str, BadArgument]

The path a file: URL names. Fails for another scheme, a host (but a Windows share), an encoded separator or a broken escape.

ParameterTypeDescription
urlUrl

Returns Effect[str, BadArgument]

def from_file_url(self, url: Url) -> Effect[str, BadArgument]:
    """The path a ``file:`` URL names. Fails for another scheme, a host
    (but a Windows share), an encoded separator or a broken escape."""
    if url.protocol != "file:":
        return _bad_url("URL must be of scheme file")
    host = url.hostname
    if host and not self._windows:
        return _bad_url("Invalid file URL host")
    path = url.pathname
    encoded = _ENCODED_SEPARATOR.search(path) or (
        self._windows and _ENCODED_BACKSLASH.search(path)
    )
    if encoded:
        return _bad_url("must not include encoded / characters")
    try:
        decoded = _decode_uri_component(path)
    except ValueError as error:
        return fail(BadArgument(module="Path", method="from_file_url", cause=error))
    return succeed(_windows_path(host, decoded) if self._windows else decoded)

is_absolute

is_absolute(path) -> bool

Whether path starts at a root (on Windows, a drive root, a separator or a share), not at the working directory.

ParameterTypeDescription
pathstr

Returns bool

def is_absolute(self, path: str) -> bool:
    """Whether ``path`` starts at a root (on Windows, a drive root, a
    separator or a share), not at the working directory."""
    return self._rules.is_absolute(path)

join

join(*paths) -> str

The non-empty paths joined with the separator and normalized ("." when there are none).

ParameterTypeDescription
pathsstr = ()

Returns str

def join(self, *paths: str) -> str:
    """The non-empty ``paths`` joined with the separator and normalized
    (``"."`` when there are none)."""
    return self._rules.join(*paths)

normalize

normalize(path) -> str

path with . and .. parts resolved and repeated separators merged, a trailing separator kept ("." for an empty path).

ParameterTypeDescription
pathstr

Returns str

def normalize(self, path: str) -> str:
    """``path`` with ``.`` and ``..`` parts resolved and repeated
    separators merged, a trailing separator kept (``"."`` for an empty
    path)."""
    return self._rules.normalize(path)

parse

parse(path) -> Parsed

The parts of path: its root, directory, base, name and extension.

ParameterTypeDescription
pathstr

Returns Parsed

def parse(self, path: str) -> Parsed:
    """The parts of ``path``: its root, directory, base, name and
    extension."""
    return Parsed(*self._rules.parse(path))

relative

relative(from_, to) -> str

The path from from_ to to, both resolved first; to resolved when no relative path leads there (another drive).

ParameterTypeDescription
from_str
tostr

Returns str

def relative(self, from_: str, to: str) -> str:
    """The path from ``from_`` to ``to``, both resolved first; ``to``
    resolved when no relative path leads there (another drive)."""
    return self._rules.relative(from_, to)

resolve

resolve(*segments) -> str

The absolute path segments lead to from the working directory.

ParameterTypeDescription
segmentsstr = ()

Returns str

def resolve(self, *segments: str) -> str:
    """The absolute path ``segments`` lead to from the working
    directory."""
    return self._rules.resolve(*segments)

resolve_within

resolve_within(root, input) -> str | None

input resolved below root, or None when it is rooted or leads outside root (a .. past it).

ParameterTypeDescription
rootstr
inputstr

Returns str | None

def resolve_within(self, root: str, input: str) -> str | None:
    """``input`` resolved below ``root``, or ``None`` when it is rooted
    or leads outside ``root`` (a ``..`` past it)."""
    if self.parse(input).root != "":
        return None
    base = self.resolve(root)
    candidate = self.resolve(base, input)
    relative = self.relative(base, candidate)
    if relative == ".." or relative.startswith(".." + self.sep) or self.is_absolute(relative):
        return None
    return candidate

to_file_url

to_file_url(path) -> Effect[Url, BadArgument]

The file: URL of path, made absolute first (a trailing separator kept); %, \, tab and newlines are escaped.

ParameterTypeDescription
pathstr

Returns Effect[Url, BadArgument]

def to_file_url(self, path: str) -> Effect[Url, BadArgument]:
    """The ``file:`` URL of ``path``, made absolute first (a trailing
    separator kept); ``%``, ``\\``, tab and newlines are escaped."""
    resolved = self.resolve(path)
    host = ""
    if self._windows:
        resolved = resolved.replace("\\", "/")
        if resolved.startswith("//"):
            host, _, rest = resolved[2:].partition("/")
            resolved = "/" + rest
        else:
            resolved = "/" + resolved
    elif path.endswith("/") and not resolved.endswith("/"):
        resolved += "/"
    record = setters.set_pathname(Url("file://").record, _encode_path_chars(resolved))
    if host:
        record = setters.set_hostname(record, host)
    return succeed(Url.from_record(record))

to_namespaced_path

to_namespaced_path(path) -> str

Windows' \\?\ form of an absolute path; on POSIX, path.

ParameterTypeDescription
pathstr

Returns str

def to_namespaced_path(self, path: str) -> str:
    """Windows' ``\\\\?\\`` form of an absolute path; on POSIX, ``path``."""
    return self._rules.to_namespaced_path(path)