fpathlib 0.1.4.dev12__py3-none-any.whl → 0.1.4.dev16__py3-none-any.whl

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/_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 = None

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/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.dist-info → fpathlib-0.1.4.dev16.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+fpathlib/__init__.py,sha256=6HdQu7fISBIc6osLZp7CMJ65DW2aGNsvFCLKbUXgE10,348
+fpathlib/_version.py,sha256=28sM26orIv-swz6NJDAQttdFakxmunN6hkOeiiQ6fYM,535
+fpathlib/expand.py,sha256=31dMQxizf7SdZzDSv7UOfLkfwqsbzl_5JP1QbEeDR_0,4587
+fpathlib/fpath.py,sha256=H7MnxyqE5N2wGu13ReBUjNg9WbSuV6PqEgtzV4uL3GU,8406
+fpathlib/path.py,sha256=ME2jfMBCK1Emu35mu8wN-KvmPE4p8qQqX8q-uO5cDsI,2629
+fpathlib/utils.py,sha256=os9ggFllqOZXYcjfKcxPIy92LuRfvt6jWL0gNfet1N0,545
+fpathlib/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fpathlib/ext/polars.py,sha256=lamkEI1CKW0g1n6jvj0aJug-ypyNqa_H3vdTb6YfmIo,12819
+fpathlib-0.1.4.dev16.dist-info/licenses/LICENSE,sha256=76rZ9i4ZumZ1M4jlYM9ZDOTYEeyzuxdsTKjF2qha3Lc,1069
+fpathlib-0.1.4.dev16.dist-info/METADATA,sha256=lEBsRE0z0zJqVyXkgx5kM4257JIJAh91UCc8UZNH-qc,2142
+fpathlib-0.1.4.dev16.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fpathlib-0.1.4.dev16.dist-info/top_level.txt,sha256=QT5pDgO4--AJn7X4RB51xpNTt0pD5_U2mCjsydpQAQw,9
+fpathlib-0.1.4.dev16.dist-info/RECORD,,

fpathlib-0.1.4.dev12.dist-info/RECORD

@@ -1,13 +0,0 @@
-fpathlib/__init__.py,sha256=VniZjNqT5pxzj6ymcpAlhNoWC44MwkQLu9jssc7o13Q,308
-fpathlib/_version.py,sha256=xCkV2LVlX6YKEXfWlZphUkmo_tboft1yQfti1gQE5Dw,535
-fpathlib/expand.py,sha256=jSkDZnGrEzSRGhKXp4G2uh6T0N-cJjt9oKGmOOjXalQ,3458
-fpathlib/fpath.py,sha256=VhCLZAqCCiOVWSB_eQu7MQj0efBJX--DIMqXO-2n3Mw,6742
-fpathlib/path.py,sha256=ME2jfMBCK1Emu35mu8wN-KvmPE4p8qQqX8q-uO5cDsI,2629
-fpathlib/utils.py,sha256=os9ggFllqOZXYcjfKcxPIy92LuRfvt6jWL0gNfet1N0,545
-fpathlib/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fpathlib/ext/polars.py,sha256=lamkEI1CKW0g1n6jvj0aJug-ypyNqa_H3vdTb6YfmIo,12819
-fpathlib-0.1.4.dev12.dist-info/licenses/LICENSE,sha256=76rZ9i4ZumZ1M4jlYM9ZDOTYEeyzuxdsTKjF2qha3Lc,1069
-fpathlib-0.1.4.dev12.dist-info/METADATA,sha256=bvmweQlBt9HiLoAJK7qZ38IyclOD0a8kOhUUc_1RgdA,2142
-fpathlib-0.1.4.dev12.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-fpathlib-0.1.4.dev12.dist-info/top_level.txt,sha256=QT5pDgO4--AJn7X4RB51xpNTt0pD5_U2mCjsydpQAQw,9
-fpathlib-0.1.4.dev12.dist-info/RECORD,,