pathseq 0.1.0__tar.gz → 1.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pathseq
-Version: 0.1.0
+Version: 1.0.0
 Summary: A pathlib-like library for working with file sequences.
 Author: Ashley Whetter
 Author-email: Ashley Whetter <ashley@awhetter.co.uk>
@@ -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,93 @@ 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')
+
+    >>> LoosePathSequence("/path/to/images.1001-1005<UVTILE>.exr")[0]
+    PosixPath('/path/to/images.u1_v1.exr')
+
 
 Contributing
 ------------
@@ -94,19 +165,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/README.rst

@@ -0,0 +1,178 @@
+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')
+
+    >>> LoosePathSequence("/path/to/images.1001-1005<UVTILE>.exr")[0]
+    PosixPath('/path/to/images.u1_v1.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-0.1.0 → pathseq-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pathseq"
-version = "0.1.0"
+version = "1.0.0"
 description = "A pathlib-like library for working with file sequences."
 authors = [
     {name = "Ashley Whetter", email = "ashley@awhetter.co.uk"},
@@ -78,6 +78,7 @@ 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}/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,21 +11,23 @@ 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"
 
 __all__ = (
     "BasePathSequence",
     "BasePurePathSequence",
+    "Completeness",
     "FileNumSequence",
     "FileNumT",
-    "IncompleteDimensionError",
+    "Formatter",
     "LoosePathSequence",
     "LoosePurePathSequence",
     "NotASequenceError",

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

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

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

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+import dataclasses
+from decimal import Decimal
+import typing
+
+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)

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

@@ -5,18 +5,16 @@ from typing import Literal, TypeAlias, Union
 
 from typing_extensions import Self  # PY311
 
-from ._base import (
-    non_recursive_asdict,
-    stringify_parsed_sequence,
-    Ranges,
-)
+from ._formatter import Formatter
+from ._ranges import Ranges
+from ._util import non_recursive_asdict
 
 
 @dataclass(frozen=True)
 class RangesStartName:
     """A parsed loose path sequence where the range starts a path's name."""
 
-    prefix: Literal[""]
+    pre_range: Literal[""]
     """An optional single character separator between the ranges and the previous component.
 
     This is always empty for file names where the ranges start the name,
@@ -25,7 +23,7 @@ class RangesStartName:
     """
     ranges: Ranges
     """The file numbers of the files in the sequence and their formatting."""
-    postfix: str
+    post_range: Literal["_", ""]
     """An optional single character separator between the ranges and the next component.
 
     In sequences where the ranges start the name,
@@ -33,7 +31,7 @@ class RangesStartName:
     :ref:`stem <format-loose-stem>`.
     """
     stem: str
-    """The name of the sequence, without the prefix, ranges, postfix, and suffixes."""
+    """The name of the sequence, without the pre-range separator, ranges, post-range separator, and suffixes."""
     suffixes: tuple[str, ...]
     """The file extensions of the files in the path sequence.
 
@@ -41,17 +39,17 @@ class RangesStartName:
     """
 
     def __str__(self) -> str:
-        return stringify_parsed_sequence(self)
+        return Formatter().format(self)
 
     def with_stem(self, stem: str) -> Self:
         """Return a new parsed sequence with the :attr:`~.RangesStartName.stem` changed.
 
-        If the stem is removed, the postfix will be as well.
+        If the stem is removed, the post-range separator will be as well.
         """
         kwargs = non_recursive_asdict(self)
         kwargs["stem"] = stem
         if not stem:
-            kwargs["postfix"] = ""
+            kwargs["post_range"] = ""
         return self.__class__(**kwargs)
 
     def with_suffix(self, suffix: str) -> Self:
@@ -86,8 +84,8 @@ class RangesInName:
     """A parsed loose range sequence where the range follows a path's stem."""
 
     stem: str
-    """The name of the sequence, without the prefix, ranges, postfix, and suffixes."""
-    prefix: str
+    """The name of the sequence, without the pre-range separator, ranges, post-range separator, and suffixes."""
+    pre_range: str
     """An optional single character separator between the ranges and the previous component.
 
     In sequences where the ranges are in the name,
@@ -96,8 +94,8 @@ class RangesInName:
     """
     ranges: Ranges
     """The file numbers of the files in the sequence and their formatting."""
-    postfix: str
-    """An optional single character separator between the ranges and the next component.
+    post_range: str
+    """An optional separator between the ranges and the next component.
 
     In sequences where the ranges are in the name,
     this separates the :ref:`ranges <format-loose-range>` from the
@@ -110,17 +108,17 @@ class RangesInName:
     """
 
     def __str__(self) -> str:
-        return stringify_parsed_sequence(self)
+        return Formatter().format(self)
 
     def with_stem(self, stem: str) -> Self:
         """Return a new parsed sequence with the :attr:`~.RangesInName.stem` changed.
 
-        If the stem is removed, the prefix will be as well.
+        If the stem is removed, the pre-range separator will be as well.
         """
         kwargs = non_recursive_asdict(self)
         kwargs["stem"] = stem
         if not stem and self.stem:
-            kwargs["prefix"] = ""
+            kwargs["pre_range"] = ""
         return self.__class__(**kwargs)
 
     def with_suffix(self, suffix: str) -> Self:
@@ -146,7 +144,7 @@ class RangesInName:
             kwargs = non_recursive_asdict(self)
             kwargs["suffixes"] = self.suffixes[:-1]
             if not kwargs["suffixes"]:
-                kwargs["postfix"] = ""
+                kwargs["post_range"] = ""
             return self.__class__(**kwargs)
 
         return self
@@ -157,13 +155,13 @@ class RangesEndName:
     """A parsed loose range sequence where the range ends a path's name."""
 
     stem: str
-    """The name of the sequence, without the prefix, ranges, postfix, and suffixes."""
+    """The name of the sequence, without the pre-range separator, ranges, post-range separator, and suffixes."""
     suffixes: tuple[str, ...]
     """The file extensions of the files in the path sequence.
 
     Each suffix includes the leading "``.``".
     """
-    prefix: str
+    pre_range: str
     """An optional single character separator between the ranges and the previous component.
 
     In sequences where the ranges are in the name,
@@ -172,8 +170,8 @@ class RangesEndName:
     """
     ranges: Ranges
     """The file numbers of the files in the sequence and their formatting."""
-    postfix: Literal[""]
-    """An optional single character separator between the ranges and the next component.
+    post_range: Literal[""]
+    """An optional separator between the ranges and the next component.
 
     This is always empty for file names where the ranges end the name,
     but is included so that :class:`~.RangesStartName`, :class:`~.RangesInName`,
@@ -181,7 +179,7 @@ class RangesEndName:
     """
 
     def __str__(self) -> str:
-        return stringify_parsed_sequence(self)
+        return Formatter().format(self)
 
     def with_stem(self, stem: str) -> Self:
         """Return a new parsed sequence with the :attr:`~.RangesEndName.stem` changed."""