fpathlib 0.1.4.dev12__tar.gz → 0.1.4.dev16__tar.gz

{fpathlib-0.1.4.dev12 → fpathlib-0.1.4.dev16}/.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.4.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpathlib
-Version: 0.1.4.dev12
+Version: 0.1.4.dev16
 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.4.dev16}/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.4.dev16}/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.4.dev16'
+__version_tuple__ = version_tuple = (0, 1, 4, 'dev16')
 
-__commit_id__ = commit_id = 'g2ae3f3b01'
+__commit_id__ = commit_id = 'g851c5dad8'

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

@@ -31,6 +31,38 @@ def expand_fpath(fpath, *, exclude_path_patterns=None, require_metadata=True):
     )
 
 
+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=True, post_process=None):
     """
     Decorator for :func:`.expand_fpath`.

{fpathlib-0.1.4.dev12 → fpathlib-0.1.4.dev16}/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.4.dev16/src/fpathlib.egg-info}/PKG-INFO

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

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

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.3",
+  "distance": 16,
+  "node": "g851c5dad81b573754c9c1d7508faca0f7b1ab986",
+  "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"
-}