fpathlib 0.1.4.dev12__tar.gz → 0.1.5__tar.gz

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/.gitignore

@@ -5,3 +5,4 @@ docs/build
 dist
 build
 src/fpathlib/_version.py
+*.swp

{fpathlib-0.1.4.dev12/src/fpathlib.egg-info → fpathlib-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpathlib
-Version: 0.1.4.dev12
+Version: 0.1.5
 Summary: A package to combine paths with metadata
 Author-email: "C. Lockhart" <clockha2@gmu.edu>
 Requires-Python: >=3.12

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/conda-recipe/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "fpathlib" %}
-{% set version = "0.1.3" %}
+{% set version = "0.1.4" %}
 
 package:
   name: {{ name|lower }}
@@ -7,7 +7,7 @@ package:
 
 source:
   url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/fpathlib-{{ version }}.tar.gz
-  sha256: 059dbf937c6e965ef33f15aa214b2f354550d5dfa26b9030357954cce8c51874
+  sha256: 8ff44332a465c2adb5c45f94d6ee79c958fb50c39e896b16734d0d8208026c77
 
 build:
   noarch: python

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/scripts/pypi.sh

@@ -21,7 +21,14 @@ python3 -m build
 # 0.1.3/0.1.2 tag-collision incident slipped past a git-describe check even
 # though the build itself came out as a .devN), inspect what actually got
 # built. This is the real signal of whether the release is clean.
-dev_artifacts=$(ls dist/ | grep -c '\.dev[0-9]')
+#
+# `grep -c` exits 1 (not just prints "0") when it finds zero matches --
+# with `set -e` active (deploy.sh sets it, and this script is sourced into
+# that same shell), that silently killed the whole deploy right here for
+# every *clean* release build (the exact case with 0 .dev files), before
+# ever reaching twine upload. `|| true` keeps the count without letting
+# grep's "no matches" exit status abort the script.
+dev_artifacts=$(ls dist/ | grep -c '\.dev[0-9]' || true)
 if [ $allow_dev -eq 0 ] && [ "$dev_artifacts" != "0" ]
 then
   echo "built version is a dev version (tag doesn't point at a clean, distinct commit -- check 'git describe --tags --long' and 'git status'), not uploading to pypi"

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/src/fpathlib/__init__.py

@@ -2,6 +2,7 @@ from fpathlib.path import Path
 from fpathlib.fpath import FPath, ExpandedFPath
 from fpathlib.expand import (
     expand_fpath,
+    iexpand_fpath,
     expand_fpath_decorator,
     is_expandable,
 )
@@ -11,6 +12,7 @@ __all__ = [
     "FPath",
     "ExpandedFPath",
     "expand_fpath",
+    "iexpand_fpath",
     "expand_fpath_decorator",
     "is_expandable",
 ]

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/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.4.dev12'
-__version_tuple__ = version_tuple = (0, 1, 4, 'dev12')
+__version__ = version = '0.1.5'
+__version_tuple__ = version_tuple = (0, 1, 5)
 
-__commit_id__ = commit_id = 'g2ae3f3b01'
+__commit_id__ = commit_id = 'gae98b27f0'

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/src/fpathlib/expand.py

@@ -31,7 +31,39 @@ def expand_fpath(fpath, *, exclude_path_patterns=None, require_metadata=True):
     )
 
 
-def expand_fpath_decorator(f=None, require_expandable=True, post_process=None):
+def iexpand_fpath(fpath, *, exclude_path_patterns=None, require_metadata=True, errors="raise"):
+    """
+    Generator equivalent of :func:`.expand_fpath` -- lazily yields each
+    matching :obj:`.Path` instead of building the whole
+    :obj:`.ExpandedFPath` up front. This is a convenience function that
+    simply creates an :obj:`FPath` and calls its :meth:`.FPath.iexpand`
+    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).
+    errors : :obj:`str`
+        How to handle the "no matches" case. See :meth:`.FPath.iexpand`. (Default: "raise").
+
+    Yields
+    ------
+    :obj:`.Path`
+    """
+
+    return FPath(fpath).iexpand(
+        exclude_path_patterns=exclude_path_patterns,
+        require_metadata=require_metadata,
+        errors=errors,
+    )
+
+
+def expand_fpath_decorator(f=None, require_expandable=False, post_process=None):
     """
     Decorator for :func:`.expand_fpath`.
 
@@ -39,6 +71,11 @@ def expand_fpath_decorator(f=None, require_expandable=True, post_process=None):
     ----------
     f : :obj:`callable`
         A function that takes an :obj:`.ExpandedFPath` as its first argument.
+    require_expandable : :obj:`bool`
+        Whether to require `fpath` to have {} named captures. If False
+        (the default), a plain literal path or glob is passed straight
+        through to `f` unexpanded, with `post_process` skipped -- there's
+        no ExpandedFPath to hand it in that case. (Default: False)
     post_process : :obj:`callable`
         A function that takes the output of `f` and the :obj:`.ExpandedFPath`.
         (Default: None).
@@ -52,18 +89,8 @@ def expand_fpath_decorator(f=None, require_expandable=True, post_process=None):
                 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
+            # Expand fpath if it is expandable.
+            elif is_expandable(fpath):
                 exclude_path_patterns = kwargs.pop("exclude_path_patterns", None)
                 require_metadata = kwargs.pop("require_metadata", True)
                 expanded_fpath = expand_fpath(
@@ -73,7 +100,17 @@ def expand_fpath_decorator(f=None, require_expandable=True, post_process=None):
                 )
                 result = f(expanded_fpath, *args, **kwargs)
 
-            # If post_process is provided, call it with the result and the expanded_fpath.
+            # fpath has no {} captures, so there's no ExpandedFPath to
+            # build -- nothing for post_process (e.g. join_metadata) to
+            # join metadata from. Call f directly and return immediately,
+            # skipping post_process entirely, rather than falling through
+            # to it with no expanded_fpath to give it.
+            else:
+                if require_expandable:
+                    msg = f"fpath not expandable: '{fpath}'"
+                    raise ValueError(msg)
+                return f(fpath, *args, **kwargs)
+
             if post_process is not None:
                 result = post_process(result, expanded_fpath)
 

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/src/fpathlib/ext/polars.py

@@ -160,7 +160,7 @@ def scan_parquet(expanded_fpath, *args, **kwargs):
 
 
 # TODO rename expanded_fpath as source
-@expand_fpath_decorator(require_expandable=False, post_process=join_metadata)
+@expand_fpath_decorator(post_process=join_metadata)
 def scan_txt(
     expanded_fpath,
     filter_expr=None,

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5}/src/fpathlib/fpath.py

@@ -1,5 +1,5 @@
 from collections.abc import Sequence
-from glob import glob
+from glob import glob, iglob
 import parse
 import re
 
@@ -31,10 +31,19 @@ class FPath:
     def __repr__(self):
         return "FPath({!r})".format(self.fpath)
 
-    def expand(self, exclude_path_patterns=None, require_metadata=True, errors="raise"):
+    def iexpand(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.
+        Lazily yield each :obj:`.Path` matching the f-string pattern, one at
+        a time, instead of building the whole :obj:`.ExpandedFPath` up
+        front. Useful when a pattern could match a very large number of
+        files and you don't want them all held in memory at once, or want
+        to start processing before the full glob finishes walking the
+        filesystem. :meth:`.expand` is built on top of this generator.
+
+        Like any generator function, nothing in the body runs -- including
+        argument validation and the wildcard/{} capture check -- until the
+        result is first iterated (a `for` loop, `list(...)`, etc.), not at
+        the moment :meth:`.iexpand` is called.
 
         Parameters
         ----------
@@ -43,13 +52,13 @@ class FPath:
         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").
+            How to handle the "no matches" case, checked once the pattern is
+            fully exhausted. If "raise", then raise an error. If "warn",
+            then warn. If "ignore", then do nothing. (Default: "raise").
 
-        Returns
-        -------
-        :obj:`.ExpandedFPath`
+        Yields
+        ------
+        :obj:`.Path`
         """
 
         if errors not in {"raise", "warn", "ignore"}:
@@ -84,8 +93,8 @@ class FPath:
                     )
                     raise ValueError(msg)
 
-        paths = []
-        for fname in glob(re.sub(r"\{.*?\}", "*", self.fpath)):
+        n = 0
+        for fname in iglob(re.sub(r"\{.*?\}", "*", self.fpath)):
             path = Path(fname)
             if exclude_path_patterns and path.match_any(exclude_path_patterns):
                 continue
@@ -93,9 +102,10 @@ class FPath:
             if require_metadata and path.metadata is None:
                 msg = f"metadata not found for '{fname}' with '{self.fpath}'"
                 raise AttributeError(msg)
-            paths.append(path)
+            n += 1
+            yield path
 
-        if len(paths) == 0 and errors != "ignore":
+        if n == 0 and errors != "ignore":
             msg = f"no paths found for {self.fpath.__repr__()}"
             if errors == "raise":
                 raise IOError(msg)
@@ -104,6 +114,35 @@ class FPath:
 
                 warnings.warn(msg)
 
+    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`
+        """
+
+        paths = list(
+            self.iexpand(
+                exclude_path_patterns=exclude_path_patterns,
+                require_metadata=require_metadata,
+                errors=errors,
+            )
+        )
+
         return ExpandedFPath(paths=paths, fpath=self)
 
 

{fpathlib-0.1.4.dev12 → fpathlib-0.1.5/src/fpathlib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpathlib
-Version: 0.1.4.dev12
+Version: 0.1.5
 Summary: A package to combine paths with metadata
 Author-email: "C. Lockhart" <clockha2@gmu.edu>
 Requires-Python: >=3.12

fpathlib-0.1.5/src/fpathlib.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.5",
+  "distance": 0,
+  "node": "gae98b27f09095479f5ae8272b52f73655b3c8a4b",
+  "dirty": false,
+  "branch": "main",
+  "node_date": "2026-09-17"
+}

fpathlib-0.1.4.dev12/src/fpathlib.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.3",
-  "distance": 12,
-  "node": "g2ae3f3b01d310e4bf9308863ebc666476069caf8",
-  "dirty": false,
-  "branch": "main",
-  "node_date": "2026-09-16"
-}