fpathlib 0.1.0__py3-none-any.whl

fpathlib/__init__.py

@@ -0,0 +1,15 @@
+from fpathlib.path import (
+    Path,
+    FPath,
+    ExpandedFPath,
+    expand_fpath,
+    expand_fpath_decorator,
+)
+
+__all__ = [
+    "Path",
+    "FPath",
+    "ExpandedFPath",
+    "expand_fpath",
+    "expand_fpath_decorator",
+]

fpathlib/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

fpathlib/ext/polars.py

@@ -0,0 +1,116 @@
+from functools import wraps
+from polars import *
+import polars as pl
+from fpathlib import expand_fpath_decorator
+
+
+def join_metadata(df, expanded_fpath):
+    return df.join(
+        expanded_fpath.to_polars(lazy=isinstance(df, pl.LazyFrame)),
+        on="fname",
+    )
+
+
+@expand_fpath_decorator(post_process=join_metadata)
+def scan_csv(expanded_fpath, *args, **kwargs):
+    """
+    Scan the paths in the collection as CSV files, and return a
+        :obj:`polars.LazyFrame` along with the metadata captured from the path
+        variables.
+
+    Parameters
+    ----------
+        expanded_fpath : :obj:`fpathlib.ExpandedFPath`
+                An expanded f-string path.
+        *args
+                Positional arguments to pass to :meth:`polars.scan_csv`.
+    **kwargs
+        Keyword arguments to pass to :meth:`polars.scan_csv`.
+
+    Returns
+    -------
+    :obj:`polars.LazyFrame`
+    """
+
+    lf = pl.scan_csv(
+        expanded_fpath,
+        include_file_paths="fname",
+        *args,
+        **kwargs,
+    )
+
+    return lf
+
+
+@expand_fpath_decorator(post_process=join_metadata)
+def scan_txt(
+    expanded_fpath,
+    filter_expr=None,
+    separator=None,
+    new_columns=None,
+    has_header=False,
+    *args,
+    **kwargs,
+):
+    """
+    Scan the paths in the collection as text files, where each line is a
+    record, and return a :obj:`polars.LazyFrame` along with the metadata
+    captured from the path. The text files can also be delimited by
+    `separator`, in which case the lines are split by the separator and each
+    field is a record. The names of these field can be set by `new_columns`.
+
+    Parameters
+    ----------
+    expanded_fpath : :obj:`fpathlib.ExpandedFPath`
+        An expanded f-string path.
+    filter_expr : :obj:`polars.Expr`, optional
+        Filter the lines before splitting by the separator (if provided).
+    separator : :obj:`str`, optional
+        Deliminatorg to split each line into fields.
+    new_columns : :obj:`list`[:obj:`str`], optional
+        List of new column names to rename the fields after splitting by the separator.
+        If not provided, the fields are named as `field_0`, `field_1`, etc.
+    has_header : :obj:`bool`
+        Whether the text files have a header line that should be skipped. The header
+        must have the same delimiter as the separator provided in `separator`.
+        (Default: False)
+    *args
+        Positional arguments to pass to :meth:`polars.scan_csv`.
+    **kwargs
+        Keyword arguments to pass to :meth:`polars.scan_csv`.
+
+    Returns
+    -------
+    :obj:`polars.LazyFrame`
+    """
+
+    # TODO there are forbidden variables that should not be in expanded_fpath
+    # such as 'line' and 'fields' and 'fname'
+
+    lf = pl.scan_csv(
+        expanded_fpath,
+        include_file_paths="fname",
+        separator="\n",
+        new_columns=["line"],
+        has_header=False,
+        **kwargs,
+    )
+
+    if filter_expr is not None:
+        lf = lf.filter(filter_expr)
+
+    if separator is not None:
+        lf = lf.with_columns(fields=pl.col("line").str.split(separator, literal=False))
+        n_fields = lf.select(pl.col("fields").list.len().unique()).collect()
+        if n_fields.shape[0] > 1:
+            msg = "number of fields must be consistent across all lines", n_fields
+            raise ValueError(msg)
+        n_fields = n_fields.item()
+        lf = lf.with_columns(
+            [pl.col("fields").list.get(i).alias(f"field_{i}") for i in range(n_fields)]
+        ).drop(["fields", "line"])
+
+        if new_columns is not None:
+            lf = lf.rename({f"field_{i}": col for i, col in enumerate(new_columns)})
+
+    return lf

fpathlib/path.py

@@ -0,0 +1,309 @@
+from collections.abc import Sequence
+from functools import wraps
+from glob import glob
+import parse
+import pathlib
+import re
+
+from .utils import import_optional_dependency
+
+
+class Path(pathlib.Path):
+    """
+    :obj:`Path` is simply :obj:`pathlib.Path` with metadata.
+
+    Parameters
+    ----------
+    *pathsegments
+    """
+
+    def __init__(self, *pathsegments, metadata=None):
+        super().__init__(*pathsegments)
+        self.metadata = metadata
+
+    def match(self, path_patterns, case_sensitive=None):
+        """
+        Perform :meth:`pathlib.Path.match` on several `path_patterns`.
+
+        Parameters
+        ----------
+        path_patterns : :obj:`str` or :obj:`Iterable`[:obj:`str`]
+            One or more path patterns to match against. (Default: None).
+        case_sensitive : :obj:`bool`
+            Whether to perform case-sensitive matching. If None, the default, then the
+            behavior is determined by the operating system. (Default: None).
+
+        Returns
+        -------
+        :obj:`generator`[:obj:`bool`]
+        """
+
+        if isinstance(path_patterns, str):
+            path_patterns = [path_patterns]
+
+        for path_pattern in path_patterns:
+            yield super().match(path_pattern, case_sensitive=case_sensitive)
+
+    def match_all(self, path_patterns, case_sensitive=None):
+        """
+        Perform :meth:`pathlib.Path.match` on several `path_patterns`. All patterns
+        must match.
+
+        Parameters
+        ----------
+        path_patterns : :obj:`str` or :obj:`Iterable`[:obj:`str`]
+            One or more path patterns to match against. (Default: None).
+        case_sensitive : :obj:`bool`
+            Whether to perform case-sensitive matching. If None, the default, then the
+            behavior is determined by the operating system. (Default: None).
+
+        Returns
+        -------
+        :obj:`bool`
+        """
+
+        for match in self.match(path_patterns, case_sensitive=case_sensitive):
+            if not match:
+                return False
+
+        return True
+
+    def match_any(self, path_patterns, case_sensitive=None):
+        """
+        Perform :meth:`pathlib.Path.match` on several `path_patterns`. Any pattern
+        must match.
+
+        Parameters
+        ----------
+        path_patterns : :obj:`str` or :obj:`Iterable`[:obj:`str`]
+            One or more path patterns to match against. (Default: None).
+        case_sensitive : :obj:`bool`
+            Whether to perform case-sensitive matching. If None, the default, then the
+            behavior is determined by the operating system. (Default: None).
+
+        Returns
+        -------
+        :obj:`bool`
+        """
+
+        for match in self.match(path_patterns):
+            if match:
+                return True
+
+        return False
+
+
+class FPath:
+    """
+    :obj:`FPath` is an f-string version of :obj:`Path`. This does not behave like a
+    typical Path, because typically there are several matches to the f-string Path.
+    Therefore, the :meth:`.FPath.expand` method must be used to create an
+    :obj:`ExpandedFPath` that lists all the possibilities.
+
+    Parameters
+    ----------
+    fpath : :obj:`str`
+        An f-string path, where the variables are captured and stored along the path
+        name.
+
+    Returns
+    -------
+    :obj:`.FPath`
+    """
+
+    def __init__(self, fpath):
+        self.fpath = fpath
+
+    def __repr__(self):
+        return "FPath({!r})".format(self.fpath)
+
+    def expand(self, exclude_path_patterns=None, require_metadata=True, errors="raise"):
+        """
+        Use an f-string to extract out a collection of paths, where the f-string
+        variables are captured and stored along the path name.
+
+        Parameters
+        ----------
+        exclude_path_patterns : :obj:`str` or :obj:`Iterable`[:obj:`str`]
+            Exclude paths that match the supplied pattern. (Default: None).
+        require_metadata : :obj:`bool`
+            Require that all paths identified must have found metadata. (Default: True).
+        errors : :obj:`str`
+            How to handle errors. If "raise", then raise an error. If "warn", then warn
+            and return an empty collection. If "ignore", then ignore the error and
+            return an empty collection. (Default: "raise").
+
+        Returns
+        -------
+        :obj:`.ExpandedFPath`
+        """
+
+        if errors not in {"raise", "warn", "ignore"}:
+            msg = f"invalid value for 'errors': {errors}"
+            raise ValueError(msg)
+
+        parser = parse.compile(self.fpath)
+
+        paths = []
+        for fname in glob(re.sub(r"\{.*?\}", "*", self.fpath)):
+            path = Path(fname)
+            if exclude_path_patterns and path.match_any(exclude_path_patterns):
+                continue
+            path.metadata = getattr(parser.parse(fname), "named", None)
+            if require_metadata and path.metadata is None:
+                msg = f"metadata not found for '{fname}' with '{self.fpath}'"
+                raise AttributeError(msg)
+            paths.append(path)
+
+        if len(paths) == 0 and errors != "ignore":
+            msg = f"no paths found for {self.fpath.__repr__()}"
+            if errors == "raise":
+                raise IOError(msg)
+            elif errors == "warn":
+                import warnings
+
+                warnings.warn(msg)
+
+        return ExpandedFPath(paths=paths, fpath=self)
+
+
+# TODO does scan_csv belong here?
+class ExpandedFPath(Sequence):
+    """
+    :obj:`ExpandedFPath` is the result of expanding an :obj:`FPath`. It is a
+    collection of :obj:`Path` objects that match the f-string pattern, and their
+    associated metadata.
+
+    Parameters
+    ----------
+    paths : :obj:`Iterable`[:obj:`Path`]
+        A collection of :obj:`Path` objects that match the f-string pattern, and their
+        associated metadata.
+    fpath : :obj:`FPath`
+        The original :obj:`FPath` that was expanded to create this
+        :obj:`ExpandedFPath`.
+    """
+
+    def __init__(self, paths, fpath):
+        if len(paths) != len(set(paths)):
+            raise AttributeError("paths are not unique")
+        self.paths = paths
+        self.fpath = fpath
+
+    def __getitem__(self, item):
+        return self.paths[item]
+
+    def __len__(self):
+        return len(self.paths)
+
+    def __repr__(self):
+        n = len(self)
+
+        txt = f"{self.fpath.__repr__()}\n\n"
+        txt += f"{n} matches found:\n\n"
+
+        for path in self.paths[:10]:
+            txt += f"{repr(path)}\n"
+        if n > 10:
+            txt += "...\n"
+
+        return txt
+
+    @property
+    def metadata(self):
+        """
+        Return the metadata for each path in the collection.
+
+        Returns
+        -------
+        :obj:`dict`[:obj:`str`, :obj:`dict`]
+        """
+
+        metadata = {path: path.metadata for path in self.paths}
+        return metadata
+
+    # TODO fix value types?
+    def to_polars(self, lazy=False):
+        """
+        Convert the metadata for each path in the collection to a polars DataFrame.
+
+        Parameters
+        ----------
+        lazy : :obj:`bool`
+            Return a lazy polars DataFrame? (Default: False).
+
+        Returns
+        -------
+        :obj:`polars.DataFrame` or :obj:`polars.LazyFrame`
+        """
+
+        pl = import_optional_dependency("polars")
+
+        data = [{"fname": str(key), **value} for key, value in self.metadata.items()]
+        df = pl.DataFrame(data)
+        if lazy:
+            df = df.lazy()
+        return df
+
+
+def expand_fpath(fpath, *, exclude_path_patterns=None, require_metadata=True):
+    """
+    Use an f-string to extract out a collection of paths, where the f-string variables
+    are captured and stored along the path name. This is a convenience function that
+    simply creates an :obj:`FPath` and calls its :meth:`.expand` method.
+
+    Parameters
+    ----------
+    fpath : :obj:`str`
+        An f-string path, where the variables are captured and stored along the path
+        name.
+    exclude_path_patterns : :obj:`str` or :obj:`Iterable`[:obj:`str`]
+        Exclude paths that match the supplied pattern. (Default: None).
+    require_metadata : :obj:`bool`
+        Require that all paths identified must have found metadata. (Default: True).
+
+    Returns
+    -------
+    :obj:`.ExpandedFPath`
+    """
+
+    return FPath(fpath).expand(
+        exclude_path_patterns=exclude_path_patterns,
+        require_metadata=require_metadata,
+    )
+
+
+def expand_fpath_decorator(f=None, post_process=None):
+    """
+    Decorator for :func:`.expand_fpath`.
+
+    Parameters
+    ----------
+    f : :obj:`callable`
+        A function that takes an :ref:`.ExpandedFPath` as its first argument.
+    post_process : :obj:`callable`
+        A function that takes the output of `f` and the :ref:`.ExpandedFPath`. 
+        (Default: None).
+    """
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(fpath, *args, **kwargs):
+            exclude_path_patterns = kwargs.pop("exclude_path_patterns", None)
+            require_metadata = kwargs.pop("require_metadata", True)
+            expanded_fpath = expand_fpath(
+                fpath,
+                exclude_path_patterns=exclude_path_patterns,
+                require_metadata=require_metadata,
+            )
+            result = f(expanded_fpath, *args, **kwargs)
+            if post_process is not None:
+                result = post_process(result, expanded_fpath)
+            return result
+
+        return wrapper
+
+    if f is None:
+        return decorator
+    else:
+        return decorator(f)

fpathlib/utils.py

@@ -0,0 +1,22 @@
+from importlib import import_module
+
+
+def import_optional_dependency(package):
+    """
+    Try to import `package`. If it is not installed, raise an ImportError.
+
+    Parameters
+    ----------
+    package : :obj:`str`
+            The name of the package to import.
+
+    Returns
+    -------
+    :obj:`module`
+    """
+
+    try:
+        return import_module(package)
+    except ModuleNotFoundError:
+        msg = f"optional dependency '{package}' is not installed; please install it and try again."
+        raise ModuleNotFoundError(msg) from None

fpathlib-0.1.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: fpathlib
+Version: 0.1.0
+Summary: A package to combine paths with metadata
+Author-email: "C. Lockhart" <clockha2@gmu.edu>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: parse
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Dynamic: license-file
+
+fpathlib
+========
+
+A Python package for adding metadata to file paths.

fpathlib-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+fpathlib/__init__.py,sha256=BQhOA7UY0wS0OfGlw5T9bbNaYZlcb7nKiA0q5F89ofo,227
+fpathlib/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+fpathlib/path.py,sha256=J9T0exhefoIUywynkOZGLnpArOERVVwA7KfaYinRxD4,9505
+fpathlib/utils.py,sha256=os9ggFllqOZXYcjfKcxPIy92LuRfvt6jWL0gNfet1N0,545
+fpathlib/__pycache__/__init__.cpython-313.pyc,sha256=YqTERPaAJJgHJ5kCpVw6c92d1Me7gfudZZ8rUAxKo50,321
+fpathlib/__pycache__/path.cpython-313.pyc,sha256=qlcwnudDL4jkFkCOVHdV14W-NTByOnHWdjvV5iIjc4I,11533
+fpathlib/__pycache__/utils.cpython-313.pyc,sha256=V4KSHMjm3ePQfaOKWwAkmaocvYb4VOul6Zooh0EvLa0,772
+fpathlib/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fpathlib/ext/polars.py,sha256=_TBjWt61e8miV5W_5UXcjdm67PvPnndWnFKa9K8dfTM,3633
+fpathlib/ext/__pycache__/__init__.cpython-313.pyc,sha256=lrgZbujuH_tlWGfe_Huo46srJdYJd1NQ6ZQFWamc6tc,153
+fpathlib/ext/__pycache__/polars.cpython-313.pyc,sha256=_Xz06TsHan10-xO87r7-AeT2S7OEKB-GTjIFnuXIuJA,4626
+fpathlib-0.1.0.dist-info/licenses/LICENSE,sha256=76rZ9i4ZumZ1M4jlYM9ZDOTYEeyzuxdsTKjF2qha3Lc,1069
+fpathlib-0.1.0.dist-info/METADATA,sha256=7bPl-Pu-RKuUVRophpn8LdoVxzZ_0ARwISM0Q9PcnQY,482
+fpathlib-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fpathlib-0.1.0.dist-info/top_level.txt,sha256=QT5pDgO4--AJn7X4RB51xpNTt0pD5_U2mCjsydpQAQw,9
+fpathlib-0.1.0.dist-info/RECORD,,

fpathlib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fpathlib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lockhart Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fpathlib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fpathlib