fpathlib 0.1.2.post0__tar.gz → 0.1.3__tar.gz

fpathlib-0.1.3/.gitignore

@@ -0,0 +1,7 @@
+__pycache__
+src/fpathlib.egg-info
+docs/build
+.pytest_cache
+dist
+build
+src/fpathlib/_version.py

fpathlib-0.1.3/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

fpathlib-0.1.3/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: fpathlib
+Version: 0.1.3
+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/README.md

@@ -0,0 +1,61 @@
+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/TODO.txt

@@ -0,0 +1,7 @@
+
+1. Tests are a mix between automated (in loading different test cases) and hardcoded (in asserting the expected output). If we move to other testcases, this will not work.
+2. Should multiple fpaths be supported, for instance, pl.scan_txt(["{a}/fname", "{a}/{b}/fname"]) ?
+
+
+
+

fpathlib-0.1.3/docs/source/api.rst

@@ -0,0 +1,36 @@
+API Reference
+=============
+
+Path
+----
+
+.. autoclass:: fpathlib.Path
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+FPath and ExpandedFPath
+-----------------------
+
+.. autoclass:: fpathlib.FPath
+   :members:
+   :undoc-members:
+
+.. autoclass:: fpathlib.ExpandedFPath
+   :members:
+   :undoc-members:
+
+Expanding paths
+----------------
+
+.. autofunction:: fpathlib.expand_fpath
+
+.. autofunction:: fpathlib.expand_fpath_decorator
+
+.. autofunction:: fpathlib.is_expandable
+
+Polars extension
+-----------------
+
+.. automodule:: fpathlib.ext.polars
+   :members: read_csv, read_txt, scan_csv, scan_parquet, scan_txt

{fpathlib-0.1.2.post0 → fpathlib-0.1.3}/docs/source/conf.py

@@ -20,8 +20,12 @@ release = '0.1.0'
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
 ]
 
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+
 templates_path = ['_templates']
 exclude_patterns = []
 

fpathlib-0.1.3/docs/source/index.rst

@@ -0,0 +1,66 @@
+fpathlib
+========
+
+fpathlib combines file paths with the metadata encoded in their names.
+
+The core idea is an f-string-like path pattern -- an :class:`~fpathlib.FPath`
+-- whose ``{variable}`` fields are captured out of every matching path on
+disk, producing an :class:`~fpathlib.ExpandedFPath`: a collection of
+:class:`~fpathlib.Path` objects, each carrying the metadata parsed from its
+own filename.
+
+.. code-block:: 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 with
+:meth:`~fpathlib.ExpandedFPath.to_polars`:
+
+.. code-block:: python
+
+    df = expanded.to_polars()
+
+:mod:`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.
+
+.. code-block:: 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
+------------
+
+.. code-block:: shell
+
+    pip install fpathlib
+
+The ``fpathlib.ext.polars`` extension additionally requires ``polars``,
+which is not installed by :mod:`fpathlib` itself:
+
+.. code-block:: shell
+
+    pip install polars
+
+API Reference
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   api

{fpathlib-0.1.2.post0 → fpathlib-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]
 write_to = "src/fpathlib/_version.py"
-version_scheme = "post-release"
+version_scheme = "guess-next-dev"
 local_scheme = "no-local-version"
 
 [project]
@@ -13,13 +13,14 @@ dynamic = ["version"]
 description = "A package to combine paths with metadata"
 authors = [{ name="C. Lockhart", email="clockha2@gmu.edu" }]
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.12"
 dependencies = [
     "parse",
 ]
 
 [project.optional-dependencies]
-dev = ["pytest", "black", "sphinx"]
+dev = ["pytest", "black", "sphinx", "furo", "polars"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
+exclude = ["*__pycache__*"]

fpathlib-0.1.3/scripts/deploy.sh

@@ -0,0 +1,3 @@
+source scripts/docs.sh
+source scripts/tag.sh "patch"
+source scripts/pypi.sh

fpathlib-0.1.3/scripts/docs.sh

@@ -0,0 +1,3 @@
+cd docs 
+make html
+cd ..

fpathlib-0.1.3/scripts/pypi.sh

@@ -0,0 +1,20 @@
+allow_dev=0
+if [ "$1" = "dev" ]
+then
+  allow_dev=1
+fi
+
+python3 -m build
+
+dev_artifacts=$(ls dist/ | grep -c '\.dev[0-9]')
+if [ $allow_dev -eq 0 ] && [ "$dev_artifacts" != "0" ]
+then
+  echo "built version is a dev version (tag likely doesn't point at a distinct commit), not uploading to pypi"
+  rm -r dist
+  rm -r src/fpathlib.egg-info
+  return
+fi
+
+twine upload --verbose dist/*
+rm -r dist
+rm -r src/fpathlib.egg-info

fpathlib-0.1.3/scripts/tag.sh

@@ -0,0 +1,33 @@
+set -e
+
+m=$1
+
+tag=$(git describe --tags --abbrev=0)
+parts=(${tag//./ })
+if [ "$m" == "major" ]
+then
+  parts[0]=$((parts[0]+1))
+  parts[1]=0
+  parts[2]=0
+elif [ "$m" == "minor" ]
+then
+  parts[1]=$((parts[1]+1))
+  parts[2]=0
+elif [ "$m" == "patch" ]
+then
+  parts[2]=$((parts[2]+1))
+else
+  echo "must specify major, minor, or patch"
+  return
+fi
+tag="${parts[0]}.${parts[1]}.${parts[2]}"
+
+git add -A
+git commit --allow-empty -m "tag $tag"
+git push origin main
+
+git checkout main
+git pull origin main
+
+git tag $tag
+git push origin $tag

fpathlib-0.1.3/src/fpathlib/__init__.py

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

{fpathlib-0.1.2.post0 → fpathlib-0.1.3}/src/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.post0'
-__version_tuple__ = version_tuple = (0, 1, 2, 'post0')
+__version__ = version = '0.1.3'
+__version_tuple__ = version_tuple = (0, 1, 3)
 
-__commit_id__ = commit_id = 'g780142e93'
+__commit_id__ = commit_id = 'g02b650d92'

fpathlib-0.1.3/src/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