pathseq 0.1.0__py3-none-any.whl

pathseq/__init__.py

@@ -0,0 +1,44 @@
+"""A pathlib-first library for working with file sequences."""
+
+from ._ast import (
+    FileNumT,
+    PaddedRange,
+    ParsedLooseSequence,
+    ParsedSequence,
+    Ranges,
+    RangesEndName,
+    RangesInName,
+    RangesStartName,
+)
+from ._base import BasePathSequence, BasePurePathSequence, PathT_co, PurePathT_co
+from ._error import IncompleteDimensionError, NotASequenceError, ParseError
+from ._file_num_seq import FileNumSequence
+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"
+
+__all__ = (
+    "BasePathSequence",
+    "BasePurePathSequence",
+    "FileNumSequence",
+    "FileNumT",
+    "IncompleteDimensionError",
+    "LoosePathSequence",
+    "LoosePurePathSequence",
+    "NotASequenceError",
+    "PaddedRange",
+    "ParsedLooseSequence",
+    "ParseError",
+    "ParsedSequence",
+    "PathSequence",
+    "PathT_co",
+    "PurePathSequence",
+    "PurePathT_co",
+    "Ranges",
+    "RangesEndName",
+    "RangesInName",
+    "RangesStartName",
+)

pathseq/_arithmetic_sequence.py

@@ -0,0 +1,154 @@
+from collections.abc import Iterator, Sequence
+import decimal
+from typing import overload, Protocol, TypeVar
+
+from typing_extensions import Self  # PY311
+
+from ._ast import FileNumT
+from ._decimal_range import DecimalRange
+
+
+FileNumT_cov = TypeVar("FileNumT_cov", covariant=True)
+
+
+class RangeProtocol(Protocol[FileNumT_cov]):
+    @property
+    def start(self) -> FileNumT_cov: ...
+    @property
+    def step(self) -> FileNumT_cov: ...
+
+    def __iter__(self) -> Iterator[FileNumT_cov]: ...
+
+    def __len__(self) -> int: ...
+
+
+def remove_exponent(d: decimal.Decimal) -> decimal.Decimal:
+    """Remove the exponent and trailing zeros from the given decimal."""
+    return d.quantize(decimal.Decimal(1)) if d == d.to_integral() else d.normalize()
+
+
+class ArithmeticSequence(Sequence[FileNumT]):
+    def __init__(
+        self, start: FileNumT, end: FileNumT | None = None, step: FileNumT | None = None
+    ) -> None:
+        end = end if end is not None else start
+        step = step if step is not None else start.__class__(1)
+
+        # Normalise to a positive step value
+        if step < 0:
+            start, end = (end, start)
+            step = -step
+
+        stop: FileNumT
+        if start < end:
+            # Normalise the end value to match the step
+            remainder = divmod(end - start, step)[1]
+            if remainder:
+                stop = end + (step - remainder)
+                end -= remainder
+            else:
+                stop = end + step
+        elif start == end:
+            # We treat the end as inclusive, ranges don't.
+            stop = end + step
+            # Normalise to a step of 1
+            step = start.__class__(1)
+        else:
+            stop = end
+
+        self._range: RangeProtocol[FileNumT]
+        self._end: FileNumT
+        if isinstance(start, int):
+            self._range = range(start, stop, step)
+            self._end = end
+        else:
+            self._range = DecimalRange(
+                remove_exponent(start), remove_exponent(stop), remove_exponent(step)
+            )
+            self._end = remove_exponent(end)
+
+    @property
+    def start(self) -> FileNumT:
+        return self._range.start
+
+    @property
+    def end(self) -> FileNumT:
+        return self._end
+
+    @property
+    def step(self) -> FileNumT:
+        return self._range.step
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ArithmeticSequence):
+            return NotImplemented
+
+        return (
+            isinstance(self.start, other.start.__class__)
+            and self.start == other.start
+            and self.end == other.end
+            and self.step == other.step
+        )
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.start, self.end, self.step))
+
+    def __contains__(self, item: object) -> bool:
+        return any(item == x for x in self._range)
+
+    def __iter__(self) -> Iterator[FileNumT]:
+        return iter(self._range)
+
+    def __len__(self) -> int:
+        return len(self._range)
+
+    def __str__(self) -> str:
+        if len(self) == 1:
+            return str(self.start)
+
+        result = f"{self.start}-{self.end}"
+        if self.step != 1:
+            result += f"x{self.step}"
+        elif len(self) == 2:
+            return ",".join(str(x) for x in self)
+
+        return result
+
+    def __repr__(self) -> str:
+        if self.step == 1:
+            return f"{self.__class__.__name__}({self.start}, {self.end})"
+
+        return f"{self.__class__.__name__}({self.start}, {self.end}, {self.step})"
+
+    @overload
+    def __getitem__(self, index: int) -> FileNumT: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> Self: ...
+
+    def __getitem__(self, index: int | slice) -> FileNumT | Self:
+        if isinstance(index, slice):
+            start_i, stop_i, step = index.indices(len(self))
+            if step > 0:
+                if start_i >= stop_i:
+                    raise IndexError("slice creates an empty arithemtic sequence")
+            else:
+                if start_i <= stop_i:
+                    raise IndexError("slice creates an empty arithemtic sequence")
+
+            start = self[index.start]
+            try:
+                stop = self[index.stop + 1]
+            except IndexError:
+                stop = self.end
+
+            return self.__class__(start, stop, self.step * index.step)
+
+        if index < 0:
+            index += len(self)
+            if index < 0:
+                raise IndexError("index out of range")
+        elif index >= len(self):
+            raise IndexError("index out of range")
+
+        return self._range.start + index * self._range.step

pathseq/_ast/__init__.py

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

pathseq/_ast/_base.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+import dataclasses
+from dataclasses import dataclass
+import decimal
+from decimal import Decimal
+import itertools
+import typing
+from typing import Any, Generic, TypeAlias, TypeGuard, TypeVar, Union
+
+if typing.TYPE_CHECKING:
+    from .._file_num_seq import FileNumSequence
+
+FileNumT = TypeVar("FileNumT", int, decimal.Decimal)
+FileNum: TypeAlias = Union[int, decimal.Decimal]
+
+
+def non_recursive_asdict(datacls: Any) -> dict[str, Any]:
+    """Like :func:`dataclasses.asdict` but does not recurse into attributes."""
+    return {
+        field.name: getattr(datacls, field.name)
+        for field in dataclasses.fields(datacls)
+    }
+
+
+# TODO: Replace with formatter usage
+def stringify_parsed_sequence(seq: Any) -> str:
+    result = ""
+    for field in dataclasses.fields(seq):
+        if field.name == "ranges":
+            ranges = (str(x) for x in seq.ranges.ranges)
+            # There's one more range than inter-range strings, so add an extra.
+            inter_ranges = itertools.chain(seq.ranges.inter_ranges, ("",))
+            result += "".join(itertools.chain.from_iterable(zip(ranges, inter_ranges)))
+            continue
+        elif field.name == "inter_ranges":
+            continue
+
+        value = getattr(seq, field.name)
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                result += str(item)
+        else:
+            result += value
+
+    return result
+
+
+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."
+    )
+
+
+@dataclass(frozen=True)
+class PaddedRange(Generic[FileNumT]):
+    file_nums: FileNumSequence[FileNumT]
+    """The file numbers of each file in the sequence."""
+    pad_format: str
+    """The definition of how a file number is formatted in each file's name in the sequence."""
+
+    def __str__(self) -> str:
+        return str(self.file_nums) + self.pad_format
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self})"
+
+    def format(self, number: int | Decimal) -> str:
+        """Format the given number using the range's padding rules."""
+        if self.pad_format == "<UVTILE>":
+            # udim = 1000+(v*10)+(u+1)
+            u = (number - 1) % 10
+            v = (number - 1000 - u - 1) // 10
+            return f"u{u + 1}_v{v + 1}"
+
+        pad_format = self.pad_format
+        if self.pad_format == "<UDIM>":
+            pad_format = "####"
+
+        if "." in pad_format:
+            head, tail = pad_format.split(".", 1)
+            return pad(number, len(head), len(tail))
+
+        return pad(number, len(pad_format))
+
+    @staticmethod
+    def has_subsamples(
+        range_: PaddedRange[int] | PaddedRange[decimal.Decimal],
+    ) -> TypeGuard[PaddedRange[decimal.Decimal]]:
+        """Check whether this file number sequence contains any decimal numbers."""
+        return range_.file_nums.has_subsamples(range_.file_nums)
+
+
+@dataclass(frozen=True)
+class Ranges:
+    ranges: tuple[PaddedRange[int] | PaddedRange[Decimal], ...]
+    """Each :ref:`range specifier <format-simple-ranges>` in the sequence."""
+    inter_ranges: tuple[str, ...]
+    """The inter-range separators between each range in the sequence.
+
+    The number of inter-range separators is guaranteed to be ``1 - len(self.ranges)``.
+    """
+
+    def __post_init__(self) -> None:
+        if len(self.inter_ranges) != len(self.ranges) - 1:
+            raise ValueError(
+                "The number of inter-range strings given does not match"
+                " the number of range strings minus one."
+            )
+
+    def __str__(self) -> str:
+        return splice_strings_onto_ranges(
+            (str(range_) for range_ in self.ranges),
+            self.inter_ranges,
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self})"
+
+
+# The MIT License (MIT)
+
+# Original work Copyright (c) 2015 Matthew Chambers
+# Modified work Copyright 2015 Justin Israel
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+# TODO: Validate that this is doing what we want
+
+
+def quantize(
+    number: decimal.Decimal,
+    decimal_places: int,
+    rounding: str = decimal.ROUND_HALF_EVEN,
+) -> decimal.Decimal:
+    """Round a decimal value to given number of decimal places
+
+    Args:
+        number: Decimal number to round
+        decimal_places: Number of decimal places in return value
+        rounding: decimal.Decimal rounding mode. See rounding argument of
+            https://docs.python.org/2/library/decimal.html#decimal.Context
+
+    Returns:
+        decimal.Decimal:
+    """
+    quantize_exponent = decimal.Decimal(1).scaleb(-decimal_places)
+    nq = number.quantize(quantize_exponent, rounding=rounding)
+    if nq.is_zero():
+        return nq.copy_abs()
+    return nq
+
+
+def pad(
+    number: int | Decimal, width: int = 0, decimal_places: int | None = None
+) -> str:
+    """Return the zero-padded string of a given number.
+
+    Args:
+        number: the number to pad
+        width: width for zero padding the integral component
+        decimal_places: number of decimal places to use in frame range
+    """
+
+    # Make the common case fast. Truncate to integer value as USD does.
+    # https://graphics.pixar.com/usd/docs/api/_usd__page__value_clips.html
+    # See _DeriveClipTimeString for formatting of templateAssetPath
+    # https://github.com/PixarAnimationStudios/USD/blob/release/pxr/usd/usd/clipSetDefinition.cpp
+    if decimal_places == 0:
+        try:
+            number = round(number) or 0
+        except TypeError:
+            pass
+        return str(number).partition(".")[0].zfill(width)
+
+    # USD ultimately uses vsnprintf to format floats for templateAssetPath:
+    # _DeriveClipTimeString -> TfStringPrintf -> ArchVStringPrintf -> ArchVsnprintf -> vsnprintf
+    # Since glibc 2.17 the printf family of functions rounds floats using the
+    # current IEEE rounding mode, by default bankers' rounding (FE_TONEAREST).
+    # See https://sourceware.org/bugzilla/show_bug.cgi?id=5044 and man(3) fegetround
+    # Also https://www.exploringbinary.com/inconsistent-rounding-of-printed-floating-point-numbers/
+    if decimal_places is not None:
+        if not isinstance(number, decimal.Decimal):
+            number = decimal.Decimal(number)
+        number = quantize(number, decimal_places, decimal.ROUND_HALF_EVEN)
+
+    parts = str(number).split(".", 1)
+    parts[0] = parts[0].zfill(width)
+    return ".".join(parts)

pathseq/_ast/_formatter.py

@@ -0,0 +1,38 @@
+import dataclasses
+from decimal import Decimal
+
+from ._base import PaddedRange, Ranges, splice_strings_onto_ranges
+from ._loose_type import ParsedLooseSequence
+from ._type import ParsedSequence
+
+
+class Formatter:
+    def stem(self, stem: str) -> str:
+        return stem
+
+    def prefix(self, prefix: str) -> str:
+        return prefix
+
+    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 splice_strings_onto_ranges(
+            (self.range(range_) for range_ in ranges.ranges),
+            (self.inter_range(inter_range) for inter_range in ranges.inter_ranges),
+        )
+
+    def postfix(self, postfix: str) -> str:
+        return postfix
+
+    def suffixes(self, suffixes: tuple[str, ...]) -> str:
+        return "".join(suffixes)
+
+    def format(self, seq: ParsedSequence | ParsedLooseSequence) -> str:
+        return "".join(
+            getattr(self, field.name)(getattr(seq, field.name))
+            for field in dataclasses.fields(seq)
+        )