fpathlib 0.1.3__tar.gz → 0.1.4__tar.gz

{fpathlib-0.1.3 → fpathlib-0.1.4}/.gitignore

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

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

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

fpathlib-0.1.4/conda-recipe/meta.yaml

@@ -0,0 +1,39 @@
+{% set name = "fpathlib" %}
+{% set version = "0.1.3" %}
+
+package:
+  name: {{ name|lower }}
+  version: {{ version }}
+
+source:
+  url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/fpathlib-{{ version }}.tar.gz
+  sha256: 059dbf937c6e965ef33f15aa214b2f354550d5dfa26b9030357954cce8c51874
+
+build:
+  noarch: python
+  number: 0
+  script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation
+
+requirements:
+  host:
+    - python >=3.12
+    - pip
+    - setuptools >=68
+    - setuptools_scm
+    - wheel
+  run:
+    - python >=3.12
+    - parse
+
+test:
+  imports:
+    - fpathlib
+
+about:
+  summary: A package to combine paths with metadata
+  license: MIT
+  home: https://github.com/LockhartLab/fpathlib
+
+extra:
+  recipe-maintainers:
+    - clockhart

fpathlib-0.1.4/scripts/conda.sh

@@ -0,0 +1,50 @@
+# Builds and uploads the conda package for the version pypi.sh just
+# published, to the lockhartlab org on anaconda.org. Must run AFTER
+# pypi.sh, since it reads the sdist checksum back from PyPI's JSON API
+# (retrying briefly -- new uploads take a few seconds to index).
+#
+# Requires a local micromamba env named "fpathlib-build" with conda-build
+# and anaconda-client installed, and an active `anaconda login --at
+# anaconda.org` session for an account with upload rights to lockhartlab:
+#   micromamba create -n fpathlib-build -c conda-forge conda-build anaconda-client
+#   micromamba run -n fpathlib-build anaconda login --at anaconda.org
+
+version=$(git describe --tags --abbrev=0)
+
+sha256=""
+for i in 1 2 3 4 5
+do
+  sha256=$(curl -s "https://pypi.org/pypi/fpathlib/$version/json" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    for f in d['urls']:
+        if f['filename'].endswith('.tar.gz'):
+            print(f['digests']['sha256'])
+            break
+except Exception:
+    pass
+")
+  if [ -n "$sha256" ]
+  then
+    break
+  fi
+  sleep 5
+done
+
+if [ -z "$sha256" ]
+then
+  echo "could not fetch sdist sha256 from PyPI for $version yet, skipping conda build -- rerun scripts/conda.sh once PyPI has indexed the release"
+  return
+fi
+
+sed -i '' -E "s/\{% set version = \"[^\"]+\" %\}/{% set version = \"$version\" %}/" conda-recipe/meta.yaml
+sed -i '' -E "s/sha256: .+/sha256: $sha256/" conda-recipe/meta.yaml
+
+rm -rf /tmp/conda-build-out
+micromamba run -n fpathlib-build conda-build conda-recipe -c conda-forge --output-folder /tmp/conda-build-out
+micromamba run -n fpathlib-build anaconda upload "/tmp/conda-build-out/noarch/fpathlib-$version-py_0.conda" --user lockhartlab
+
+git add conda-recipe/meta.yaml
+git commit -m "conda-recipe: bump to $version"
+git push origin main

fpathlib-0.1.4/scripts/deploy.sh

@@ -0,0 +1,13 @@
+# Full release: build docs, bump+push the patch tag, build and upload to
+# PyPI, then build and upload to conda (lockhartlab org). Order matters --
+# tag.sh must run before pypi.sh so that HEAD is exactly on the new tag
+# (clean release, no .devN) when pypi.sh builds, and conda.sh must run
+# after pypi.sh since it packages what was just published to PyPI.
+# For an interim dev release without cutting a tag, run
+# `source scripts/pypi.sh dev` directly instead of this script.
+set -e
+
+source scripts/docs.sh
+source scripts/tag.sh "patch"
+source scripts/pypi.sh
+source scripts/conda.sh

fpathlib-0.1.4/scripts/pypi.sh

@@ -0,0 +1,35 @@
+# Builds and (usually) uploads to PyPI. setuptools_scm derives the version
+# purely from git: exactly on a tag with a clean tree -> "X.Y.Z"; ahead of
+# the last tag, or a dirty tree -> "X.Y.Z.devN". Run this on its own (e.g.
+# `source scripts/pypi.sh dev`) to intentionally publish an interim dev
+# build while iterating; deploy.sh runs tag.sh first so that by the time
+# this script runs, HEAD should be exactly on the new tag and produce a
+# clean release -- if it doesn't, something upstream is wrong (see below).
+allow_dev=0
+if [ "$1" = "dev" ]
+then
+  allow_dev=1
+fi
+
+# Stale dist/ or egg-info from a previous failed run can leak into `twine
+# upload dist/*` (multiple versions at once) or shadow a fresh build.
+rm -rf dist src/fpathlib.egg-info
+
+python3 -m build
+
+# Belt-and-suspenders check: rather than trust git state ahead of time (the
+# 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]')
+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"
+  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.4/scripts/tag.sh

@@ -0,0 +1,56 @@
+# Bumps the version tag and pushes it. This MUST leave HEAD on a commit that
+# is not shared with any older tag, or setuptools_scm can't tell the new tag
+# apart from the old one and pypi.sh will build a .devN version instead of a
+# clean release (see the 0.1.3/0.1.2 incident: both tags landed on the same
+# commit because there was nothing new to commit, so setuptools_scm treated
+# the checkout as ambiguous).
+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]}"
+
+# Fail loudly instead of leaving a stale/misplaced tag if $tag already exists
+# (locally or on origin) -- creating it again would either error out partway
+# through or, worse, silently retag the wrong commit.
+if git rev-parse -q --verify "refs/tags/$tag" >/dev/null
+then
+  echo "tag $tag already exists locally -- delete it first (git tag -d $tag) if you really want to redo this release"
+  return
+fi
+if git ls-remote --exit-code --tags origin "$tag" >/dev/null 2>&1
+then
+  echo "tag $tag already exists on origin -- delete it first (git push origin :refs/tags/$tag) if you really want to redo this release"
+  return
+fi
+
+git add -A
+# --allow-empty is required: if there's nothing to commit (working tree
+# already clean), a plain `git commit` would no-op and this tag would end up
+# pointing at the SAME commit as the previous tag, confusing setuptools_scm.
+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 → fpathlib-0.1.4}/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.3 → fpathlib-0.1.4}/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.3'
-__version_tuple__ = version_tuple = (0, 1, 3)
+__version__ = version = '0.1.4'
+__version_tuple__ = version_tuple = (0, 1, 4)
 
-__commit_id__ = commit_id = 'g02b650d92'
+__commit_id__ = commit_id = 'gd0a205773'

{fpathlib-0.1.3 → fpathlib-0.1.4}/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`.
@@ -88,7 +120,8 @@ def expand_fpath_decorator(f=None, require_expandable=True, post_process=None):
 
 def is_expandable(fpath):
     """
-    Check if expandable.
+    Check whether `fpath` has fpathlib's own named f-string captures (e.g.
+    `{name}`).
 
     Parameters
     ----------

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

@@ -169,6 +169,7 @@ def scan_txt(
     has_header=False,
     keep_line=False,
     usecols=None,
+    validate_schema=True,
     *args,
     **kwargs,
 ):
@@ -198,6 +199,17 @@ def scan_txt(
         Whether to keep the original line as a column in the output.
     usecols : :obj:`list`[:obj:`int`], optional
         Indexes of columns to keep in the output. If not provided, all columns are kept. Only applicable if `separator` is provided.
+    validate_schema : :obj:`bool`
+        When the field count is inferred from a single representative file
+        (the fast path for a multi-file glob/pattern), also check that no
+        *other* matched file has *more* fields than that sample. A file with
+        fewer fields than the sample already raises a clear polars error
+        (out-of-bounds list access); a file with more fields would otherwise
+        have its extra columns silently dropped instead of erroring. This
+        check reads every matched file's line count, which costs an extra
+        full pass over the data on top of the fast path -- pass False if
+        you've already confirmed your files are consistent and want to
+        skip it for speed on very large globs. (Default: True)
     *args
         Positional arguments to pass to :meth:`polars.scan_csv`.
     **kwargs
@@ -282,6 +294,26 @@ def scan_txt(
             # Initial field names, may be renamed later from header or by `new_columns`
             fields = {i: f"field_{i}" for i in range(n_fields)}
 
+            # n_fields came from a single sample file (see above), so a file
+            # with *fewer* fields than the sample will already raise a clear
+            # polars error below (list.get() on an out-of-bounds index). A
+            # file with *more* fields would not -- its extra columns would
+            # just be silently dropped -- so check for that explicitly if
+            # requested.
+            if validate_schema and sample_schema is not None:
+                max_fields = (
+                    lf.select(_polars.col("fields").list.len().max())
+                    .collect()
+                    .item()
+                )
+                if max_fields is not None and max_fields > n_fields:
+                    msg = (
+                        f"field count mismatch: schema was inferred from a "
+                        f"single sample file with {n_fields} fields, but at "
+                        f"least one matched file has {max_fields} fields"
+                    )
+                    raise ValueError(msg)
+
         # Add each field as a separate column
         for i, field in fields.items():
             lf = lf.with_columns(_polars.col("fields").list.get(i).alias(field))

{fpathlib-0.1.3 → fpathlib-0.1.4}/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"}:
@@ -58,8 +67,34 @@ class FPath:
 
         parser = parse.compile(self.fpath)
 
-        paths = []
-        for fname in glob(re.sub(r"\{.*?\}", "*", self.fpath)):
+        # glob() (used below to find files) and `parse` (used above to
+        # extract {name} values) disagree about what a bare '*', '?', or
+        # '[...]' means outside a {} capture: glob treats it as a wildcard,
+        # but parse's format-string language only special-cases {...} and
+        # reads everything else -- including '*' -- as literal text to
+        # match. A pattern like "{a}/*" would find files fine via glob()
+        # but then fail to parse against that same string, since real
+        # filenames don't literally contain "/*" -- silently producing
+        # metadata=None for every match, or raising a confusing "metadata
+        # not found" error, with no indication that '*' was the actual
+        # problem. Fail fast and explain it instead. Only applies when
+        # there's a {} capture to begin with -- a plain glob with none is a
+        # separate, unaffected case (no metadata is expected from it).
+        if parser.named_fields:
+            literal_fpath = re.sub(r"\{.*?\}", "", self.fpath)
+            for c in "*?[":
+                if c in literal_fpath:
+                    msg = (
+                        f"glob wildcard {c!r} outside a {{}} capture is not "
+                        f"supported in {self.fpath!r} -- 'parse' treats it "
+                        "as a literal character, not a wildcard. Use a "
+                        "named capture (e.g. '{a}/{b}') if you want that "
+                        "segment captured too."
+                    )
+                    raise ValueError(msg)
+
+        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
@@ -67,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)
@@ -78,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)
 
 
@@ -153,7 +218,13 @@ class ExpandedFPath(Sequence):
 
         pl = import_optional_dependency("polars")
 
-        data = [{"fname": str(key), **value} for key, value in self.metadata.items()]
+        # `value` is None whenever this ExpandedFPath was built with
+        # require_metadata=False and a path's metadata simply wasn't found
+        # (e.g. a plain glob with no named captures at all) -- treat that as
+        # "no metadata columns" rather than crashing on `**None`.
+        data = [
+            {"fname": str(key), **(value or {})} for key, value in self.metadata.items()
+        ]
         df = pl.DataFrame(data)
         if lazy:
             df = df.lazy()

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

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

{fpathlib-0.1.3 → fpathlib-0.1.4}/src/fpathlib.egg-info/SOURCES.txt

@@ -4,11 +4,13 @@ MANIFEST.in
 README.md
 TODO.txt
 pyproject.toml
+conda-recipe/meta.yaml
 docs/Makefile
 docs/make.bat
 docs/source/api.rst
 docs/source/conf.py
 docs/source/index.rst
+scripts/conda.sh
 scripts/deploy.sh
 scripts/docs.sh
 scripts/pypi.sh

{fpathlib-0.1.3 → fpathlib-0.1.4}/src/fpathlib.egg-info/scm_file_list.json

@@ -5,12 +5,14 @@
     "MANIFEST.in",
     "README.md",
     "TODO.txt",
+    "conda-recipe/meta.yaml",
     "docs/Makefile",
     "docs/make.bat",
     "docs/source/api.rst",
     "docs/source/conf.py",
     "docs/source/index.rst",
     "pyproject.toml",
+    "scripts/conda.sh",
     "scripts/deploy.sh",
     "scripts/docs.sh",
     "scripts/pypi.sh",

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

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

fpathlib-0.1.3/scripts/deploy.sh

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

fpathlib-0.1.3/scripts/pypi.sh

@@ -1,20 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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.egg-info/scm_version.json

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