cs-mediainfo 20260531__tar.gz

cs_mediainfo-20260531/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: cs-mediainfo
+Version: 20260531
+Summary: Simple minded facilities for media information inferred from filenames. This contains mostly lexical functions for extracting information from strings or constructing media filenames from metadata and a few classes like `EpisodeInfo` and `SeriesEpisodeInfo` for common descriptions.
+Keywords: python2,python3
+Author-email: Cameron Simpson <cs@cskk.id.au>
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Requires-Dist: cs.deco>=20260525
+Requires-Dist: cs.gimmicks>=20260311
+Requires-Dist: cs.lex>=20260526
+Requires-Dist: cs.pfx>=20250914
+Requires-Dist: cs.tagset>=20260531
+Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
+Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
+Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
+Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/mediainfo.py
+
+Simple minded facilities for media information inferred from filenames.
+This contains mostly lexical functions for extracting information from strings
+or constructing media filenames from metadata and a few classes
+like `EpisodeInfo` and `SeriesEpisodeInfo` for common descriptions.
+
+*Latest release 20260531*:
+Bugfix a parse return value, small doc updates.
+
+The default filename parsing rules are based on my personal convention,
+which is to name media files as:
+
+  series_name--episode_info--title--source--etc-etc.ext
+
+where the components are:
+* `series_name`:
+  the programme series name downcased and with whitespace replaced by dashes;
+  in the case of standalone items like movies this is often the studio.
+* `episode_info`: a structured field with episode information:
+  `s`_n_ is a series/season,
+  `e`_n_` is an episode number within the season,
+  `x`_n_` is a "extra" - addition material supplied with the season,
+  etc.
+* `title`: the episode title downcased and with whitespace replaced by dashes.
+* `source`: the source of the media.
+* `ext`: filename extension such as `mp4`.
+
+As you may imagine,
+as a rule I dislike mixed case filenames
+and filenames with embedded whitespace.
+I also like a media filename to contain enough information
+to identify the file contents in a compact and human readable form.
+
+Short summary:
+* `EpisodeDatumDefn`: An `EpisodeInfo` marker definition with the following components: - `name`: the marker name, such as `"series"` or `"episode"` - `prefix`: the stub used in a filename, such as `"s"` or `"e"` - `re`: a regular expression to match the `prefix` an some digits.
+* `EpisodeInfo`: Trite class for episodic information, used to store, match or transcribe series/season, episode, etc values.
+* `main`: Main command line running some test code.
+* `parse_name`: Parse the descriptive part of a filename (the portion remaining after stripping the file extension) and yield `(part,fields)` for each part as delineated by `sep`.
+* `part_to_title`: Convert a filename part into a title string.
+* `pathname_info`: Parse information from the basename of a file pathname. Return a mapping of field => values in the order parsed.
+* `scrub_title`: Strip redundant text from the start of an episode title.
+* `SeriesEpisodeInfo`: Episode information from a TV series episode.
+* `title_to_part`: Convert a title string into a filename part. This is lossy; the `part_to_title` function cannot completely reverse this.
+
+Module contents:
+- <a name="EpisodeDatumDefn"></a>`class EpisodeDatumDefn(EpisodeDatumDefn)`: An `EpisodeInfo` marker definition with the following components:
+  - `name`: the marker name, such as `"series"` or `"episode"`
+  - `prefix`: the stub used in a filename, such as `"s"` or `"e"`
+  - `re`: a regular expression to match the `prefix` an some digits
+
+*`EpisodeDatumDefn.parse(self, s, offset=0)`*:
+Parse an episode datum from a string, return the value and new offset.
+Raise `ValueError` if the string doesn't match this definition.
+
+Parameters:
+* `s`: the string
+* `offset`: parse offset, default 0
+- <a name="EpisodeInfo"></a>`class EpisodeInfo(types.SimpleNamespace)`: Trite class for episodic information, used to store, match
+  or transcribe series/season, episode, etc values.
+
+*`EpisodeInfo.__getitem__(self, name)`*:
+We can look up values by name.
+
+*`EpisodeInfo.as_dict(self)`*:
+Return the episode info as a `dict`.
+
+*`EpisodeInfo.as_tags(self, prefix=None)`*:
+Generator yielding the episode info as `Tag`s.
+
+*`EpisodeInfo.from_filename_part(s, offset=0)`*:
+Factory to return an `EpisodeInfo` from a filename episode field.
+
+Parameters:
+* `s`: the string containing the episode information
+* `offset`: the start of the episode information, default 0
+
+The episode information must extend to the end of the string
+because the factory returns just the information. See the
+`parse_filename_part` class method for the core parse.
+
+*`EpisodeInfo.get(self, name, default=None)`*:
+Look up value by name with default.
+
+*`EpisodeInfo.parse_filename_part(s, offset=0)`*:
+Parse episode information from a string,
+returning the matched fields and the new offset.
+
+Parameters:
+`s`: the string containing the episode information.
+`offset`: the starting offset of the information, default 0.
+
+*`EpisodeInfo.season`*:
+.season property, synonym for .series
+- <a name="main"></a>`main(argv=None)`: Main command line running some test code.
+- <a name="parse_name"></a>`parse_name(name, sep='--')`: Parse the descriptive part of a filename
+  (the portion remaining after stripping the file extension)
+  and yield `(part,fields)` for each part as delineated by `sep`.
+- <a name="part_to_title"></a>`part_to_title(part)`: Convert a filename part into a title string.
+
+  Example:
+
+      >>> part_to_title('episode-name')
+      'Episode Name'
+- <a name="pathname_info"></a>`pathname_info(pathname)`: Parse information from the basename of a file pathname.
+  Return a mapping of field => values in the order parsed.
+- <a name="scrub_title"></a>`scrub_title(title: str, *, season=None, episode=None) -> str`: Strip redundant text from the start of an episode title.
+
+  I frequently get "title" strings with leading season/episode information.
+  This function cleans up these strings to return the unadorned title.
+- <a name="SeriesEpisodeInfo"></a>`class SeriesEpisodeInfo(cs.deco.Promotable)`: Episode information from a TV series episode.
+
+*`SeriesEpisodeInfo.as_dict(self)`*:
+Return the non-`None` values as a `dict`.
+Note that this uses `dataclasses.asdict()` and as such is a deep copy.
+
+*`SeriesEpisodeInfo.from_str(episode_title: str, series=None)`*:
+Infer a `SeriesEpisodeInfo` from an episode title.
+
+This recognises the common `'sSSeEE - Episode Title'` format
+and variants like `Series Name - sSSeEE - Episode Title'`
+or `'sSSeEE - Episode Title - Part: One'`.
+- <a name="title_to_part"></a>`title_to_part(title)`: Convert a title string into a filename part.
+  This is lossy; the `part_to_title` function cannot completely reverse this.
+
+  Example:
+
+      >>> title_to_part('Episode Name')
+      'episode-name'
+
+# Release Log
+
+
+
+*Release 20260531*:
+Bugfix a parse return value, small doc updates.
+
+*Release 20240519*:
+Initial PyPI release, particularly for SeriesEpisodeInfo which I use in cs.app.playon.

cs_mediainfo-20260531/pyproject.toml

@@ -0,0 +1,186 @@
+[project]
+name = "cs-mediainfo"
+description = "Simple minded facilities for media information inferred from filenames. This contains mostly lexical functions for extracting information from strings or constructing media filenames from metadata and a few classes like `EpisodeInfo` and `SeriesEpisodeInfo` for common descriptions."
+authors = [
+    { name = "Cameron Simpson", email = "cs@cskk.id.au" },
+]
+keywords = [
+    "python2",
+    "python3",
+]
+dependencies = [
+    "cs.deco>=20260525",
+    "cs.gimmicks>=20260311",
+    "cs.lex>=20260526",
+    "cs.pfx>=20250914",
+    "cs.tagset>=20260531",
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+]
+version = "20260531"
+
+[project.license]
+text = "GNU General Public License v3 or later (GPLv3+)"
+
+[project.urls]
+"Monorepo Hg/Mercurial Mirror" = "https://hg.sr.ht/~cameron-simpson/css"
+"Monorepo Git Mirror" = "https://github.com/cameron-simpson/css"
+"MonoRepo Commits" = "https://bitbucket.org/cameron_simpson/css/commits/branch/main"
+Source = "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/mediainfo.py"
+
+[project.readme]
+text = """
+Simple minded facilities for media information inferred from filenames.
+This contains mostly lexical functions for extracting information from strings
+or constructing media filenames from metadata and a few classes
+like `EpisodeInfo` and `SeriesEpisodeInfo` for common descriptions.
+
+*Latest release 20260531*:
+Bugfix a parse return value, small doc updates.
+
+The default filename parsing rules are based on my personal convention,
+which is to name media files as:
+
+  series_name--episode_info--title--source--etc-etc.ext
+
+where the components are:
+* `series_name`:
+  the programme series name downcased and with whitespace replaced by dashes;
+  in the case of standalone items like movies this is often the studio.
+* `episode_info`: a structured field with episode information:
+  `s`_n_ is a series/season,
+  `e`_n_` is an episode number within the season,
+  `x`_n_` is a \"extra\" - addition material supplied with the season,
+  etc.
+* `title`: the episode title downcased and with whitespace replaced by dashes.
+* `source`: the source of the media.
+* `ext`: filename extension such as `mp4`.
+
+As you may imagine,
+as a rule I dislike mixed case filenames
+and filenames with embedded whitespace.
+I also like a media filename to contain enough information
+to identify the file contents in a compact and human readable form.
+
+Short summary:
+* `EpisodeDatumDefn`: An `EpisodeInfo` marker definition with the following components: - `name`: the marker name, such as `\"series\"` or `\"episode\"` - `prefix`: the stub used in a filename, such as `\"s\"` or `\"e\"` - `re`: a regular expression to match the `prefix` an some digits.
+* `EpisodeInfo`: Trite class for episodic information, used to store, match or transcribe series/season, episode, etc values.
+* `main`: Main command line running some test code.
+* `parse_name`: Parse the descriptive part of a filename (the portion remaining after stripping the file extension) and yield `(part,fields)` for each part as delineated by `sep`.
+* `part_to_title`: Convert a filename part into a title string.
+* `pathname_info`: Parse information from the basename of a file pathname. Return a mapping of field => values in the order parsed.
+* `scrub_title`: Strip redundant text from the start of an episode title.
+* `SeriesEpisodeInfo`: Episode information from a TV series episode.
+* `title_to_part`: Convert a title string into a filename part. This is lossy; the `part_to_title` function cannot completely reverse this.
+
+Module contents:
+- <a name=\"EpisodeDatumDefn\"></a>`class EpisodeDatumDefn(EpisodeDatumDefn)`: An `EpisodeInfo` marker definition with the following components:
+  - `name`: the marker name, such as `\"series\"` or `\"episode\"`
+  - `prefix`: the stub used in a filename, such as `\"s\"` or `\"e\"`
+  - `re`: a regular expression to match the `prefix` an some digits
+
+*`EpisodeDatumDefn.parse(self, s, offset=0)`*:
+Parse an episode datum from a string, return the value and new offset.
+Raise `ValueError` if the string doesn't match this definition.
+
+Parameters:
+* `s`: the string
+* `offset`: parse offset, default 0
+- <a name=\"EpisodeInfo\"></a>`class EpisodeInfo(types.SimpleNamespace)`: Trite class for episodic information, used to store, match
+  or transcribe series/season, episode, etc values.
+
+*`EpisodeInfo.__getitem__(self, name)`*:
+We can look up values by name.
+
+*`EpisodeInfo.as_dict(self)`*:
+Return the episode info as a `dict`.
+
+*`EpisodeInfo.as_tags(self, prefix=None)`*:
+Generator yielding the episode info as `Tag`s.
+
+*`EpisodeInfo.from_filename_part(s, offset=0)`*:
+Factory to return an `EpisodeInfo` from a filename episode field.
+
+Parameters:
+* `s`: the string containing the episode information
+* `offset`: the start of the episode information, default 0
+
+The episode information must extend to the end of the string
+because the factory returns just the information. See the
+`parse_filename_part` class method for the core parse.
+
+*`EpisodeInfo.get(self, name, default=None)`*:
+Look up value by name with default.
+
+*`EpisodeInfo.parse_filename_part(s, offset=0)`*:
+Parse episode information from a string,
+returning the matched fields and the new offset.
+
+Parameters:
+`s`: the string containing the episode information.
+`offset`: the starting offset of the information, default 0.
+
+*`EpisodeInfo.season`*:
+.season property, synonym for .series
+- <a name=\"main\"></a>`main(argv=None)`: Main command line running some test code.
+- <a name=\"parse_name\"></a>`parse_name(name, sep='--')`: Parse the descriptive part of a filename
+  (the portion remaining after stripping the file extension)
+  and yield `(part,fields)` for each part as delineated by `sep`.
+- <a name=\"part_to_title\"></a>`part_to_title(part)`: Convert a filename part into a title string.
+
+  Example:
+
+      >>> part_to_title('episode-name')
+      'Episode Name'
+- <a name=\"pathname_info\"></a>`pathname_info(pathname)`: Parse information from the basename of a file pathname.
+  Return a mapping of field => values in the order parsed.
+- <a name=\"scrub_title\"></a>`scrub_title(title: str, *, season=None, episode=None) -> str`: Strip redundant text from the start of an episode title.
+
+  I frequently get \"title\" strings with leading season/episode information.
+  This function cleans up these strings to return the unadorned title.
+- <a name=\"SeriesEpisodeInfo\"></a>`class SeriesEpisodeInfo(cs.deco.Promotable)`: Episode information from a TV series episode.
+
+*`SeriesEpisodeInfo.as_dict(self)`*:
+Return the non-`None` values as a `dict`.
+Note that this uses `dataclasses.asdict()` and as such is a deep copy.
+
+*`SeriesEpisodeInfo.from_str(episode_title: str, series=None)`*:
+Infer a `SeriesEpisodeInfo` from an episode title.
+
+This recognises the common `'sSSeEE - Episode Title'` format
+and variants like `Series Name - sSSeEE - Episode Title'`
+or `'sSSeEE - Episode Title - Part: One'`.
+- <a name=\"title_to_part\"></a>`title_to_part(title)`: Convert a title string into a filename part.
+  This is lossy; the `part_to_title` function cannot completely reverse this.
+
+  Example:
+
+      >>> title_to_part('Episode Name')
+      'episode-name'
+
+# Release Log
+
+
+
+*Release 20260531*:
+Bugfix a parse return value, small doc updates.
+
+*Release 20240519*:
+Initial PyPI release, particularly for SeriesEpisodeInfo which I use in cs.app.playon."""
+content-type = "text/markdown"
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = [
+    "flit_core >=3.2,<4",
+]
+
+[tool.flit.module]
+name = "cs.mediainfo"

cs_mediainfo-20260531/src/cs/mediainfo.py

@@ -0,0 +1,393 @@
+#!/usr/bin/env python3
+#
+# Assorted facilities for media information.
+# - Cameron Simpson <cs@cskk.id.au> 09may2018
+#
+
+'''
+Simple minded facilities for media information inferred from filenames.
+This contains mostly lexical functions for extracting information from strings
+or constructing media filenames from metadata and a few classes
+like `EpisodeInfo` and `SeriesEpisodeInfo` for common descriptions.
+
+The default filename parsing rules are based on my personal convention,
+which is to name media files as:
+
+  series_name--episode_info--title--source--etc-etc.ext
+
+where the components are:
+* `series_name`:
+  the programme series name downcased and with whitespace replaced by dashes;
+  in the case of standalone items like movies this is often the studio.
+* `episode_info`: a structured field with episode information:
+  `s`_n_ is a series/season,
+  `e`_n_` is an episode number within the season,
+  `x`_n_` is a "extra" - addition material supplied with the season,
+  etc.
+* `title`: the episode title downcased and with whitespace replaced by dashes.
+* `source`: the source of the media.
+* `ext`: filename extension such as `mp4`.
+
+As you may imagine,
+as a rule I dislike mixed case filenames
+and filenames with embedded whitespace.
+I also like a media filename to contain enough information
+to identify the file contents in a compact and human readable form.
+'''
+
+from collections import namedtuple, defaultdict
+from dataclasses import asdict, dataclass
+from os.path import basename, splitext
+import re
+import sys
+from types import SimpleNamespace as NS
+from typing import Optional
+
+from cs.deco import Promotable
+from cs.gimmicks import warning
+from cs.lex import cutsuffix, get_prefix_n, get_suffix_part
+from cs.pfx import Pfx, pfx
+from cs.tagset import Tag
+
+__version__ = '20260531'
+
+DISTINFO = {
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+    ],
+    'install_requires': [
+        'cs.deco',
+        'cs.gimmicks',
+        'cs.lex',
+        'cs.pfx',
+        'cs.tagset',
+    ],
+}
+
+USAGE = r'''Usage: %s media-filenames...'''
+
+def main(argv=None):
+  ''' Main command line running some test code.
+  '''
+  if argv is None:
+    argv = sys.argv
+  argv = list(argv)
+  cmd = argv.pop(0)
+  usage = USAGE % (cmd,)
+  if not argv:
+    warning("%s: missing media-filenames", cmd)
+    print(usage)
+    return 2
+  for pathname in argv:
+    with Pfx("%r", pathname):
+      name, _ = splitext(basename(pathname))
+      for part, fields in parse_name(name):
+        print(" ", part, repr(fields))
+      print(" ", name, pathname_info(pathname))
+  return 0
+
+def title_to_part(title):
+  ''' Convert a title string into a filename part.
+      This is lossy; the `part_to_title` function cannot completely reverse this.
+
+      Example:
+
+          >>> title_to_part('Episode Name')
+          'episode-name'
+  '''
+  return re.sub(r'[\s-]+', '-', title).strip().lower()
+
+def part_to_title(part):
+  ''' Convert a filename part into a title string.
+
+      Example:
+
+          >>> part_to_title('episode-name')
+          'Episode Name'
+  '''
+  return part.strip('- \t\r\n').replace('-', ' ').title()
+
+class EpisodeDatumDefn(namedtuple('EpisodeDatumDefn', 'name prefix re')):
+  ''' An `EpisodeInfo` marker definition with the following components:
+      - `name`: the marker name, such as `"series"` or `"episode"`
+      - `prefix`: the stub used in a filename, such as `"s"` or `"e"`
+      - `re`: a regular expression to match the `prefix` an some digits
+  '''
+
+  def __new__(cls, name, prefix):
+    r = re.compile(prefix + r'(\d+)', re.I)
+    return super(EpisodeDatumDefn, cls).__new__(cls, name, prefix, r)
+
+  def parse(self, s, offset=0):
+    ''' Parse an episode datum from a string, return the value and new offset.
+        Raise `ValueError` if the string doesn't match this definition.
+
+        Parameters:
+        * `s`: the string
+        * `offset`: parse offset, default 0
+    '''
+    m = self.re.match(s, offset)
+    if m:
+      return int(m.group(1)), m.end()
+    raise ValueError(
+        '%s: unparsed episode datum: %r' % (type(self).__name__, s[offset:])
+    )
+
+class EpisodeInfo(NS):
+  ''' Trite class for episodic information, used to store, match
+      or transcribe series/season, episode, etc values.
+  '''
+
+  MARKERS = [
+      EpisodeDatumDefn('series', 's'),
+      EpisodeDatumDefn('episode', 'e'),
+      EpisodeDatumDefn('part', 'pt'),
+      EpisodeDatumDefn('part', 'p'),
+      EpisodeDatumDefn('scene', 'sc'),
+      EpisodeDatumDefn('extra', 'x'),
+      EpisodeDatumDefn('extra', 'ex'),
+  ]
+
+  def __init__(self, series=None, episode=None, part=None, scene=None):
+    self.series = series
+    self.episode = episode
+    self.part = part
+    self.scene = scene
+
+  def as_dict(self):
+    ''' Return the episode info as a `dict`.
+    '''
+    d = {}
+    for attr in 'series', 'episode', 'part', 'scene':
+      value = getattr(self, attr)
+      if value is not None:
+        d[attr] = value
+    return d
+
+  def as_tags(self, prefix=None):
+    ''' Generator yielding the episode info as `Tag`s.
+    '''
+    for field, value in self.as_dict().items():
+      yield Tag(field, value, prefix=prefix)
+
+  def __str__(self):
+    marks = []
+    for marker in self.MARKERS:
+      value = self.get(marker.name)
+      if value is not None:
+        marks.append(marker.prefix + '%02d' % value)
+    return ''.join(marks)
+
+  def __getitem__(self, name):
+    ''' We can look up values by name.
+    '''
+    try:
+      value = getattr(self, name)
+    except AttributeError as e:
+      raise KeyError(name) from e
+    return value
+
+  def get(self, name, default=None):
+    ''' Look up value by name with default.
+    '''
+    try:
+      value = self[name]
+    except KeyError:
+      return default
+    return value
+
+  @classmethod
+  def from_filename_part(cls, s, offset=0):
+    ''' Factory to return an `EpisodeInfo` from a filename episode field.
+
+        Parameters:
+        * `s`: the string containing the episode information
+        * `offset`: the start of the episode information, default 0
+
+        The episode information must extend to the end of the string
+        because the factory returns just the information. See the
+        `parse_filename_part` class method for the core parse.
+    '''
+    fields, offset = cls.parse_filename_part(s, offset=offset)
+    if offset < len(s):
+      raise ValueError("unparsed filename part: %r" % (s[offset:],))
+    return cls(**fields)
+
+  @classmethod
+  @pfx
+  def parse_filename_part(cls, s, offset=0):
+    ''' Parse episode information from a string,
+        returning the matched fields and the new offset.
+
+        Parameters:
+        `s`: the string containing the episode information.
+        `offset`: the starting offset of the information, default 0.
+    '''
+    start_offset = offset
+    fields = {}
+    while offset < len(s):
+      offset0 = offset
+      for defn in cls.MARKERS:
+        if defn.name in fields:
+          # support for different definitions with a common prefix
+          # earlier definitions are matched first
+          continue
+        try:
+          value, offset = defn.parse(s, offset)
+        except ValueError:
+          pass
+        else:
+          fields[defn.name] = value
+          break
+      # parse fails, stop trying for more information
+      if offset == offset0:
+        break
+    if offset == start_offset:
+      # no component info, try other things
+      if len(s) == 4 and s.isdigit() and s.startswith(('19', '20')):
+        fields['year'] = int(s)
+      elif len(s) == 6 and s[1:-1].isdigit() and s.startswith(('19', '20'), 1):
+        fields['year'] = int(s[1:-1])
+    return fields, offset
+
+  @property
+  def season(self):
+    ''' .season property, synonym for .series
+    '''
+    return self.series
+
+  @season.setter
+  def season(self, n):
+    ''' .season property, synonym for .series
+    '''
+    self.series = n
+
+@pfx
+def parse_name(name, sep='--'):
+  ''' Parse the descriptive part of a filename
+      (the portion remaining after stripping the file extension)
+      and yield `(part,fields)` for each part as delineated by `sep`.
+  '''
+  unstructured_sections = ('series_name', 'episode_name', 'source_name')
+  unstructured_index = 0
+  for part0 in name.split(sep):
+    with Pfx(part0):
+      part = part0.strip('- \t\r\n')
+      if not part:
+        # ignore empty parts
+        continue
+      # look for series/episode/scene/part markers
+      fields, offset = EpisodeInfo.parse_filename_part(part)
+      if offset == 0:
+        # nothing parsed, consider the unstructured sections
+        if unstructured_index < len(unstructured_sections):
+          fields = {unstructured_sections[unstructured_index]: part}
+          unstructured_index += 1
+        else:
+          fields = None
+      elif offset < len(part):
+        warning(
+            "parse_name %r: part %r: unparsed: %r", name, part0, part[offset:]
+        )
+    yield part0, fields
+
+def pathname_info(pathname):
+  ''' Parse information from the basename of a file pathname.
+      Return a mapping of field => values in the order parsed.
+  '''
+  info = defaultdict(list)
+  name, _ = splitext(basename(pathname))
+  for _, fields in parse_name(name):
+    if fields:
+      for field, value in fields.items():
+        if field in info:
+          warning(
+              "discard %r=%r: already have %r=%r", field, value, field,
+              info[field]
+          )
+        else:
+          info[field].append(value)
+  return info
+
+def scrub_title(title: str, *, season=None, episode=None) -> str:
+  ''' Strip redundant text from the start of an episode title.
+
+      I frequently get "title" strings with leading season/episode information.
+      This function cleans up these strings to return the unadorned title.
+  '''
+  title = title.strip()
+  if season:
+    spfx, _, offset = get_prefix_n(title, 's', n=season)
+    if spfx:
+      assert title.startswith(f's{season:02d}')
+      title = title[offset:]
+  if episode:
+    epfx, _, offset = get_prefix_n(title, 'e', n=episode)
+    if epfx:
+      assert title.startswith(f'e{episode:02d}')
+      title = title[offset:]
+  title = title.lstrip(' -')
+  if episode:
+    epfx, _, offset = get_prefix_n(title.lower(), 'episode ', n=episode)
+    if epfx:
+      title = title[offset:]
+    title = title.lstrip(' -')
+  return title
+
+@dataclass
+class SeriesEpisodeInfo(Promotable):
+  ''' Episode information from a TV series episode.
+  '''
+
+  series: str
+  season: int
+  episode: int
+  episode_title: Optional[str] = None
+  episode_part: Optional[int] = None
+
+  @classmethod
+  def from_str(cls, episode_title: str, series=None):
+    ''' Infer a `SeriesEpisodeInfo` from an episode title.
+
+        This recognises the common `'sSSeEE - Episode Title'` format
+        and variants like `Series Name - sSSeEE - Episode Title'`
+        or `'sSSeEE - Episode Title - Part: One'`.
+    '''
+    if not series:
+      # look for leading "series - sSSeEE"
+      m = re.match(
+          r'(?P<series>\S.*\S)\s+(-\s+)?(?=s\d+e\d+\s)', episode_title, re.I
+      )
+      if m:
+        series = m.group('series')
+        episode_title = episode_title[m.end():]
+    # strip leading "sSSeEE - " prefix
+    _, season, offset = get_prefix_n(episode_title.lower(), 's')
+    _, episode, offset = get_prefix_n(
+        episode_title.lower(), 'e', offset=offset
+    )
+    if offset > 0:
+      # strip the sSSeEE and any following spaces or dashes
+      episode_title = episode_title[offset:].lstrip(' -')
+    # strip the trailing part info eg ": Part One"
+    part_suffix, episode_part = get_suffix_part(episode_title)
+    if part_suffix:
+      episode_title = cutsuffix(episode_title, part_suffix)
+    return cls(
+        series=series,
+        season=season,
+        episode=episode,
+        episode_title=episode_title,
+        episode_part=episode_part,
+    )
+
+  def as_dict(self):
+    ''' Return the non-`None` values as a `dict`.
+        Note that this uses `dataclasses.asdict()` and as such is a deep copy.
+    '''
+    return {k: v for k, v in asdict(self).items() if v is not None}
+
+if __name__ == '__main__':
+  sys.exit(main(sys.argv))