pathseq 0.1.0__py3-none-any.whl

pathseq/_parse_path_sequence.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+import collections
+from dataclasses import dataclass
+from decimal import Decimal
+import enum
+import re
+
+from statemachine import StateMachine, State
+
+from ._error import NotASequenceError, ParseError
+from ._file_num_seq import FileNumSequence
+from ._ast import (
+    PaddedRange,
+    ParsedSequence,
+    Ranges,
+)
+
+_PREFIX_SEPARATORS = {".", "_"}
+RANGE_RE = re.compile(
+    r"""
+        -?\d+(?:\.\d+)?
+        (?:                       # optional range
+            -                     #   range delimiter
+            -?\d+(?:\.\d+)?       #   end frame
+            (?:                   #   optional stepping
+                x                 #     step type
+                \d+(?:\.\d+)?     #     step value
+            )?
+        )?
+    """,
+    re.VERBOSE,
+)
+PAD_FORMAT_RE = re.compile(
+    r"""
+        (?:
+            \#+(?:\.\#+)?
+            | <UDIM>
+            | <UVTILE>
+        )
+    """,
+    flags=re.VERBOSE,
+)
+RANGES_RE = re.compile(
+    f"""
+    (
+        (?:{RANGE_RE.pattern} (?:, {RANGE_RE.pattern})*)?
+        {PAD_FORMAT_RE.pattern}
+    )
+    """,
+    flags=RANGE_RE.flags | PAD_FORMAT_RE.flags | re.VERBOSE,
+)
+
+
+class TokenType(enum.Enum):
+    RANGE = enum.auto()
+    INTER_RANGE = enum.auto()
+    STEM = enum.auto()
+    PREFIX = enum.auto()
+    SUFFIXES = enum.auto()
+
+
+@dataclass
+class Token:
+    type: TokenType
+    value: str
+    column: int
+
+    @property
+    def end_column(self) -> int:
+        return self.column + len(self.value)
+
+
+def _tokenise_seq(seq: str) -> list[Token]:
+    raw_tokens = re.split(RANGES_RE, seq)
+    if len(raw_tokens) == 1:
+        raise NotASequenceError(seq)
+
+    return process_tokens(seq, raw_tokens)
+
+
+def process_tokens(seq: str, raw_tokens: list[str]) -> list[Token]:
+    if seq.endswith("."):
+        raise ParseError(seq, len(seq) - 1, reason="Suffixes cannot end with a '.'")
+
+    starts_with_range = not bool(raw_tokens[0])
+    if starts_with_range:
+        raise ParseError(seq, 0, reason="Expected a stem but got a range")
+
+    ends_with_range = not bool(raw_tokens[-1])
+    if ends_with_range:
+        raise ParseError(
+            seq, len(seq), reason="Expected file suffixes but path ends with a range"
+        )
+
+    column = 0
+    tokens: list[Token] = []
+    for i, raw_token in enumerate(raw_tokens):
+        if i == 0:
+            separator = None
+            if raw_token != "." and any(
+                raw_token.endswith(sep) for sep in _PREFIX_SEPARATORS
+            ):
+                separator = Token(
+                    TokenType.PREFIX,
+                    raw_token[-1],
+                    column + len(raw_token) - 1,
+                )
+                raw_token = raw_token[:-1]
+
+            token = Token(
+                TokenType.STEM,
+                raw_token,
+                column,
+            )
+            tokens.append(token)
+
+            if separator:
+                tokens.append(separator)
+        elif i % 2 == 1:
+            token = Token(
+                TokenType.RANGE,
+                raw_token,
+                column,
+            )
+            tokens.append(token)
+        elif i >= 2 and i != len(raw_tokens) - 1:
+            if not raw_token:
+                raise ParseError(
+                    seq,
+                    column + 1,
+                    column + 2,
+                    "Expected a non-empty inter-range separator",
+                )
+            if raw_token == ".":
+                raise ParseError(
+                    seq,
+                    column + 1,
+                    column + 2,
+                    "Cannot use '.' as an inter-range separator",
+                )
+            token = Token(
+                TokenType.INTER_RANGE,
+                raw_token,
+                column,
+            )
+            tokens.append(token)
+        elif i == len(raw_tokens) - 1:
+            if raw_token.startswith("."):
+                token = Token(
+                    TokenType.SUFFIXES,
+                    raw_token,
+                    column,
+                )
+                tokens.append(token)
+            else:
+                raise ParseError(
+                    seq,
+                    column + 1,
+                    column + 2,
+                    "Expected a '.' to begin file suffixes",
+                )
+        else:
+            assert False, "Found a token that should be impossible"
+
+        column += len(raw_token)
+
+    assert all(isinstance(token, Token) for token in tokens)
+    if not any(token.type == TokenType.RANGE for token in tokens):
+        raise NotASequenceError(seq)
+
+    if __debug__:
+        type_counts = collections.Counter(token.type for token in tokens)
+        assert type_counts[TokenType.STEM] <= 1
+        num_pre_seps = type_counts[TokenType.PREFIX]
+        assert num_pre_seps <= 1
+        num_ranges = type_counts[TokenType.RANGE]
+        num_inter_ranges = type_counts[TokenType.INTER_RANGE]
+        assert num_inter_ranges == num_ranges - 1
+        assert type_counts[TokenType.SUFFIXES] <= 1
+
+    return tokens
+
+
+class _SeqParser(StateMachine):
+    init = State(initial=True)
+    stem = State()
+
+    in_prefix = State()
+    range_in_name = State()
+    in_inter_range = State()
+    in_suffixes = State()
+
+    parsed = State(final=True)
+
+    pump = (
+        init.to(stem, validators="expect_stem")
+        | stem.to(in_prefix, cond="is_prefix")
+        | stem.to(range_in_name, validators="expect_prefix_or_range")
+        | in_prefix.to(range_in_name, validators="expect_range")
+        | range_in_name.to(in_inter_range, cond="is_inter_range")
+        | in_inter_range.to(range_in_name, validators="expect_range")
+        | range_in_name.to(in_suffixes, validators="expect_inter_range_or_suffixes")
+    )
+
+    finalise = in_suffixes.to(parsed)
+
+    def __init__(self, seq: str) -> None:
+        super().__init__()
+
+        self._seq = seq
+        self._stem: str = ""
+        self._prefix = ""
+        self._ranges: list[PaddedRange[int] | PaddedRange[Decimal]] = []
+        self._inter_ranges: list[str] = []
+        self._suffixes: tuple[str, ...] = ()
+
+    def is_inter_range(self, token: Token) -> bool:
+        return token.type == TokenType.INTER_RANGE
+
+    def is_prefix(self, token: Token) -> bool:
+        return token.type == TokenType.PREFIX
+
+    def expect_stem(self, token: Token) -> bool:
+        return self._validate_stem(token, "Expected a stem")
+
+    def expect_prefix_or_range(self, token: Token) -> bool:
+        return self._validate_range(token, "Expected a prefix separator, or the ranges")
+
+    def expect_range(self, token: Token) -> bool:
+        return self._validate_range(token, "Expected the ranges")
+
+    def expect_inter_range_or_suffixes(self, token: Token) -> bool:
+        return self._validate_suffixes(
+            token, "Expected an inter-range string, or file suffixes"
+        )
+
+    def _validate_range(self, token: Token, reason: str) -> bool:
+        if token.type != TokenType.RANGE:
+            raise ParseError(self._seq, token.column, token.end_column, reason=reason)
+        return True
+
+    def _validate_stem(self, token: Token, reason: str) -> bool:
+        if token.type != TokenType.STEM:
+            raise ParseError(self._seq, token.column, token.end_column, reason=reason)
+        return True
+
+    def _validate_suffixes(self, token: Token, reason: str) -> bool:
+        if token.type != TokenType.SUFFIXES:
+            raise ParseError(self._seq, token.column, token.end_column, reason=reason)
+        return True
+
+    def on_enter_stem(self, token: Token) -> None:
+        self._stem = token.value
+
+    def on_enter_in_prefix(self, token: Token) -> None:
+        self._prefix = token.value
+
+    def _parse_padded_range(
+        self, token: Token
+    ) -> PaddedRange[int] | PaddedRange[Decimal]:
+        match = PAD_FORMAT_RE.search(token.value)
+        if not match:
+            raise ParseError(
+                self._seq,
+                token.column,
+                token.end_column,
+                reason=f"Tokenised an invalid range: {token.value}",
+            )
+        pad_format = match.group(0)
+        seq_str = token.value[: -len(pad_format)]
+        file_nums = FileNumSequence.from_str(seq_str)
+        return PaddedRange(file_nums, pad_format)  # type: ignore[misc]
+
+    def _parse_suffixes(self, token: Token) -> tuple[str, ...]:
+        if not token.value:
+            return ()
+
+        suffixes = []
+        buffer = token.value[0]
+        for char in token.value[1:]:
+            if char == ".":
+                if buffer == ".":
+                    column = token.column + len(buffer)
+                    raise ParseError(
+                        self._seq,
+                        column,
+                        column + 1,
+                        "Cannot have an empty file extension",
+                    )
+                suffixes.append(buffer)
+                buffer = char
+            else:
+                buffer += char
+
+        suffixes.append(buffer)
+        return tuple(suffixes)
+
+    def on_enter_range_in_name(self, token: Token) -> None:
+        self._ranges.append(self._parse_padded_range(token))
+
+    def on_enter_in_inter_range(self, token: Token) -> None:
+        self._inter_ranges.append(token.value or "")
+
+    def on_enter_in_suffixes(self, token: Token) -> None:
+        self._suffixes = self._parse_suffixes(token)
+
+    def on_finalise(self) -> ParsedSequence:
+        return ParsedSequence(
+            stem=self._stem,
+            prefix=self._prefix,
+            ranges=Ranges(tuple(self._ranges), tuple(self._inter_ranges)),
+            suffixes=self._suffixes,
+        )
+
+    @classmethod
+    def parse(cls, seq: str) -> ParsedSequence:
+        machine = cls(seq)
+        tokens = _tokenise_seq(seq)
+        for token in tokens:
+            machine.pump(token)
+
+        return machine.finalise()  # type: ignore[no-any-return]
+
+
+def parse_path_sequence(seq: str) -> ParsedSequence:
+    return _SeqParser.parse(seq)

pathseq/_path_sequence.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ._base import BasePathSequence, PathT_co
+from ._pure_path_sequence import PurePathSequence
+
+
+class PathSequence(PurePathSequence[PathT_co], BasePathSequence[PathT_co]):
+    """A sequence of Path objects.
+
+    Raises:
+        NotASequenceError: When the given path does not represent a sequence,
+            but a regular path.
+        ParseError: When the given path is not a valid path sequence.
+    """

pathseq/_pure_path_sequence.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from decimal import Decimal
+
+from typing_extensions import (
+    Self,  # PY311
+)
+
+from ._ast import PaddedRange, ParsedSequence, Ranges
+from ._base import BasePurePathSequence, PathT_co
+from ._file_num_seq import FileNumSequence
+from ._parse_path_sequence import parse_path_sequence
+
+
+class PurePathSequence(BasePurePathSequence[PathT_co]):
+    """A sequence of PurePath objects.
+
+    Raises:
+        NotASequenceError: When the given path does not represent a sequence,
+            but a regular path.
+        ParseError: When the given path is not a valid path sequence.
+    """
+
+    _parsed: ParsedSequence
+
+    def _parse(self, name: str) -> ParsedSequence:
+        return parse_path_sequence(name)
+
+    @property
+    def parsed(self) -> ParsedSequence:
+        """The parsed sequence string, as a tree of objects."""
+        return self._parsed
+
+    def with_file_num_seqs(
+        self, *seqs: FileNumSequence[int] | FileNumSequence[Decimal]
+    ) -> Self:
+        """Return a new sequence with the file number sequences changed.
+
+        Raises:
+            TypeError: If the given number of file number sequences does not match
+                the sequence's number of file number sequences.
+        """
+        if len(seqs) != len(self._parsed.ranges.ranges):
+            raise TypeError(
+                f"Need {len(self._parsed.ranges.ranges)} sequences, but got {len(seqs)}"
+            )
+
+        new_ranges = tuple(
+            PaddedRange(seq, range_.pad_format)
+            for seq, range_ in zip(seqs, self._parsed.ranges.ranges)
+        )
+        new = self._parsed.__class__(
+            self._parsed.stem,
+            self._parsed.prefix,
+            Ranges(new_ranges, self._parsed.ranges.inter_ranges),
+            self._parsed.suffixes,
+        )
+        return self.__class__(self._path.with_name(str(new)))

pathseq-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.3
+Name: pathseq
+Version: 0.1.0
+Summary: A pathlib-like library for working with file sequences.
+Author: Ashley Whetter
+Author-email: Ashley Whetter <ashley@awhetter.co.uk>
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Plugins
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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
+Description-Content-Type: text/x-rst
+
+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 file sequences.
+
+TODO: Note special features
+
+* Multi-dimension ranges (eg animated udims)
+* pathlib-first API
+* Support for UDIM tokens
+* Sequence compression?
+
+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 through pip:
+
+.. code-block:: bash
+
+    pip install pathseq
+
+Usage
+~~~~~
+
+TODO
+
+For more detailed usage, see the documentation:
+https://pathseq.readthedocs.io/en/latest/
+
+
+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 `black <https://github.com/python/black>`_.
+
+You can check your formatting using black's check mode:
+
+.. code-block:: bash
+
+    tox -e format
+
+You can also get black to format your changes for you:
+
+.. code-block:: bash
+
+    tox -e format -- src/ tests/
+
+
+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.dist-info/RECORD

@@ -0,0 +1,24 @@
+pathseq/__init__.py,sha256=Vfq5BvdPoY0rpQ_JLgGa6HEn69RmlMvBAbMAIfPpOPU,1121
+pathseq/_arithmetic_sequence.py,sha256=9FiiHMRHPiSVuKh1IWOkHhapiJoeFDl6LKr15p_t790,4630
+pathseq/_ast/__init__.py,sha256=vzv_VxfY8HFmKuVbPhzVrZ3Ii1DVskSlo7LhIHxtdcY,447
+pathseq/_ast/_base.py,sha256=rDgCUF8m4RUBdYU7Q5C5r6SDWHzgC6e1yf3-dUSyN50,8241
+pathseq/_ast/_formatter.py,sha256=xy6UKTZ8Nx2DAlzoe9VQzqAMskugDYNoWSD2AKVgU-A,1146
+pathseq/_ast/_loose_type.py,sha256=yg0T1Xw-KWALTqmx7ZrHvw9RCR7cD2sI8A_9ek_HeWE,7574
+pathseq/_ast/_type.py,sha256=VqIXf1Au-RMXrmCyDu5MofjCI1UPEydpPJbB4aQhR1A,1958
+pathseq/_base.py,sha256=EOcxeb3Wv4v_DKXtkiFysv1eyKvO8VKke-9MDWhJwJM,17096
+pathseq/_decimal_range.py,sha256=T6eqqVzRe5JfvnraO5UzqslGKke-64T2714Q08boyZM,5138
+pathseq/_error.py,sha256=MNK5kazk3PsuE6hs9Hpcv9wnYqZZIqoIMuzj9IErUYw,2644
+pathseq/_file_num_seq.py,sha256=VSqYAX4-tIJn3h5AD038_xpAP31Oj3ocoZfch-tClTY,7293
+pathseq/_formatter.py,sha256=Sevv_B-AsOSbx0D4oYq-edgHQEySLpMoyZ94CK5ZMOY,2569
+pathseq/_from_disk.py,sha256=iUqK3ma1m9vhIUso2vnLLpAa9tF_eQXYOZL4ch7oewU,2445
+pathseq/_loose_path_sequence.py,sha256=0YoJM5H7nXO0zFFK09cCx3GYBvDlOcwk8VZLUaTqpxk,467
+pathseq/_loose_pure_path_sequence.py,sha256=cc4dfStsCqtLrvJ40RuNQRO5OjUQLN2r-QkB581_0lc,4196
+pathseq/_parse_file_num_seq.py,sha256=6Sd__7SEzjQaxXvVXj-0Yad8NsElHl7JzQukYpvS-KA,2102
+pathseq/_parse_loose_path_sequence.py,sha256=8_v05ty-gn4S8TD0djduD1Sj7JPVkw9SNKBeLwEx_sI,17539
+pathseq/_parse_path_sequence.py,sha256=FumrJ02XOpjfm_UMVEi786E3ZkWDXu1PhqW1qrfl55M,9957
+pathseq/_path_sequence.py,sha256=glss3zoC3lMTxGrPIGQXputLOG65e-XSFM50BwhdpXk,446
+pathseq/_pure_path_sequence.py,sha256=3-MgYD4peH-uNpm7xkTdLxYP1Kkz9ERiU4DRy9S32dA,1869
+pathseq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pathseq-0.1.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+pathseq-0.1.0.dist-info/METADATA,sha256=8XaFeU9rKHVPkgtdpW2_BvPG-s7M5uX4pASwe0zbIa8,3421
+pathseq-0.1.0.dist-info/RECORD,,

pathseq-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any