pathseq 0.1.0__py3-none-any.whl

pathseq/_error.py

@@ -0,0 +1,72 @@
+class ParseError(ValueError):
+    """Raised when parsing a sequence string fails.
+
+    Args:
+        seq: The sequence string that failed parsing.
+        column: The index of the character of the part of the string that failed parsing.
+        end: The index of the last character of the part of the string that failed parsing.
+        reason: A human readable explanation of why parsing failed.
+    """
+
+    seq: str
+    """The sequence string that failed parsing."""
+    column: int
+    """The index of the character of the part of the string that failed parsing."""
+    end: int
+    """The index of the last character of the part of the string that failed parsing."""
+
+    def __init__(
+        self, seq: str, column: int, end_column: int = -1, reason: str | None = None
+    ):
+        self.seq = seq
+        self.column = column
+        self.end = end_column if end_column >= 1 else (column + 1)
+
+        lines = []
+        message = "Invalid sequence"
+        if reason:
+            message = f"{message}: {reason}"
+        lines.append(message)
+
+        prefix = "  "
+        lines.append(f"{prefix}{seq}")
+        if column >= 0:
+            lines.append(f"{prefix}{' ' * column}{'^' * (self.end - column)}")
+            message = "\n".join(lines)
+
+        super().__init__(message)
+
+
+class NotASequenceError(ParseError):
+    """Raised when parsing a string that does not represent a sequence, but a regular path.
+
+    In other words, the given sequence string has no :ref:`range <format-simple-range>`
+    present.
+    """
+
+    def __init__(self, seq: str) -> None:
+        super().__init__(seq, 0, len(seq) - 1, reason="No range string is present")
+
+
+class IncompleteDimensionError(Exception):
+    """A multi-dimension sequence does not contain a consistent number of files across a dimension.
+
+    Example:
+        .. code-block:: pycon
+
+            >>> tmp = getfixture('tmp_path')
+            >>> seq = tmp / PathSequence('file.1001,1002<UDIM>_1-3#.exr')
+            >>> for path in seq:
+            ...     path.touch()
+            ...
+            >>> seq.with_existing_paths()
+            PathSequence('.../file.1001,1002<UDIM>_1-3#.exr')
+            >>> (tmp / 'file.1002_3.exr').unlink()
+            >>> seq.with_existing_paths()
+            Traceback (most recent call last):
+            ...
+            pathseq._error.IncompleteDimensionError: Sequence '.../file.1001,1002<UDIM>_1-3#.exr' contains an inconsistent number of files across one or more dimensions.
+            >>> (tmp / 'file.1001_3.exr').unlink()
+            >>> seq.with_existing_paths()
+            PathSequence('.../file.1001,1002<UDIM>_1,2#.exr')
+    """

pathseq/_file_num_seq.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+import decimal
+import itertools
+from typing import Generic, overload, TypeGuard
+
+from typing_extensions import (
+    Self,  # PY311
+)
+
+from ._arithmetic_sequence import ArithmeticSequence
+from ._ast import FileNumT
+from ._parse_file_num_seq import parse_file_num_seq
+
+
+class FileNumSequenceIterator(Generic[FileNumT]):
+    def __init__(self, ranges: tuple[ArithmeticSequence[FileNumT], ...]):
+        self._ranges_iter: Iterator[ArithmeticSequence[FileNumT]] = iter(ranges)
+        self._range_iter: Iterator[FileNumT] = iter(())
+
+    def __iter__(self) -> Self:
+        return self
+
+    def __next__(self) -> FileNumT:
+        try:
+            return next(self._range_iter)
+        except StopIteration:
+            range_ = next(self._ranges_iter)
+            self._range_iter = iter(range_)
+            return next(self._range_iter)
+
+
+def _seqs_from_nums(
+    numbers: Iterable[FileNumT],
+) -> Iterable[ArithmeticSequence[FileNumT]]:
+    if not numbers:
+        return []
+
+    numbers = iter(numbers)
+    seqs: list[tuple[FileNumT, FileNumT, FileNumT | None]] = []
+    start = next(numbers)
+    previous = start
+    step = None
+    current_step = None
+
+    for current in numbers:
+        if current == previous:
+            continue
+
+        current_step = current - previous
+
+        if step is None:
+            step = current_step
+
+        if step == current_step:
+            # Continue contiguous range
+            pass
+        else:
+            # Close off the current range
+            seqs.append((start, previous, step))
+            start = current
+            step = None
+
+        previous = current
+
+    # Handle the last or only range
+    if step is not None or current_step is None:
+        seqs.append((start, previous, step))
+
+    return [ArithmeticSequence(*seq) for seq in seqs]
+
+
+def _consolidate_ranges(
+    ranges: Iterable[ArithmeticSequence[FileNumT]],
+) -> tuple[ArithmeticSequence[FileNumT], ...]:
+    filtered = (r for r in ranges if len(r))
+    try:
+        new_ranges = [next(filtered)]
+    except StopIteration:
+        return ()
+
+    for range_b in filtered:
+        range_a = new_ranges[-1]
+        difference = range_b.start - range_a.end
+        if difference == range_a.step:
+            # Can we merge this entire range into the previous range?
+            if range_a.step == range_b.step:
+                new_ranges[-1] = range_a.__class__(
+                    range_a.start, range_b.end, range_a.step
+                )
+                continue
+
+            # Otherwise we can move at most one item to the previous range
+            # without changing the order of file numbers.
+            new_ranges[-1] = range_a.__class__(
+                range_a.start, range_b.start, range_a.step
+            )
+            range_b = range_b.__class__(
+                range_b.start + range_b.step, range_b.end, range_b.step
+            )
+            if not range_b:
+                continue
+        # Consolidate neighbouring numbers into a range in the hope that
+        # another lone number is next and can be consolidated into the range as well.
+        elif len(range_a) == 1 and len(range_b) == 1:
+            new_ranges[-1] = range_a.__class__(range_a.start, range_b.start, difference)
+            continue
+
+        new_ranges.append(range_b)
+
+    return tuple(new_ranges)
+
+
+class FileNumSequence(Sequence[FileNumT]):
+    """A sequence of file numbers.
+
+    Warning:
+        The constructor is not considered public.
+        Instead, use the :meth:`~FileNumSequence.from_str`
+        and :meth:`~FileNumSequence.from_file_nums` class methods.
+    """
+
+    def __init__(self, ranges: Iterable[ArithmeticSequence[FileNumT]]) -> None:
+        self._ranges: tuple[ArithmeticSequence[FileNumT], ...] = _consolidate_ranges(
+            ranges
+        )
+
+    @classmethod
+    def from_str(
+        cls, seq: str
+    ) -> FileNumSequence[int] | FileNumSequence[decimal.Decimal]:
+        """Parse a range string in a file number sequence.
+
+        Args:
+            seq: The range string to parse (eg '1001-1005,1010-1015').
+
+        Returns:
+            The resulting file number sequence.
+        """
+        return cls(parse_file_num_seq(seq))  # type: ignore[arg-type]
+
+    @classmethod
+    def from_file_nums(cls, file_nums: Iterable[FileNumT]) -> FileNumSequence[FileNumT]:
+        """Create a file number sequence from an iterable of file numbers.
+
+        The given numbers are put into the sequence in the order they are provided.
+
+        Args:
+            file_nums: The file numbers to turn into a sequence.
+
+        Returns:
+            The resulting file number sequence.
+        """
+        return cls(_seqs_from_nums(file_nums))
+
+    def __contains__(self, item: object) -> bool:
+        """Return True if the given item is a file number in this sequence."""
+        if not self._ranges:
+            return False
+
+        return any(item in rng for rng in self._ranges)
+
+    def __iter__(self) -> Iterator[FileNumT]:
+        """Iterate over the file numbers in this sequence.
+
+        Yields:
+            Each file number in the sequence.
+        """
+        return FileNumSequenceIterator(self._ranges)
+
+    def __len__(self) -> int:
+        """Get the number of file numbers in this sequence."""
+        return sum(len(rng) for rng in self._ranges)
+
+    def __eq__(self, other: object) -> bool:
+        """Check for equality with another object.
+
+        File number sequences are considered equal when they contain
+        the same items in the same order.
+        """
+        if not isinstance(other, FileNumSequence):
+            return NotImplemented
+
+        return self._ranges == other._ranges
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._ranges))
+
+    @overload
+    def __getitem__(self, index: int) -> FileNumT: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> Sequence[FileNumT]: ...
+
+    def __getitem__(self, index: int | slice) -> FileNumT | Sequence[FileNumT]:
+        """Return one or more file numbers from this sequence.
+
+        Note:
+            Negative slice steps are not supported at this time.
+
+        Returns:
+            PurePath: When indexed with an integer.
+            Sequence: An immutable sequence of file numbers from this sequence
+                when indexed with a :class:`slice`.
+        """
+        if isinstance(index, slice):
+            return tuple(itertools.islice(self, *index.indices(len(self))))
+
+        for rng in self._ranges:
+            range_len = len(rng)
+            if index < range_len:
+                return rng[index]
+            index -= range_len
+        else:
+            raise IndexError(index)
+
+    def __str__(self) -> str:
+        return ",".join(str(rng) for rng in self._ranges)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self})"
+
+    @staticmethod
+    def has_subsamples(
+        file_num_seq: FileNumSequence[int] | FileNumSequence[decimal.Decimal],
+    ) -> TypeGuard[FileNumSequence[decimal.Decimal]]:
+        """Check whether this file number sequence contains any decimal numbers."""
+        if not file_num_seq:
+            return False
+
+        return isinstance(next(iter(file_num_seq)), decimal.Decimal)

pathseq/_formatter.py

@@ -0,0 +1,85 @@
+from decimal import Decimal
+import re
+
+from ._ast import Formatter, PaddedRange
+
+
+class GlobFormatter(Formatter):
+    """Format to a glob pattern to match paths in the given sequence."""
+
+    def __init__(self) -> None:
+        self._ignore_next_range = False
+
+    def range(self, range_: PaddedRange[int] | PaddedRange[Decimal]) -> str:
+        if self._ignore_next_range:
+            self._ignore_next_range = False
+            return ""
+
+        return "*"
+
+    def inter_range(self, inter_range: str) -> str:
+        if not inter_range:
+            self._ignore_next_range = True
+
+        return inter_range
+
+
+class FileNumberFormatter(Formatter):
+    def __init__(self, *numbers: int | Decimal) -> None:
+        self._numbers = iter(numbers)
+
+    def range(self, range_: PaddedRange[int] | PaddedRange[Decimal]) -> str:
+        try:
+            number = next(self._numbers)
+        except StopIteration:
+            raise TypeError(
+                "Insufficient number of file numbers given to format sequence"
+            )
+
+        return range_.format(number)
+
+
+class RegexFormatter(Formatter):
+    """Format to a regex pattern to match paths in the given sequence."""
+
+    def __init__(self) -> None:
+        self._i = 0
+
+    def stem(self, stem: str) -> str:
+        return re.escape(super().stem(stem))
+
+    def prefix(self, prefix: str) -> str:
+        return re.escape(super().prefix(prefix))
+
+    def _range(self, range_: PaddedRange[int] | PaddedRange[Decimal]) -> str:
+        if range_.pad_format == "<UVTILE>":
+            return r"u\d+_v\d+"
+
+        pad_format = range_.pad_format
+        if range_.pad_format == "<UDIM>":
+            pad_format = "####"
+
+        if "." in pad_format:
+            head, tail = pad_format.split(".", 1)
+            tail_re = r"\.[0-9]*" + r"[0-9]" * len(tail)
+        else:
+            head = pad_format
+            tail_re = ""
+            if range_.has_subsamples(range_):
+                tail_re = r"(\.[0-9]+)?"
+
+        positive_re = r"([1-9][0-9]*)?" + r"[0-9]" * len(head)
+        negative_re = r"-([1-9][0-9]*)?" + r"[0-9]" * (len(head) - 1)
+
+        return f"({positive_re}|{negative_re}){tail_re}"
+
+    def range(self, range_: PaddedRange[int] | PaddedRange[Decimal]) -> str:
+        result = f"(?P<range{self._i}>{self._range(range_)})"
+        self._i += 1
+        return result
+
+    def inter_range(self, inter_range: str) -> str:
+        return re.escape(super().inter_range(inter_range))
+
+    def suffixes(self, suffixes: tuple[str, ...]) -> str:
+        return re.escape(super().suffixes(suffixes))

pathseq/_from_disk.py

@@ -0,0 +1,73 @@
+from collections.abc import Iterator
+from decimal import Decimal
+import functools
+import operator
+import pathlib
+import re
+
+from ._ast import (
+    RangesStartName,
+    RangesInName,
+    RangesEndName,
+    ParsedSequence,
+)
+from ._error import IncompleteDimensionError
+from ._file_num_seq import FileNumSequence
+from ._formatter import GlobFormatter, RegexFormatter
+
+
+def find_on_disk(
+    path: pathlib.Path,
+    parsed: ParsedSequence | RangesStartName | RangesInName | RangesEndName,
+) -> Iterator[FileNumSequence[int] | FileNumSequence[Decimal]]:
+    """Find the ranges of files that exist on disk for the given path.
+
+    Each file number sequence in the path sequence will be ordered numerically.
+
+    Raises:
+        IncompleteDimensionError: When one or more dimensions in
+        a multi-dimension sequence does not have a consistent number of
+        files in each other dimension.
+    """
+    num_ranges = len(parsed.ranges.ranges)
+    file_str_sets: list[set[str]] = [set() for _ in range(num_ranges)]
+    glob_pattern = GlobFormatter().format(parsed)
+    paths = path.parent.glob(glob_pattern)
+    pattern = re.compile(RegexFormatter().format(parsed))
+    num_paths = 0
+    for found in paths:
+        match = pattern.fullmatch(str(found.name))
+        if not match:
+            continue
+
+        file_nums = []
+        for i in range(num_ranges):
+            group_name = f"range{i}"
+            group = match.group(group_name)
+            file_nums.append(group)
+
+        if len(file_nums) != num_ranges:
+            continue
+
+        num_paths += 1
+        for file_num, file_str_set in zip(file_nums, file_str_sets):
+            file_str_set.add(file_num)
+
+    expected = functools.reduce(operator.mul, (len(nums) for nums in file_str_sets), 1)
+    if num_paths != expected:
+        raise IncompleteDimensionError(
+            f"Sequence '{path}' contains an inconsistent number of files across one or more dimensions."
+        )
+
+    for file_str_set in file_str_sets:
+        file_num_seq: FileNumSequence[int] | FileNumSequence[Decimal]
+        if any("." in file_str for file_str in file_str_set):
+            file_num_seq = FileNumSequence.from_file_nums(
+                sorted(Decimal(file_str) for file_str in file_str_set)
+            )
+        else:
+            file_num_seq = FileNumSequence.from_file_nums(
+                sorted(int(file_str) for file_str in file_str_set)
+            )
+
+        yield file_num_seq

pathseq/_loose_path_sequence.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ._base import BasePathSequence, PathT_co
+from ._loose_pure_path_sequence import LoosePurePathSequence
+
+
+class LoosePathSequence(LoosePurePathSequence[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/_loose_pure_path_sequence.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from decimal import Decimal
+
+from typing_extensions import (
+    Self,  # PY311
+)
+
+from ._ast import PaddedRange, ParsedLooseSequence, Ranges
+from ._base import BasePurePathSequence, PurePathT_co
+from ._error import ParseError
+from ._file_num_seq import FileNumSequence
+from ._parse_loose_path_sequence import parse_path_sequence
+
+
+class LoosePurePathSequence(BasePurePathSequence[PurePathT_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: ParsedLooseSequence
+
+    def _parse(self, name: str) -> ParsedLooseSequence:
+        return parse_path_sequence(name)
+
+    @property
+    def parsed(self) -> ParsedLooseSequence:
+        """The parsed sequence string, as a tree of objects."""
+        return self._parsed
+
+    @property
+    def suffix(self) -> str:
+        """The file extension of the paths in the sequence.
+
+        If there is no suffix, this will be the empty string.
+
+        .. code-block:: pycon
+
+            >>> LoosePurePathSequence('file1-3###').suffix
+            ''
+        """
+        return super().suffix
+
+    def with_suffix(self, suffix: str) -> Self:
+        """Return a new path sequence with the suffix changed.
+
+        If the given suffix is the empty string, the existing suffix will be removed.
+        But if the path sequence has only one suffix,
+        then a :exc:`ValueError` will be raised because removing the suffix will result in
+        an invalid path sequence.
+
+        Args:
+            suffix: The new suffix to replace the existing suffix with.
+
+        Raises:
+            ValueError: If the given suffix would result in an invalid path sequence.
+        """
+        parsed = self._parsed.with_suffix(suffix)
+        try:
+            return self.with_segments(self._path.parent, str(parsed))
+        except ParseError:
+            raise ValueError(
+                f"Cannot use suffix '{suffix}' because"
+                " it would result in an invalid path sequence"
+            )
+
+    @property
+    def stem(self) -> str:
+        """The final path component, without any prefix, ranges, postfix, or suffixes.
+
+        .. code-block:: pycon
+
+            >>> LoosePurePathSequence('/path/to/images.1-3####.exr').stem
+            'images'
+            >>> LoosePurePathSequence('/path/to/1-3####_images.exr').stem
+            'images'
+            >>> LoosePurePathSequence('/path/to/images.exr.1-3####').stem
+            'images'
+
+        Unlike :attr:`pathlib.PurePath.stem`, this will never contain a suffix
+        if the paths have multiple suffixes:
+
+        .. code-block:: pycon
+
+            >>> LoosePurePathSequence('/path/to/images.tar.gz.1-3####').stem
+            'images'
+
+        If the paths have no stem, then the empty string is returned:
+
+        .. code-block:: pycon
+
+            >>> LoosePurePathSequence('1-3#.tar.gz').stem
+            ''
+        """
+        return super().stem
+
+    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__(
+            stem=self._parsed.stem,
+            prefix=self._parsed.prefix,  # type: ignore[arg-type]
+            ranges=Ranges(new_ranges, self._parsed.ranges.inter_ranges),
+            postfix=self._parsed.postfix,  # type: ignore[arg-type]
+            suffixes=self._parsed.suffixes,
+        )
+        return self.__class__(self._path.with_name(str(new)))

pathseq/_parse_file_num_seq.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from decimal import Decimal as D
+from typing import TypeAlias, TypeVar, Union
+
+import lark
+
+from ._arithmetic_sequence import ArithmeticSequence
+from ._error import ParseError
+
+_GRAMMAR = r"""
+    start: ranges
+
+    ranges: range ("," range)*
+
+    range: FILE_NUM ["-" FILE_NUM ["x" NUM]]
+
+    FILE_NUM: "-"? NUM
+    NUM: /
+        (0|[1-9][0-9]*)       # the digits
+        (\.0|\.[0-9]*[1-9])?  # the subsamples
+    /x
+"""
+_PARSER = lark.Lark(_GRAMMAR, parser="lalr")
+_SeqArgsT: TypeAlias = Union[tuple[str], tuple[str, str], tuple[str, str, str]]
+T = TypeVar("T")
+
+
+@lark.v_args(inline=True)
+class _RangeReducer(
+    lark.Transformer[
+        lark.Token, list[ArithmeticSequence[int]] | list[ArithmeticSequence[D]]
+    ]
+):
+    def start(self, seq: T) -> T:
+        return seq
+
+    def ranges(
+        self, range_: _SeqArgsT, *ranges: _SeqArgsT
+    ) -> list[ArithmeticSequence[int]] | list[ArithmeticSequence[D]]:
+        if any("." in arg for arg in range_) or any(
+            "." in arg for r in ranges for arg in r
+        ):
+            return [
+                ArithmeticSequence(*tuple(D(arg) for arg in range_)),
+                *(ArithmeticSequence(*tuple(D(arg) for arg in r)) for r in ranges),
+            ]
+
+        return [
+            ArithmeticSequence(*tuple(int(arg) for arg in range_)),
+            *(ArithmeticSequence(*tuple(int(arg) for arg in r)) for r in ranges),
+        ]
+
+    def range(self, start: str, end: str | None, step: str | None) -> _SeqArgsT:
+        assert step is None or end is not None, "Parsed an end but no step"
+
+        args: _SeqArgsT = (start,)
+        if end is not None:
+            args = (start, end)
+            if step is not None:
+                args = (start, end, step)
+
+        return args
+
+
+def parse_file_num_seq(
+    seq: str,
+) -> list[ArithmeticSequence[int]] | list[ArithmeticSequence[D]]:
+    if not seq:
+        return []
+
+    try:
+        ranges = _PARSER.parse(seq)
+    except lark.UnexpectedInput as exc:
+        raise ParseError(seq, exc.column)
+
+    return _RangeReducer().transform(ranges)