Merge pull request #952 from guessit-io/develop

release: v4.3.0

Author: Toilal

.github/workflows/ci.yml

@@ -178,6 +178,12 @@ jobs:
           git config --global user.name "github-actions"
 
       - name: Bump version
+        # A pull_request checkout is a detached merge commit, which python-semantic-release
+        # refuses to version ("Detached HEAD state cannot match any release groups") with a
+        # non-zero exit — unlike a branch outside the release groups, which it just skips.
+        # Artifacts built from a pull request are never published, so they keep the version
+        # already in pyproject.toml.
+        if: github.event_name != 'pull_request'
         run: uvx --from python-semantic-release semantic-release version --no-commit --no-tag --no-push
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -217,6 +223,8 @@ jobs:
           git config --global user.name "github-actions"
 
       - name: Bump version
+        # Skipped on a pull request: detached merge commit, see the build job.
+        if: github.event_name != 'pull_request'
         run: uvx --from python-semantic-release semantic-release version --no-commit --no-tag --no-push
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -259,6 +267,8 @@ jobs:
           git config --global user.name "github-actions"
 
       - name: Bump version
+        # Skipped on a pull request: detached merge commit, see the build job.
+        if: github.event_name != 'pull_request'
         run: uvx --from python-semantic-release semantic-release version --no-commit --no-tag --no-push
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -301,6 +311,8 @@ jobs:
           git config --global user.name "github-actions"
 
       - name: Bump version
+        # Skipped on a pull request: detached merge commit, see the build job.
+        if: github.event_name != 'pull_request'
         run: uvx --from python-semantic-release semantic-release version --no-commit --no-tag --no-push
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/known-limitations.md

@@ -77,6 +77,19 @@ The `SxxExx` chain extends across a weak `.` separator to the **consecutive** nu
 `S01E02.5.Kings` → episode `2`, episode_title `5 Kings`. Telling `S01E02.3.Kings` (title) apart from
 `S01E02.03` (range) needs to know `Kings` is a title, which is the same ambiguity as #743/#746.
 
+### #948 — a half-episode number
+
+```text
+[GroupName].Show.Name.-.02.5.(Special).[BD.1080p]
+  episode: 2   episode_title: "5"   episode_details: Special
+  wanted -> a single "episode 2.5" notion
+```
+
+`02.5` numbers a special sitting between episodes 2 and 3. Episode numbers are integers, so the
+fractional part has nowhere to go: guessit keeps it out of the numbering — it is neither a second
+episode nor a range — and it falls back to the episode title. Carrying it would need a new property,
+or a non-integer `episode` every consumer of the schema would have to follow.
+
 ### #744 — episode title made of numbers and hyphens
 
 ```text

guessit/config/options.json

@@ -362,7 +362,13 @@
       "ordinal_suffix": "(?:ª|º|°|a|o|-?(?:й|я|е|го|ая|ый|ое))?",
       "of_words": [
         "of",
-        "sur"
+        "sur",
+        "de",
+        "di",
+        "von",
+        "van",
+        "din",
+        "из"
       ],
       "all_words": [
         "All"
@@ -588,7 +594,7 @@
         "Proof": {"string": "Proof", "tags": ["at-end", "not-a-release-group"]},
         "Obfuscated": {"string": ["Obfuscated", "Scrambled"], "tags": ["at-end", "not-a-release-group"]},
         "Repost": {"string": ["xpost", "postbot", "asrequested"], "tags": "not-a-release-group"},
-        "_complete_words": {"callable": "import:guessit.rules.properties.other:complete_words", "season_words": ["seasons?", "series?"], "complete_article_words": ["The"]}
+        "_complete_words": {"callable": "import:guessit.rules.properties.other:complete_words", "season_words": ["seasons?", "series?"], "complete_article_words": ["The"], "season_number_separators": ["&", "and"]}
       },
       "art": {
         "poster": "Poster",

guessit/rules/properties/episodes.py

@@ -382,13 +382,16 @@ def season_word_not_year(match: Match) -> bool:
 
     # Non-English convention where the number precedes the keyword:
     #   "1ª Temporada", "3 сезон", "5-й сезон", "2.Sezon" (season); "24 серия", "7.Bölüm" (episode).
-    # An optional ordinal suffix (ª/º/°, Portuguese a/o, Russian -й/-я/…) may sit between the two.
+    # An optional ordinal suffix (ª/º/°, Portuguese a/o, Russian -й/-я/…) may sit between the two,
+    # and the total may follow the keyword ("5 серия из 12"), as it does in the word-first patterns.
+    of_count = r"(?:@?" + build_or_pattern(of_words) + r"@?(?P<count>\d+))?"
     rebulk.regex(
         r"(?P<season>\d{1,2})"
         + ordinal_suffix
         + r"@?@?"
         + build_or_pattern(season_words_numfirst, name="seasonMarker")
-        + r"(?![^\W\d_])",
+        + r"(?![^\W\d_])"
+        + of_count,
         tags=["SxxExx", "numfirst"],
         formatter={"season": parse_numeral},
         disabled=is_season_episode_disabled,
@@ -398,7 +401,8 @@ def season_word_not_year(match: Match) -> bool:
         + ordinal_suffix
         + r"@?@?"
         + build_or_pattern(episode_words_numfirst, name="episodeMarker")
-        + r"(?![^\W\d_])",
+        + r"(?![^\W\d_])"
+        + of_count,
         tags=["SxxExx", "numfirst"],
         formatter={"episode": parse_numeral},
         disabled=lambda context: is_disabled(context, "episode"),
@@ -416,8 +420,12 @@ def season_word_not_year(match: Match) -> bool:
         disabled=lambda context: context.get("type") == "episode" or is_disabled(context, "episode"),
     )
 
+    # A roman numeral can be read out of the letters a longer marker continues with ("Ep" then
+    # "i" of "Episodio"), so the marker only counts when it ends on a word boundary. The digit
+    # variant above needs no such guard: a letter can never start its number.
     rebulk.regex(
         build_or_pattern(episode_words, name="episodeMarker")
+        + r"(?![^\W\d_])"
         + r"-?-?(?:(?:№|#)-?)?(?P<episode>"
         + numeral
         + ")"
@@ -546,6 +554,7 @@ def season_word_not_year(match: Match) -> bool:
         EpisodeNumberSeparatorRange(range_separators),
         SeasonSeparatorRange(range_separators),
         RemoveWeakIfMovie(episode_words),
+        RemoveMisleadingLoneDigitEpisode,
         RemoveWeakIfSxxExx,
         RemoveWeakDuplicate,
         EpisodeDetailValidator,
@@ -766,18 +775,30 @@ def when(self, matches: Matches, context: dict[str, Any] | None) -> Any:
         season_count: list[Match] = []
 
         for count in matches.named("count"):
-            previous = matches.previous(count, lambda match: match.name in ["episode", "season"], 0)
-            if previous:
-                if previous.name == "episode":
-                    episode_count.append(count)
-                elif previous.name == "season":
-                    season_count.append(count)
-            else:
+            numbered = self._numbered_by(matches, count)
+            if numbered is None:
                 to_remove.append(count)
+            elif numbered.name == "episode":
+                episode_count.append(count)
+            else:
+                season_count.append(count)
         if to_remove or episode_count or season_count:
             return to_remove, episode_count, season_count
         return False
 
+    @staticmethod
+    def _numbered_by(matches: Matches, count: Match) -> Match | None:
+        """The episode or season the count belongs to: the last one its own match holds.
+
+        Scoped to the count's match rather than to the nearest neighbour, because another property
+        can sit on the linking word itself — "de" is the German language code as much as it is the
+        Spanish "of" — and would then hide the number the count completes.
+        """
+        numbers = matches.range(
+            count.initiator.start, count.start, predicate=lambda match: match.name in ("episode", "season")
+        )
+        return numbers[-1] if numbers else None
+
 
 class SeePatternRange(Rule):
     """
@@ -1090,6 +1111,102 @@ def when(self, matches: Matches, context: dict[str, Any] | None) -> Any:
         return False
 
 
+class RemoveMisleadingLoneDigitEpisode(Rule):
+    """
+    Remove a lone digit read as an episode while it plainly numbers something else.
+
+    Only a forced `type=episode` reads a single digit as an episode, and that pattern fires
+    wherever a digit sits — including inside a release group, in a parent directory, or in the
+    tail of a title — where it then evicts whatever owned that span. Such a digit is discarded
+    when it cannot be part of the episode numbering: quoted in a bracketed group, sitting in a
+    non-final path part, behind the dot of a decimal number, or unable to extend a marked episode
+    list (a list grows rightwards from its marker and stays glued to it, as in "E01 02 03")
+    (#943, #948).
+
+    Runs before anything is carved out of the name (rebulk executes rules by decreasing priority),
+    so the freed span goes back to the title instead of leaving a hole behind.
+    """
+
+    priority = PRE_PROCESS + 1
+    consequence = RemoveMatch
+
+    def enabled(self, context: dict[str, Any] | None) -> bool:
+        return bool(context and context.get("type") == "episode")
+
+    def when(self, matches: Matches, context: dict[str, Any] | None) -> Any:
+        to_remove: list[Match] = []
+        fileparts = matches.markers.named("path")
+        for index, filepart in enumerate(fileparts):
+            episodes_ = sorted(
+                matches.range(filepart.start, filepart.end, predicate=lambda m: m.name == "episode"),
+                key=lambda m: (m.start, m.end),
+            )
+            in_final_part = index == len(fileparts) - 1
+            misplaced = [
+                episode
+                for episode in episodes_
+                if self._is_lone_digit(episode)
+                and (
+                    self._numbers_something_else(matches, episode, in_final_part) or self._fraction_of_a_number(episode)
+                )
+            ]
+            kept = [episode for episode in episodes_ if episode not in misplaced]
+            misplaced.extend(self._detached_from_list(kept))
+
+            for episode in misplaced:
+                to_remove.extend(self._whole_match(matches, episode))
+
+        return to_remove
+
+    @staticmethod
+    def _is_lone_digit(episode: Match) -> bool:
+        return "weak-episode" in episode.tags and len(episode.raw or "") == 1
+
+    @staticmethod
+    def _numbers_something_else(matches: Matches, episode: Match, in_final_part: bool) -> bool:
+        """A digit numbering a parent directory ("/Volumes/data-1/…") or a quoted group ("[t.3.3.d]")."""
+        quoted = matches.markers.at_match(episode, lambda marker: marker.name == "group", 0)
+        return not in_final_part or bool(quoted)
+
+    @staticmethod
+    def _fraction_of_a_number(episode: Match) -> bool:
+        """A digit behind the dot of a decimal number ("02.5"): a half episode, not a second one."""
+        before = (episode.input_string or "")[: episode.start]
+        return len(before) > 1 and before[-1] == "." and before[-2].isdigit()
+
+    @classmethod
+    def _detached_from_list(cls, episodes_: list[Match]) -> list[Match]:
+        """Lone digits that cannot extend the marked episode list of their filepart."""
+        anchor = next((episode for episode in episodes_ if "weak-episode" not in episode.tags), None)
+        if anchor is None:
+            return []
+
+        detached: list[Match] = []
+        previous = anchor
+        for episode in episodes_:
+            if episode.end <= anchor.start:
+                if cls._is_lone_digit(episode):
+                    detached.append(episode)
+                continue
+
+            between = (episode.input_string or "")[previous.end : episode.start].strip(seps)
+            if between and cls._is_lone_digit(episode):
+                detached.append(episode)
+            else:
+                previous = episode
+
+        return detached
+
+    @staticmethod
+    def _whole_match(matches: Matches, episode: Match) -> list[Match]:
+        """The match and the private ones holding its span, so the freed text becomes a hole again."""
+        return matches.range(
+            episode.start,
+            episode.end,
+            predicate=lambda m: "weak-episode" in m.tags and m.start >= episode.start and m.end <= episode.end,
+        )
+
+
 class RemoveWeakIfSxxExx(Rule):
     """
     Remove weak-episode tagged matches if SxxExx pattern is matched.

guessit/rules/properties/other.py

@@ -142,12 +142,22 @@ def add(pattern: str, value: str, *, ignore_case: bool) -> None:
     add(r"ED", "Ending Credits", ignore_case=False)
 
 
-def complete_words(rebulk: Rebulk, season_words: Iterable[str], complete_article_words: Iterable[str]) -> None:
+def complete_words(
+    rebulk: Rebulk,
+    season_words: Iterable[str],
+    complete_article_words: Iterable[str],
+    season_number_separators: Iterable[str],
+) -> None:
     """
     Custom pattern to find complete seasons from words.
+
+    ``season_number_separators`` are the tokens that may join the season numbers a marker spans,
+    e.g. the ``&`` of "Seasons 1 & 2 - Complete"; plain separators are always allowed.
     """
     season_words_pattern = build_or_pattern(season_words)
     complete_article_words_pattern = build_or_pattern(complete_article_words)
+    # The season numbers listed between the season word and the marker: "1", "1 & 2", "1 and 2".
+    season_numbers_pattern = r"(?:-+(?:\d+|" + build_or_pattern(season_number_separators, escape=True) + r"))+-+"
 
     def validate_complete(match: Match) -> bool:
         """
@@ -177,6 +187,20 @@ def validate_complete(match: Match) -> bool:
         validator={"__parent__": and_(seps_surround, validate_complete)},
     )
 
+    # "Season 1 Complete", "Seasons 1 & 2 - Complete": the season numbers sit between the season
+    # word and the marker, so the adjacency pattern above cannot see the word. Anchoring on the
+    # numbered season word keeps the marker alive even when nothing matched the numbers — the
+    # season chain is off under a forced ``type=movie`` (#944).
+    rebulk.regex(
+        season_words_pattern + season_numbers_pattern + "(?P<other>Complete)",
+        children=True,
+        private_parent=True,
+        validate_all=True,
+        value={"other": "Complete"},
+        tags=["release-group-prefix"],
+        validator={"__parent__": seps_surround},
+    )
+
 
 class ProperCountRule(Rule):
     """

guessit/rules/properties/release_group.py

@@ -140,6 +140,16 @@ def leading_anime_group(matches: Matches, filepart: Match) -> Match | None:
     return None
 
 
+_SEPS_CHARS = re.escape(seps)
+
+#: A trailing hole made of a numeric run and a final dash-separated word, e.g. ``.313-314-GROUP``.
+#: Digits and separators alone cannot be a title, so the last word stays a release group even when
+#: nothing claimed the numbers.
+_NUMERIC_RUN_THEN_GROUP = re.compile(
+    rf"^[{_SEPS_CHARS}]?\d+(?:[{_SEPS_CHARS}]+\d+)*-(?P<group>[^{_SEPS_CHARS}]{{2,}})$"
+)
+
+
 class DashSeparatedReleaseGroup(Rule):
     """
     Detect dash separated release groups that might appear at the end or at the beginning of a release name.
@@ -288,8 +298,35 @@ def detect(self, matches: Matches, start: int, end: int, at_end: bool) -> Any:
 
         if candidate and self.is_valid(matches, candidate, start, end, at_end):
             return candidate
+        if at_end:
+            return self.detect_after_numeric_run(matches, start, end)
         return None
 
+    @classmethod
+    def detect_after_numeric_run(cls, matches: Matches, start: int, end: int) -> Match | None:
+        """
+        Detach a trailing dash separated group from an unclaimed numeric run.
+
+        ``Bleach.s16e03-04.313-314-GROUP`` leaves ``.313-314-GROUP`` as a single hole whenever no
+        rule claims the absolute episode run — the weak episode chains are off under a forced
+        ``type=movie`` (#944). The run is anchored on the season/episode markers it follows, so the
+        trailing word behind it is a release group rather than the tail of a title.
+        """
+        hole = matches.holes(start, end, index=-1, predicate=lambda m: m.end == end and m.raw)
+        if not hole or hole.raw is None:
+            return None
+
+        numeric_run = _NUMERIC_RUN_THEN_GROUP.match(hole.raw)
+        if not numeric_run or int_coercable(numeric_run.group("group")):
+            return None
+
+        previous = matches.range(start, hole.start, index=-1, predicate=lambda m: not m.private)
+        if not previous or previous.name not in ("season", "episode"):
+            return None
+
+        # The candidate keeps its leading dash, as the ones the branches above return do.
+        return Match(hole.start + numeric_run.start("group") - 1, hole.end, input_string=hole.input_string)
+
     def when(self, matches: Matches, context: dict[str, Any] | None) -> Any:
         if matches.named("release_group"):
             return None