Revert "Can parse a single file path"

This reverts commit ce1fe93,
and includes a documented decision for this change.

Author: AWhetter

doc/source/api.rst

@@ -80,6 +80,10 @@ API Reference
       :show-inheritance:
       :members:
 
+   .. autoexception:: NotASequenceError
+      :show-inheritance:
+      :members:
+
    .. autoexception:: ParseError
       :show-inheritance:
       :members:

doc/source/decisions/002-directory-sequence-support.rst

@@ -3,7 +3,7 @@
 [ADR-002] Directory Sequence Support
 ====================================
 
-:bdg-success:`Accepted`
+:bdg-success:`Rejected`
 
 Context and Problem Statement
 -----------------------------
@@ -23,13 +23,6 @@ Supporting sequences of directories will complicate the API in the following way
   with directory sequences are used.
 
 
-Considered Options
-------------------
-
-* We will support directory sequences
-* We will not support directory sequences.
-
-
 Decision Outcome
 ----------------
 

doc/source/decisions/004-supporting-single-path-sequences.rst

@@ -0,0 +1,144 @@
+.. _adr-004:
+
+[ADR-004] Supporting Single Path Sequences
+==========================================
+
+:bdg-danger:`Rejected`
+
+Context and Problem Statement
+-----------------------------
+
+This proposal is to make the ranges in a sequence optional,
+such that a sequence with no ranges (i.e. a single file) is still considered a valid sequence.
+
+Use cases for this include:
+
+* Retrieving a sequence string from an unknown source,
+  and not knowing whether it will be a single file or a sequence.
+  For example, a user may have a sequence string stored in a database, and want to
+  use pathseq to loop over the files in that sequence. If the sequence string is for
+  a single file, they would still want to be able to use pathseq to loop over it.
+
+  Where this type of pattern has been seen before,
+  users have typically run the equivalent of ``.with_existing_files``
+  immediately after creating the sequence.
+
+Currently, a sequence with only empty ranges is considered to be empty.
+A single path sequence would have no ranges, and would be considered as having one file.
+These two definitions are somewhat in conflict,
+and so introducing single path sequences would erode the concept of a sequence.
+
+PathSeq defines a "stem" slightly differently to pathlib.
+In pathlib, the stem of a path is the final path component without its suffix.
+In PathSeq, the stem of a path is the final path component without the ranges and any suffixes.
+This difference is achievable because the ranges are an additional component
+that creates a clear separation between the stem from the suffixes.
+In single path sequences, there is no clear separation between the stem and suffixes,
+hence why pathlib behaves the way it does.
+pathlib puts the burden on users to parse the stem and suffixes themselves,
+and PathSeq would ideally do the same,
+else risk users reporting unintuitive/inconsistent parsing of suffixes
+(e.g. "file.tar.gz" having a stem of "file.tar" and suffixes of ".gz"
+instead of a stem of "file" and suffixes of ".tar.gz").
+
+.. note::
+
+   This is already an issue for loose path sequences
+   where the ranges exist at the start or end of the sequence string,
+   and therefore there is no separation between the stem and suffixes.
+   The loose format already warns users that ambiguity exists throughout
+   the API of ``LoosePathSequence``,
+   so the effect on loose path sequences is not considered significant.
+
+Supporting single path sequences does not significantly complicate the implementation.
+Wherever we support sequences of an unknown number of ranges
+we already support sequences with no ranges.
+
+
+Considered Options
+------------------
+
+* Change the signature of ``.with_existing_files`` from ``PathSequence`` to ``PathSequence | None``.
+
+  Supporting single path sequences would complicate the API in the following ways:
+
+  * Users would have to check the type of the return value before using it.
+    This applies even for those users that are always using a sequence with ranges.
+    Essentially, users end up needing to check whether the sequence has any ranges
+    or not before using ``.with_existing_files``.
+    So users may as well check this upon creation of the sequence,
+    and not have to worry about it for the rest of the sequence's lifetime.
+
+  * Proper use of ``.with_existing_files`` can be type checked.
+
+  * For users that aren't using type checking,
+    improper use of ``.with_existing_files`` could go unnoticed until
+    it is called on a single path sequence for which the file does not exist.
+
+  * The common use case would be written as:
+
+    .. code-block:: python
+
+       def do_something_with_sequence(seq: str):
+           files: Iterable[Path] = PathSequence(seq).with_existing_files() or [Path(seq)]
+           for file in files:
+               # do something with the file
+               ...
+
+* ``.with_existing_files`` will raise an error if it is called on a single file sequence,
+  for which the file does not exist.
+
+  * Proper use of ``.with_existing_files`` cannot be type checked.
+
+  * For users that aren't using type checking,
+    improper use of ``.with_existing_files`` could go unnoticed until
+    it is called on a single path sequence for which the file does not exist.
+
+  * The common use case would be written as:
+
+    .. code-block:: python
+
+       def do_something_with_sequence(seq: str):
+           files: Iterable[Path]
+           try:
+               files = PathSequence(seq).with_existing_files()
+           except FileNotFoundError:
+               files = [Path(seq)]
+
+           for file in files:
+               # do something with the file
+               ...
+
+* We will not support single path sequences.
+  and instead raise an error if a PathSequence is constructed with a single file sequence.
+
+  * Users will not have to worry about whether ``.with_existing_files`` can be used safely.
+    Checking is done upon creation of the sequence.
+
+  * The methods that construct an instance of ``BasePurePathSequence`` will
+    need to raise an error if the sequence string is for a single file.
+    Users already need to be aware of a ``ParseError`` being raised in these methods,
+    so this is not a significant change to the API.
+
+  * The common use case would be written as:
+
+    .. code-block:: python
+
+       def do_something_with_sequence(seq: str):
+           files: Iterable[Path]
+           try:
+               files = PathSequence(seq).with_existing_files()
+           except NotASequenceError:
+               files = [Path(seq)]
+
+           for file in files:
+               # do something with the file
+               ...
+
+
+Decision Outcome
+----------------
+
+We will not support single path sequences.
+A single file and a path sequence occasionally needs to be treated in differently,
+and it's best for users to be aware of this distinction when they create the sequence.

doc/source/user/format.rst

@@ -79,13 +79,13 @@ an inter-range separator.
 
 .. code-block:: text
 
-   /directory/ file . udim1001-1002<UDIM> _ 1001-1010# .tar.gz
-         ┌────┴────┼─┼────┼──────────────┼─┼───────────┼───────┴┐
-         │    ┌────┘ │    └────┐     ┌───┘ └───┐       │        │
-         │stem│prefix│pre-range|range│pre-range│ range │suffixes│
-         └────┴──────┼─────────┴─────┴─────────┴───────┼────────┘
-                     │              ranges             │
-                     └─────────────────────────────────┘
+   /directory/ file . 1001-1002<UDIM> _ 1001-1010# .tar.gz
+         ┌────┴────┼─┼───────────────┼─┼──────────┼───────┴┐
+         │    ┌────┘ │          ┌────┘ └────┐     │        │
+         │stem│prefix│   range  │inter-range│range│suffixes│
+         └────┴──────┼──────────┴───────────┴─────┼────────┘
+                     │           ranges           │
+                     └────────────────────────────┘
 
 
 .. _format-simple-stem:
@@ -463,6 +463,20 @@ a stem may or may not be present in the name of a loose path sequence.
       >>> LoosePathSequence('.tar.gz1-5#').stem
       '.tar'
 
+.. note::
+
+   For ranges that start or end the name of the sequence,
+   there is ambiguity in how to interpret the stem and suffixes.
+   Unlike :attr:`pathlib.PurePath.stem`, this will never contain a suffix
+   if the paths have multiple suffixes:
+
+   .. code-block:: pycon
+
+      >>> LoosePathSequence('file.tar.gz.1-5#').stem
+      'file'
+      >>> LoosePathSequence('1-5#file.tar.gz').stem
+      'file'
+
 
 .. _format-loose-prefix:
 

src/pathseq/__init__.py

@@ -11,7 +11,7 @@
     RangesStartName,
 )
 from ._base import BasePathSequence, BasePurePathSequence, PathT_co, PurePathT_co
-from ._error import IncompleteDimensionError, ParseError
+from ._error import IncompleteDimensionError, NotASequenceError, ParseError
 from ._file_num_seq import FileNumSequence, FileNumT
 from ._loose_path_sequence import LoosePathSequence
 from ._loose_pure_path_sequence import LoosePurePathSequence
@@ -29,6 +29,7 @@
     "IncompleteDimensionError",
     "LoosePathSequence",
     "LoosePurePathSequence",
+    "NotASequenceError",
     "PaddedRange",
     "ParsedLooseSequence",
     "ParseError",

src/pathseq/_ast/__init__.py

@@ -7,6 +7,7 @@
 )
 from ._ranges import PaddedRange, Ranges
 from ._type import ParsedSequence
+from ._util import non_recursive_asdict
 
 __all__ = [
     "Formatter",
@@ -17,4 +18,5 @@
     "RangesStartName",
     "RangesInName",
     "RangesEndName",
+    "non_recursive_asdict",
 ]

src/pathseq/_ast/_formatter.py

@@ -41,9 +41,6 @@ def _splice_strings_onto_ranges(
             except StopIteration:
                 return result
 
-    if not result:
-        return result
-
     raise TypeError(
         "The number of inter-range strings given does not match"
         " the number of range strings given minus one."

src/pathseq/_ast/_ranges.py

@@ -55,22 +55,15 @@ class Ranges:
     inter_ranges: tuple[str, ...]
     """The inter-range separators between each range in the sequence.
 
-    If there are ranges then
-    the number of inter-range separators is guaranteed to be ``1 - len(self.ranges)``.
+    The number of inter-range separators is guaranteed to be ``1 - len(self.ranges)``.
     """
 
     def __post_init__(self) -> None:
-        if self.ranges:
-            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."
-                )
-        else:
-            if self.inter_ranges:
-                raise ValueError(
-                    "There are no ranges but there are inter-range strings."
-                )
+        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 Formatter().ranges(self)

src/pathseq/_base.py

@@ -14,7 +14,7 @@
     Self,  # PY311
 )
 
-from ._ast import ParsedLooseSequence, ParsedSequence
+from ._ast import PaddedRange, ParsedLooseSequence, ParsedSequence, Ranges, non_recursive_asdict
 from ._error import ParseError
 from ._file_num_seq import FileNumSequence
 from ._from_disk import find_on_disk
@@ -32,6 +32,7 @@ class BasePurePathSequence(Sequence[PurePathT_co], metaclass=abc.ABCMeta):
     """A generic class that represents a path sequence.
 
     Raises:
+        NotASequenceError: When the given path does not represent a sequence.
         ParseError: When the given path is not a valid path sequence.
     """
 
@@ -274,6 +275,7 @@ def with_name(self, name: str) -> Self:
         Raises:
             ValueError: When the given name is empty.
                 Use :attr:`~.BasePurePathSequence.parent` instead.
+            NotASequenceError: When the given name does not represent a sequence.
             ParseError: When the resulting path is not a valid path sequence.
         """
         return self.with_segments(self._path.with_name(name))
@@ -293,7 +295,6 @@ def with_stem(self, stem: str) -> Self:
         parsed = self._parsed.with_stem(stem)
         return self.with_segments(self._path.parent, str(parsed))
 
-    @abc.abstractmethod
     def with_file_num_seqs(
         self, *seqs: FileNumSequence[int] | FileNumSequence[Decimal]
     ) -> Self:
@@ -303,6 +304,19 @@ def with_file_num_seqs(
             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)
+        )
+        kwargs = non_recursive_asdict(self)
+        kwargs["ranges"] = Ranges(new_ranges, self._parsed.ranges.inter_ranges)
+        new = self._parsed.__class__(**kwargs)
+        return self.with_segments(self._path.parent, str(new))
 
     def path_with_file_nums(self, *numbers: int | Decimal) -> PurePathT_co:
         """Return a path for the given file number(s) in the sequence.
@@ -457,6 +471,8 @@ class BasePathSequence(BasePurePathSequence[PathT_co], metaclass=abc.ABCMeta):
     """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.
     """
 

src/pathseq/_error.py

@@ -37,6 +37,17 @@ def __init__(
         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.