pathseq 0.1.0__tar.gz → 1.0.0.post0__tar.gz

{pathseq-0.1.0 → pathseq-1.0.0.post0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pathseq
-Version: 0.1.0
+Version: 1.0.0.post0
 Summary: A pathlib-like library for working with file sequences.
 Author: Ashley Whetter
 Author-email: Ashley Whetter <ashley@awhetter.co.uk>
@@ -21,8 +21,8 @@ Requires-Dist: lark
 Requires-Dist: python-statemachine
 Requires-Dist: typing-extensions
 Requires-Python: >=3.10
-Project-URL: Documentation, https://pathseq.readthedocs.org
 Project-URL: Source, https://github.com/AWhetter/pathseq
+Project-URL: Documentation, https://pathseq.readthedocs.org
 Description-Content-Type: text/x-rst
 
 pathseq
@@ -44,14 +44,12 @@ pathseq
     :target: https://pypi.org/project/pathseq/
     :alt: Supported Python Versions
 
-A pathlib-first library for working with file sequences.
+A pathlib-first library for working with path sequences.
 
-TODO: Note special features
-
-* Multi-dimension ranges (eg animated udims)
+* Multi-dimension ranges (e.g. animated udims)
 * pathlib-first API
 * Support for UDIM tokens
-* Sequence compression?
+
 
 Getting Started
 ---------------
@@ -63,20 +61,90 @@ Full documentation is available here: https://pathseq.readthedocs.io/en/latest/
 Installation
 ~~~~~~~~~~~~
 
-``pathseq`` can be installed through pip:
+``pathseq`` can be installed from PyPI:
 
 .. code-block:: bash
 
     pip install pathseq
 
+
 Usage
 ~~~~~
 
-TODO
-
 For more detailed usage, see the documentation:
 https://pathseq.readthedocs.io/en/latest/
 
+Now, let's get started:
+
+.. code-block:: pycon
+
+    >>> from pathseq import PathSequence
+    >>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
+    >>> for path in seq:
+    ...     path
+    ...
+    PosixPath('tests/fixtures/simple/images.0001.exr')
+    PosixPath('tests/fixtures/simple/images.0002.exr')
+    PosixPath('tests/fixtures/simple/images.0003.exr')
+    PosixPath('tests/fixtures/simple/images.0004.exr')
+    PosixPath('tests/fixtures/simple/images.0005.exr')
+
+    >>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
+    >>> for path in seq:
+    ...     path.touch(exist_ok=True)
+    ...
+    >>> seq2 = PathSequence("tests/fixtures/simple/images.####.exr")
+    >>> for path in seq2.iter_existing_paths():
+    ...    path
+    ...
+    PosixPath('tests/fixtures/simple/images.0001.exr')
+    PosixPath('tests/fixtures/simple/images.0002.exr')
+    PosixPath('tests/fixtures/simple/images.0003.exr')
+    PosixPath('tests/fixtures/simple/images.0004.exr')
+    PosixPath('tests/fixtures/simple/images.0005.exr')
+
+    >>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
+    >>> seq.parent
+    PosixPath('tests/fixtures/simple')
+    >>> seq.parent / PathSequence("images.1-5####.exr")
+    ... PathSequence("tests/fixtures/simple/images.1-5####.exr")
+
+    >>> anim_udims = PathSequence("/path/to/textures.1011-1012<UDIM>_1-3#.tex")
+    >>> for path in anim_udims:
+    ...     path
+    ...
+    PosixPath('/path/to/textures.1011_1.tex')
+    PosixPath('/path/to/textures.1011_2.tex')
+    PosixPath('/path/to/textures.1011_3.tex')
+    PosixPath('/path/to/textures.1012_1.tex')
+    PosixPath('/path/to/textures.1012_2.tex')
+    PosixPath('/path/to/textures.1012_3.tex')
+
+A wide range of sequence string formats are supported:
+
+.. code-block:: pycon
+
+    >>> from pathseq import LoosePathSequence
+    >>> seq = LoosePathSequence("/path/to/images.1-5####.exr")
+
+    >>> seq = LoosePathSequence("/path/to/1-5####_images.exr")
+    >>> seq[0]
+    PosixPath('/path/to/0001_images.exr')
+    >>> seq.suffixes
+    ('.exr',)
+
+    >>> LoosePathSequence("/path/to/1-5####_archives.tar.gz").suffixes
+    ('.tar', '.gz')
+
+    >>> seq = LoosePathSequence("/path/to/images.exr.1-5####")
+    >>> seq[0]
+    PosixPath('/path/to/images.exr.0001')
+    >>> seq.suffixes
+    ('.exr',)
+
+    >>> LoosePathSequence("/path/to/images.1001-1005<UDIM>.exr")[0]
+    PosixPath('/path/to/images.1001.exr')
+
 
 Contributing
 ------------
@@ -94,19 +162,19 @@ Tests are executed through `tox <https://tox.readthedocs.io/en/latest/>`_.
 Code Style
 ~~~~~~~~~~
 
-Code is formatted using `black <https://github.com/python/black>`_.
+Code is formatted using `ruff <https://docs.astral.sh/ruff/formatter/>`_.
 
-You can check your formatting using black's check mode:
+You can check your formatting using ruff's check mode:
 
 .. code-block:: bash
 
     tox -e format
 
-You can also get black to format your changes for you:
+You can also get ruff to format your changes for you:
 
 .. code-block:: bash
 
-    tox -e format -- src/ tests/
+    tox -e autoformat
 
 
 Release Notes

pathseq-1.0.0.post0/README.rst

@@ -0,0 +1,175 @@
+pathseq
+=======
+
+.. image:: https://readthedocs.org/projects/pathseq/badge/?version=latest
+    :target: https://pathseq.readthedocs.org
+    :alt: Documentation
+
+.. image:: https://github.com/AWhetter/pathseq/actions/workflows/main.yml/badge.svg?branch=main
+    :target: https://github.com/AWhetter/pathseq/actions/workflows/main.yml?query=branch%3Amain
+    :alt: Github Build Status
+
+.. image:: https://img.shields.io/pypi/v/pathseq.svg
+    :target: https://pypi.org/project/pathseq/
+    :alt: PyPI Version
+
+.. image:: https://img.shields.io/pypi/pyversions/pathseq.svg
+    :target: https://pypi.org/project/pathseq/
+    :alt: Supported Python Versions
+
+A pathlib-first library for working with path sequences.
+
+* Multi-dimension ranges (e.g. animated udims)
+* pathlib-first API
+* Support for UDIM tokens
+
+
+Getting Started
+---------------
+
+The following section demonstrates how to install ``pathseq`` and some basic usage.
+Full documentation is available here: https://pathseq.readthedocs.io/en/latest/
+
+
+Installation
+~~~~~~~~~~~~
+
+``pathseq`` can be installed from PyPI:
+
+.. code-block:: bash
+
+    pip install pathseq
+
+
+Usage
+~~~~~
+
+For more detailed usage, see the documentation:
+https://pathseq.readthedocs.io/en/latest/
+
+Now, let's get started:
+
+.. code-block:: pycon
+
+    >>> from pathseq import PathSequence
+    >>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
+    >>> for path in seq:
+    ...     path
+    ...
+    PosixPath('tests/fixtures/simple/images.0001.exr')
+    PosixPath('tests/fixtures/simple/images.0002.exr')
+    PosixPath('tests/fixtures/simple/images.0003.exr')
+    PosixPath('tests/fixtures/simple/images.0004.exr')
+    PosixPath('tests/fixtures/simple/images.0005.exr')
+
+    >>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
+    >>> for path in seq:
+    ...     path.touch(exist_ok=True)
+    ...
+    >>> seq2 = PathSequence("tests/fixtures/simple/images.####.exr")
+    >>> for path in seq2.iter_existing_paths():
+    ...    path
+    ...
+    PosixPath('tests/fixtures/simple/images.0001.exr')
+    PosixPath('tests/fixtures/simple/images.0002.exr')
+    PosixPath('tests/fixtures/simple/images.0003.exr')
+    PosixPath('tests/fixtures/simple/images.0004.exr')
+    PosixPath('tests/fixtures/simple/images.0005.exr')
+
+    >>> seq = PathSequence("tests/fixtures/simple/images.1-5####.exr")
+    >>> seq.parent
+    PosixPath('tests/fixtures/simple')
+    >>> seq.parent / PathSequence("images.1-5####.exr")
+    ... PathSequence("tests/fixtures/simple/images.1-5####.exr")
+
+    >>> anim_udims = PathSequence("/path/to/textures.1011-1012<UDIM>_1-3#.tex")
+    >>> for path in anim_udims:
+    ...     path
+    ...
+    PosixPath('/path/to/textures.1011_1.tex')
+    PosixPath('/path/to/textures.1011_2.tex')
+    PosixPath('/path/to/textures.1011_3.tex')
+    PosixPath('/path/to/textures.1012_1.tex')
+    PosixPath('/path/to/textures.1012_2.tex')
+    PosixPath('/path/to/textures.1012_3.tex')
+
+A wide range of sequence string formats are supported:
+
+.. code-block:: pycon
+
+    >>> from pathseq import LoosePathSequence
+    >>> seq = LoosePathSequence("/path/to/images.1-5####.exr")
+
+    >>> seq = LoosePathSequence("/path/to/1-5####_images.exr")
+    >>> seq[0]
+    PosixPath('/path/to/0001_images.exr')
+    >>> seq.suffixes
+    ('.exr',)
+
+    >>> LoosePathSequence("/path/to/1-5####_archives.tar.gz").suffixes
+    ('.tar', '.gz')
+
+    >>> seq = LoosePathSequence("/path/to/images.exr.1-5####")
+    >>> seq[0]
+    PosixPath('/path/to/images.exr.0001')
+    >>> seq.suffixes
+    ('.exr',)
+
+    >>> LoosePathSequence("/path/to/images.1001-1005<UDIM>.exr")[0]
+    PosixPath('/path/to/images.1001.exr')
+
+
+Contributing
+------------
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+
+Tests are executed through `tox <https://tox.readthedocs.io/en/latest/>`_.
+
+.. code-block:: bash
+
+    tox
+
+
+Code Style
+~~~~~~~~~~
+
+Code is formatted using `ruff <https://docs.astral.sh/ruff/formatter/>`_.
+
+You can check your formatting using ruff's check mode:
+
+.. code-block:: bash
+
+    tox -e format
+
+You can also get ruff to format your changes for you:
+
+.. code-block:: bash
+
+    tox -e autoformat
+
+
+Release Notes
+~~~~~~~~~~~~~
+
+Release notes are managed through `towncrier <https://towncrier.readthedocs.io/en/stable/index.html>`_.
+When making a pull request you will need to create a news fragment to document your change:
+
+.. code-block:: bash
+
+    tox -e release_notes -- create --help
+
+
+Versioning
+----------
+
+We use `SemVer <https://semver.org/>`_ for versioning.
+For the versions available, see the `tags on this repository <https://github.com/AWhetter/pathseq/tags>`_.
+
+
+License
+-------
+
+This project is licensed under the MIT License.
+See the `LICENSE.rst <LICENSE.rst>`_ file for details.

pathseq-1.0.0.post0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["uv_build>=0.8.5,<1.0.0"]
+build-backend = "uv_build"
+
+[project]
+name = "pathseq"
+version = "1.0.0.post0"
+description = "A pathlib-like library for working with file sequences."
+readme = "README.rst"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Plugins",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "lark",
+    "python-statemachine",
+    "typing_extensions",
+]
+
+[[project.authors]]
+name = "Ashley Whetter"
+email = "ashley@awhetter.co.uk"
+
+[project.urls]
+Source = "https://github.com/AWhetter/pathseq"
+Documentation = "https://pathseq.readthedocs.org"
+
+[dependency-groups]
+test = [
+    "fileseq",
+    "hypothesis",
+    "pytest",
+]
+format = ["ruff"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+doc = [
+    "furo",
+    "sphinx",
+    "sphinx-design",
+]
+release_notes = ["towncrier"]
+
+[[dependency-groups.dev]]
+include-group = "test"
+
+[[dependency-groups.dev]]
+include-group = "format"
+
+[[dependency-groups.dev]]
+include-group = "lint"
+
+[[dependency-groups.dev]]
+include-group = "typecheck"
+
+[[dependency-groups.dev]]
+include-group = "doc"
+
+[tool.uv.build-backend]
+module-name = "pathseq"
+
+[tool.mypy]
+strict = true
+
+[tool.towncrier]
+directory = "doc/changes"
+filename = "CHANGELOG.rst"
+package = "pathseq"
+title_format = "pathseq v{version} ({project_date})"
+underlines = [
+    "-",
+    "^",
+    '"',
+]
+
+[tool.pytest.ini_options]
+markers = ["todo"]
+addopts = "--doctest-glob='[!0]*.rst' --doctest-modules --ignore=doc/source/conf.py"
+doctest_optionflags = "ELLIPSIS"
+testpaths = [
+    "tests",
+    "doc/source",
+    "src",
+]

pathseq-0.1.0/pyproject.toml → pathseq-1.0.0.post0/pyproject.toml.orig

@@ -1,6 +1,10 @@
+[build-system]
+requires = ["uv_build>=0.8.5,<1.0.0"]
+build-backend = "uv_build"
+
 [project]
 name = "pathseq"
-version = "0.1.0"
+version = "1.0.0.post0"
 description = "A pathlib-like library for working with file sequences."
 authors = [
     {name = "Ashley Whetter", email = "ashley@awhetter.co.uk"},
@@ -63,21 +67,18 @@ release_notes = [
     "towncrier",
 ]
 
-[build-system]
-requires = ["uv_build>=0.8.5,<0.9.0"]
-build-backend = "uv_build"
-
 [tool.uv.build-backend]
 module-name = "pathseq"
 
-[tool.pylint]
-disable = "R,unused-argument"
+[tool.mypy]
+strict = true
 
 [tool.towncrier]
 directory = "doc/changes"
 filename = "CHANGELOG.rst"
 package = "pathseq"
 title_format = "pathseq v{version} ({project_date})"
+underlines = ["-", "^", "\""]
 
 [tool.pytest.ini_options]
 markers = [

{pathseq-0.1.0 → pathseq-1.0.0.post0}/src/pathseq/__init__.py

@@ -1,7 +1,7 @@
 """A pathlib-first library for working with file sequences."""
 
 from ._ast import (
-    FileNumT,
+    Formatter,
     PaddedRange,
     ParsedLooseSequence,
     ParsedSequence,
@@ -11,27 +11,29 @@ from ._ast import (
     RangesStartName,
 )
 from ._base import BasePathSequence, BasePurePathSequence, PathT_co, PurePathT_co
-from ._error import IncompleteDimensionError, NotASequenceError, ParseError
-from ._file_num_seq import FileNumSequence
+from ._error import NotASequenceError, ParseError
+from ._file_num_seq import FileNumSequence, FileNumT
+from ._from_disk import Completeness
 from ._loose_path_sequence import LoosePathSequence
 from ._loose_pure_path_sequence import LoosePurePathSequence
 from ._path_sequence import PathSequence
 from ._pure_path_sequence import PurePathSequence
 
-__version__ = "0.1.0"
+__version__ = "1.0.0.post0"
 
 __all__ = (
     "BasePathSequence",
     "BasePurePathSequence",
+    "Completeness",
     "FileNumSequence",
     "FileNumT",
-    "IncompleteDimensionError",
+    "Formatter",
     "LoosePathSequence",
     "LoosePurePathSequence",
     "NotASequenceError",
     "PaddedRange",
-    "ParsedLooseSequence",
     "ParseError",
+    "ParsedLooseSequence",
     "ParsedSequence",
     "PathSequence",
     "PathT_co",

{pathseq-0.1.0 → pathseq-1.0.0.post0}/src/pathseq/_ast/__init__.py

@@ -1,22 +1,22 @@
-from ._base import FileNum, FileNumT, PaddedRange, Ranges
 from ._formatter import Formatter
 from ._loose_type import (
     ParsedLooseSequence,
-    RangesStartName,
-    RangesInName,
     RangesEndName,
+    RangesInName,
+    RangesStartName,
 )
+from ._ranges import PaddedRange, Ranges
 from ._type import ParsedSequence
+from ._util import non_recursive_asdict
 
 __all__ = [
-    "FileNum",
-    "FileNumT",
     "Formatter",
     "PaddedRange",
     "ParsedLooseSequence",
     "ParsedSequence",
     "Ranges",
-    "RangesStartName",
-    "RangesInName",
     "RangesEndName",
+    "RangesInName",
+    "RangesStartName",
+    "non_recursive_asdict",
 ]

pathseq-1.0.0.post0/src/pathseq/_ast/_formatter.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import dataclasses
+import typing
+from collections.abc import Iterable
+from decimal import Decimal
+
+if typing.TYPE_CHECKING:
+    from ._loose_type import ParsedLooseSequence
+    from ._ranges import PaddedRange, Ranges
+    from ._type import ParsedSequence
+
+
+def _splice_strings_onto_ranges(
+    strings: Iterable[str], inter_ranges: Iterable[str]
+) -> str:
+    """Format the given range strings and inter-range strings together.
+
+    Raises:
+        TypeError: If the given number of strings does not match
+            the number of inter-range strings minus one.
+    """
+    result = ""
+
+    strs = iter(strings)
+    for inter_range in inter_ranges:
+        try:
+            result += next(strs)
+        except StopIteration:
+            break
+
+        result += inter_range
+    else:
+        try:
+            result += next(strs)
+        except StopIteration:
+            pass
+        else:
+            try:
+                next(strs)
+            except StopIteration:
+                return result
+
+    raise TypeError(
+        "The number of inter-range strings given does not match"
+        " the number of range strings given minus one."
+    )
+
+
+class Formatter:
+    """A :class:`Formatter` formats a parsed sequence into a string.
+
+    The purpose of the class is primarily for converting from a
+    :ref:`simple <simple-format>` or :ref:`loose <loose-format>` sequence
+    into other sequence formats by overriding this class.
+
+    Example:
+
+        .. code-block:: pycon
+
+            >>> class HoudiniFormatter(pathseq.Formatter):
+            ...   def range(self, range_):
+            ...       return "$F"
+            ...
+            >>> seq = pathseq.PathSequence("image.1-5#.exr")
+            >>> HoudiniFormatter().format(seq.parsed)
+            'image.$F.exr'
+    """
+
+    def __init__(self) -> None:
+        self.include_all_suffixes = False
+        """Whether to include all suffixes in the formatted sequence.
+
+        This is set by :meth:`~.Formatter.format` to indicate whether the
+        suffixes have been cleanly separated from the stem or not.
+        If this is ``False``, then the ``stem`` and ``suffixes`` will overlap
+        and both include all but the last suffix.
+        """
+
+    def stem(self, stem: str) -> str:
+        return stem
+
+    def pre_range(self, pre_range: str) -> str:
+        return pre_range
+
+    def range(self, range_: PaddedRange[int] | PaddedRange[Decimal]) -> str:
+        return str(range_)
+
+    def inter_range(self, inter_range: str) -> str:
+        return inter_range
+
+    def ranges(self, ranges: Ranges) -> str:
+        return self.splice_inter_ranges(
+            (self.range(range_) for range_ in ranges.ranges),
+            (self.inter_range(inter_range) for inter_range in ranges.inter_ranges),
+        )
+
+    def post_range(self, post_range: str) -> str:
+        return post_range
+
+    def suffixes(self, suffixes: tuple[str, ...]) -> str:
+        return "".join(suffixes if self.include_all_suffixes else suffixes[-1:])
+
+    def format(self, seq: ParsedSequence | ParsedLooseSequence) -> str:
+        """Format the given path sequence into a string.
+
+        The parsed sequence is traversed, and each node is formatted
+        according to the implementation of the associated method on this class.
+
+        Args:
+            seq: The path sequence to format into a string.
+
+        Returns:
+            The formatter path sequence.
+        """
+        from ._loose_type import RangesInName
+        from ._type import ParsedSequence
+
+        self.include_all_suffixes = bool(
+            isinstance(seq, ParsedSequence)
+            or (isinstance(seq, RangesInName) and seq.ranges.ranges)
+        )
+
+        return "".join(
+            getattr(self, field.name)(getattr(seq, field.name))
+            for field in dataclasses.fields(seq)
+        )
+
+    def splice_inter_ranges(
+        self, strings: Iterable[str], inter_ranges: Iterable[str]
+    ) -> str:
+        """Format the given range strings and inter-range strings together.
+
+        Raises:
+            TypeError: If the given number of strings does not match
+                the number of inter-range strings minus one.
+        """
+        return _splice_strings_onto_ranges(strings, inter_ranges)