fpathlib 0.1.2.dev0__py3-none-any.whl → 0.1.3.dev0__py3-none-any.whl

fpathlib/__init__.py

@@ -1,14 +1,11 @@
-from fpathlib.path import (
-    Path,
-    FPath,
-    ExpandedFPath,
+from fpathlib.path import Path
+from fpathlib.fpath import FPath, ExpandedFPath
+from fpathlib.expand import (
     expand_fpath,
     expand_fpath_decorator,
     is_expandable,
 )
 
-from fpathlib.ext import polars
-
 __all__ = [
     "Path",
     "FPath",
@@ -16,5 +13,4 @@ __all__ = [
     "expand_fpath",
     "expand_fpath_decorator",
     "is_expandable",
-    "polars",
 ]

fpathlib/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.2.dev0'
-__version_tuple__ = version_tuple = (0, 1, 2, 'dev0')
+__version__ = version = '0.1.3.dev0'
+__version_tuple__ = version_tuple = (0, 1, 3, 'dev0')
 
 __commit_id__ = commit_id = None

fpathlib/expand.py

@@ -0,0 +1,106 @@
+from functools import wraps
+import parse
+
+from .fpath import ExpandedFPath, FPath
+
+
+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, require_expandable=True, post_process=None):
+    """
+    Decorator for :func:`.expand_fpath`.
+
+    Parameters
+    ----------
+    f : :obj:`callable`
+        A function that takes an :obj:`.ExpandedFPath` as its first argument.
+    post_process : :obj:`callable`
+        A function that takes the output of `f` and the :obj:`.ExpandedFPath`.
+        (Default: None).
+    """
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(fpath, *args, **kwargs):
+            # If fpath is an :obj:`ExpandedFPath`, just call f with it.
+            if isinstance(fpath, ExpandedFPath):
+                expanded_fpath = fpath
+                result = f(fpath, *args, **kwargs)
+
+            # Otherwise, expand fpath and call f with the result.
+            else:
+                # What happens if fpath is not expandable?
+                # If require_expandable is True, raise an error.
+                # Otherwise, just call f with the original fpath.
+                if not is_expandable(fpath):
+                    if require_expandable:
+                        msg = f"fpath not expandable: '{fpath}'"
+                        raise ValueError(msg)
+                    return f(fpath, *args, **kwargs)
+
+                # We know fpath is expandable, so we can expand it and call f
+                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 provided, call it with the result and the expanded_fpath.
+            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)
+
+def is_expandable(fpath):
+    """
+    Check if expandable.
+
+    Parameters
+    ----------
+    fpath : :obj:`str`
+
+    Returns
+    -------
+    :obj:`bool`
+    """
+
+    try:
+        parser = parse.compile(str(fpath))
+        return bool(parser.named_fields)
+    except TypeError:
+        return False

fpathlib/ext/polars.py

@@ -1,12 +1,21 @@
 from functools import wraps
-from polars import *
-import polars as pl
+import polars as _polars
 from fpathlib import expand_fpath_decorator, ExpandedFPath
 
 
+def __getattr__(name):
+    # Delegates any attribute this module doesn't define itself to the real
+    # polars module, so `fpathlib.ext.polars` remains a drop-in replacement for
+    # `import polars` (pl.DataFrame, pl.col, pl.List, etc. all still resolve).
+    # Unlike `from polars import *`, this only kicks in for names Python didn't
+    # already find defined here, so it can't silently shadow builtins like
+    # `list` or `len` for this module's own implementation code.
+    return getattr(_polars, name)
+
+
 def join_metadata(df, expanded_fpath):
     return df.join(
-        expanded_fpath.to_polars(lazy=isinstance(df, pl.LazyFrame)),
+        expanded_fpath.to_polars(lazy=isinstance(df, _polars.LazyFrame)),
         on="fname",
     )
 
@@ -109,7 +118,7 @@ def scan_csv(expanded_fpath, *args, **kwargs):
     :obj:`polars.LazyFrame`
     """
 
-    lf = pl.scan_csv(
+    lf = _polars.scan_csv(
         expanded_fpath,
         include_file_paths="fname",
         *args,
@@ -140,7 +149,7 @@ def scan_parquet(expanded_fpath, *args, **kwargs):
     :obj:`polars.LazyFrame`
     """
 
-    lf = pl.scan_parquet(
+    lf = _polars.scan_parquet(
         expanded_fpath,
         include_file_paths="fname",
         *args,
@@ -151,8 +160,6 @@ def scan_parquet(expanded_fpath, *args, **kwargs):
 
 
 # TODO rename expanded_fpath as source
-# TODO this gets very slow when expanded_fpath contains thousands of files
-# I turned on streaming to fix this, but streaming is also slow. expanded_fpath[0] is the answer
 @expand_fpath_decorator(require_expandable=False, post_process=join_metadata)
 def scan_txt(
     expanded_fpath,
@@ -206,7 +213,7 @@ def scan_txt(
 
     # TODO schema and schema_overrides is probably broken
 
-    lf = pl.scan_csv(
+    lf = _polars.scan_csv(
         expanded_fpath,
         include_file_paths="fname",
         separator="\n",
@@ -224,12 +231,36 @@ def scan_txt(
     if separator is not None:
         # Separate line into fields by separator
         lf = lf.with_columns(
-            pl.col("line").str.split(separator, literal=False).alias("fields")
+            _polars.col("line").str.split(separator, literal=False).alias("fields")
         )
 
         if not keep_line:
             lf = lf.drop("line")
 
+        # With many matched files, inferring the field count/dtypes directly
+        # against the full glob is extremely slow (every file has to be opened
+        # before a `.head()` takes effect). Instead, recurse on a single
+        # representative file -- expanded_fpath[0] -- and reuse its already-cheap
+        # (single-file) inference below instead of duplicating it here. Computed
+        # once here since it's needed by both the field-count branch below and
+        # the dtype-inference branch further down.
+        infer_schema = kwargs.get("infer_schema", True)
+        sample_schema = None
+        if (
+            isinstance(expanded_fpath, ExpandedFPath)
+            and len(expanded_fpath) > 1
+            and (usecols is None or infer_schema)
+        ):
+            sample_schema = scan_txt(
+                expanded_fpath[0],
+                filter_expr=filter_expr,
+                separator=separator,
+                new_columns=new_columns,
+                has_header=has_header,
+                usecols=usecols,
+                **kwargs,
+            ).collect_schema()
+
         # Set the columns to use for the fields.
         # Either specify a subset of columns to use, or use all columns
         if usecols is not None:
@@ -238,21 +269,23 @@ def scan_txt(
                 fields[col] = f"field_{col}"
 
         else:
-            # Count the number of fields
-            n_fields = (
-                lf.head(1)
-                .select(pl.col("fields").list.len().unique())
-                .collect(engine="streaming")
-                .item()
-            )
+            if sample_schema is not None:
+                n_fields = len(sample_schema) - 1  # minus 'fname'
+            else:
+                n_fields = (
+                    lf.head(1)
+                    .select(_polars.col("fields").list.len().unique())
+                    .collect()
+                    .item()
+                )
 
             # Initial field names, may be renamed later from header or by `new_columns`
             fields = {i: f"field_{i}" for i in range(n_fields)}
 
         # Add each field as a separate column
-        lf = lf.with_columns(
-            [pl.col("fields").list.get(i).alias(field) for i, field in fields.items()]
-        ).drop("fields")
+        for i, field in fields.items():
+            lf = lf.with_columns(_polars.col("fields").list.get(i).alias(field))
+        lf = lf.drop("fields")
 
         # LazyFrame does not guarantee order, so the header might not be the first row
         # This can be fixed by scan_csv with include_row_index. But this seems clunky
@@ -261,29 +294,32 @@ def scan_txt(
             first_row = lf.head(1).collect()
             header.to_pandas().transpose()[0].to_dict()
             lf = lf.slice(offset=1, length=None)
-            header = first_row.select(pl.col(fields)).to_dict(as_series=False)
+            header = first_row.select(_polars.col(fields)).to_dict(as_series=False)
             lf = lf.rename({field: header[field][0] for field in fields})
             """
             raise NotImplementedError
 
         # Apply new column names if provided
         if new_columns is not None:
-            lf = lf.rename(
-                {
-                    field: new_column
-                    for field, new_column in zip(fields.keys(), new_columns)
-                }
-            )
+            for field, new_column in zip(fields.values(), new_columns):
+                lf = lf.rename({field: new_column})
 
         # Infer dtypes?
-        if kwargs.get("infer_schema", True):
-            sample = (
-                lf.head(kwargs.get("infer_schema_length", 100))
-                .collect(engine="streaming")
-                .write_csv()
-                .encode()
-            )
-            inferred_schema = pl.read_csv(sample).schema
+        if infer_schema:
+            if sample_schema is not None:
+                inferred_schema = {
+                    name: dtype
+                    for name, dtype in sample_schema.items()
+                    if name != "fname"
+                }
+            else:
+                sample = (
+                    lf.head(kwargs.get("infer_schema_length", 100))
+                    .collect()
+                    .write_csv()
+                    .encode()
+                )
+                inferred_schema = _polars.read_csv(sample).schema
             lf = lf.cast(inferred_schema)
 
     return lf

fpathlib/fpath.py

@@ -0,0 +1,160 @@
+from collections.abc import Sequence
+from glob import glob
+import parse
+import re
+
+from .path import Path
+from .utils import import_optional_dependency
+
+
+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 = str(fpath)  # must be string, not Path or something else
+
+    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

fpathlib/path.py

@@ -1,11 +1,4 @@
-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):
@@ -91,248 +84,3 @@ class Path(pathlib.Path):
                 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 = str(fpath)  # must be string, not Path or something else
-
-    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, require_expandable=True, 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):
-            # What happens if fpath is not expandable? 
-            # If require_expandable is True, raise an error. 
-            # Otherwise, just call f with the original fpath.
-            if not is_expandable(fpath):
-                if require_expandable:
-                    msg = f"fpath '{fpath}' is not expandable"
-                    raise ValueError(msg)
-                return f(fpath, *args, **kwargs)  
-
-            # We know fpath is expandable, so we can expand it and call f 
-            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)
-
-def is_expandable(fpath):
-    """
-    Check if expandable.
-
-    Parameters
-    ----------
-    fpath : :obj:`str`
-   
-    Returns
-    -------
-    :obj:`bool`
-    """
-
-    try: 
-        parser = parse.compile(fpath)
-        return bool(parser.named_fields)
-    except TypeError:
-        return False

fpathlib-0.1.3.dev0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: fpathlib
+Version: 0.1.3.dev0
+Summary: A package to combine paths with metadata
+Author-email: "C. Lockhart" <clockha2@gmu.edu>
+Requires-Python: >=3.12
+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"
+Requires-Dist: furo; extra == "dev"
+Requires-Dist: polars; extra == "dev"
+Dynamic: license-file
+
+fpathlib
+========
+
+A Python package for adding metadata to file paths.
+
+`fpathlib` combines file paths with the metadata encoded in their names. It
+does this with an f-string-like path pattern -- `FPath` -- whose
+`{variable}` fields are captured out of every matching path on disk.
+
+```python
+from fpathlib import expand_fpath
+
+# Given files like data/tr1/output/0/job2.log, data/tr2/output/1/job0.log, ...
+expanded = expand_fpath("data/tr{trajectory:d}/output/{replica:d}/job{job:d}.log")
+
+for path in expanded:
+    print(path, path.metadata)
+# data/tr1/output/0/job2.log {'trajectory': 1, 'replica': 0, 'job': 2}
+# data/tr2/output/1/job0.log {'trajectory': 2, 'replica': 1, 'job': 0}
+```
+
+Combine the metadata for every matched path into a single table:
+
+```python
+df = expanded.to_polars()
+```
+
+`fpathlib.ext.polars` goes a step further: it wraps `polars`'s own
+`read_csv`/`scan_csv`/`read_txt`/`scan_txt` so that an expandable path
+pattern is accepted directly, and the resulting DataFrame or LazyFrame comes
+back with the metadata already joined in.
+
+```python
+import fpathlib.ext.polars as pl
+
+df = pl.read_csv(
+    "data/tr{trajectory:d}/output/{replica:d}/job{job:d}.log",
+    has_header=False,
+)
+# df has columns "column_1", ..., plus "trajectory", "replica", "job"
+```
+
+Installation
+------------
+
+```shell
+pip install fpathlib
+```
+
+The `fpathlib.ext.polars` extension additionally requires `polars`, which
+is not installed by `fpathlib` itself:
+
+```shell
+pip install polars
+```
+
+Documentation
+-------------
+
+Full API documentation is in `docs/`; build it locally with
+`scripts/docs.sh` (requires the `dev` extras: `pip install -e .[dev]`).

fpathlib-0.1.3.dev0.dist-info/RECORD

@@ -0,0 +1,18 @@
+fpathlib/__init__.py,sha256=VniZjNqT5pxzj6ymcpAlhNoWC44MwkQLu9jssc7o13Q,308
+fpathlib/_version.py,sha256=dxsNQZw4RtnKvRTjSi1emxt4lZsN7c7hbUngeAYGVZY,533
+fpathlib/expand.py,sha256=M_K1nfRAD9c983d68kCRuzo7-zNaOY_3R9gn8aBritI,3393
+fpathlib/fpath.py,sha256=okEgqpWQjearSyDTp6RdIWbFolijI3BrXR8F5t-9Was,4877
+fpathlib/path.py,sha256=ME2jfMBCK1Emu35mu8wN-KvmPE4p8qQqX8q-uO5cDsI,2629
+fpathlib/utils.py,sha256=os9ggFllqOZXYcjfKcxPIy92LuRfvt6jWL0gNfet1N0,545
+fpathlib/__pycache__/__init__.cpython-313.pyc,sha256=clLXRuVcvX9dJt4CTvaUBR6vhAzg67Ex7gKRwtumJFY,428
+fpathlib/__pycache__/path.cpython-313.pyc,sha256=mQVWw1qjmvUp3NflXzhC_Q654H4hFW29gLYHP9nxRPQ,12257
+fpathlib/__pycache__/utils.cpython-313.pyc,sha256=V4KSHMjm3ePQfaOKWwAkmaocvYb4VOul6Zooh0EvLa0,772
+fpathlib/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fpathlib/ext/polars.py,sha256=r3-MoGfbB11cOrECGCEyFzdKXGGEI9DSV6Xfc8vHeJo,10994
+fpathlib/ext/__pycache__/__init__.cpython-313.pyc,sha256=lrgZbujuH_tlWGfe_Huo46srJdYJd1NQ6ZQFWamc6tc,153
+fpathlib/ext/__pycache__/polars.cpython-313.pyc,sha256=S0epPPABmHRj0IrCxyOC8hD2_g0hBKggFFWfsmXw4m0,7740
+fpathlib-0.1.3.dev0.dist-info/licenses/LICENSE,sha256=76rZ9i4ZumZ1M4jlYM9ZDOTYEeyzuxdsTKjF2qha3Lc,1069
+fpathlib-0.1.3.dev0.dist-info/METADATA,sha256=EqyLMoPqqdMHwjd0To4_dc-o-wW2B2t6HmHel926ueM,2141
+fpathlib-0.1.3.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fpathlib-0.1.3.dev0.dist-info/top_level.txt,sha256=QT5pDgO4--AJn7X4RB51xpNTt0pD5_U2mCjsydpQAQw,9
+fpathlib-0.1.3.dev0.dist-info/RECORD,,

fpathlib-0.1.2.dev0.dist-info/METADATA

@@ -1,19 +0,0 @@
-Metadata-Version: 2.4
-Name: fpathlib
-Version: 0.1.2.dev0
-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.2.dev0.dist-info/RECORD

@@ -1,16 +0,0 @@
-fpathlib/__init__.py,sha256=EBSrXJL75V913iVAFnxN9-I2PptBoNvVJuz7a3ljPrA,314
-fpathlib/_version.py,sha256=fsBXt_uGfzjmQP8ggFtdc8lndHuCWCLefeg9u0NFdb8,533
-fpathlib/path.py,sha256=QognR9ULT7uxUBVJa2mXLAVSrdE5luX62DtMYStwuMY,10372
-fpathlib/utils.py,sha256=os9ggFllqOZXYcjfKcxPIy92LuRfvt6jWL0gNfet1N0,545
-fpathlib/__pycache__/__init__.cpython-313.pyc,sha256=clLXRuVcvX9dJt4CTvaUBR6vhAzg67Ex7gKRwtumJFY,428
-fpathlib/__pycache__/path.cpython-313.pyc,sha256=mQVWw1qjmvUp3NflXzhC_Q654H4hFW29gLYHP9nxRPQ,12257
-fpathlib/__pycache__/utils.cpython-313.pyc,sha256=V4KSHMjm3ePQfaOKWwAkmaocvYb4VOul6Zooh0EvLa0,772
-fpathlib/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fpathlib/ext/polars.py,sha256=viSPdThRZCDafN37YixntfwRzgqKfNB6TfqvlFFATK0,9262
-fpathlib/ext/__pycache__/__init__.cpython-313.pyc,sha256=lrgZbujuH_tlWGfe_Huo46srJdYJd1NQ6ZQFWamc6tc,153
-fpathlib/ext/__pycache__/polars.cpython-313.pyc,sha256=S0epPPABmHRj0IrCxyOC8hD2_g0hBKggFFWfsmXw4m0,7740
-fpathlib-0.1.2.dev0.dist-info/licenses/LICENSE,sha256=76rZ9i4ZumZ1M4jlYM9ZDOTYEeyzuxdsTKjF2qha3Lc,1069
-fpathlib-0.1.2.dev0.dist-info/METADATA,sha256=j8pkPrc9dnYU2tgvZiibJ1PFoM_I_U55vvFN6GPeKt4,487
-fpathlib-0.1.2.dev0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-fpathlib-0.1.2.dev0.dist-info/top_level.txt,sha256=QT5pDgO4--AJn7X4RB51xpNTt0pD5_U2mCjsydpQAQw,9
-fpathlib-0.1.2.dev0.dist-info/RECORD,,