shownamer 1.0.0__py3-none-any.whl

shownamer/cli.py

@@ -0,0 +1,151 @@
+import os
+import re
+import requests
+import argparse
+from collections import defaultdict
+
+# Default supported video extensions
+DEFAULT_EXTENSIONS = [".mkv", ".mp4", ".avi", ".mov", ".flv"]
+TOOL_VERSION = "1.0.0"
+
+# Regex to parse filename
+FILENAME_PATTERN = re.compile(
+    r"^(?P<show>.+?)\s+[Ss](?P<season>\d{2})[Ee](?P<episode>\d{2})"
+)
+
+# Characters not allowed in filenames
+INVALID_CHARS = r'\/:*?"<>|'
+
+
+def sanitize_filename(name):
+    """Remove or replace characters that are not allowed in filenames."""
+    return "".join(c if c not in INVALID_CHARS else "_" for c in name)
+
+
+def get_episode_title(show_name, season, episode):
+    """Query TVmaze API for the episode title."""
+    response = requests.get(
+        "https://api.tvmaze.com/singlesearch/shows", params={"q": show_name}
+    )
+    if response.status_code != 200:
+        return None
+    show_data = response.json()
+    show_id = show_data["id"]
+
+    episode_response = requests.get(
+        f"https://api.tvmaze.com/shows/{show_id}/episodebynumber",
+        params={"season": season, "number": episode},
+    )
+    if episode_response.status_code != 200:
+        return None
+    return episode_response.json()["name"]
+
+
+def list_series_summary(directory, extensions):
+    """List all detected show names with season/episode counts."""
+    stats = defaultdict(lambda: defaultdict(int))
+    for filename in os.listdir(directory):
+        name, ext = os.path.splitext(filename)
+        if ext.lower() not in extensions:
+            continue
+        match = FILENAME_PATTERN.match(name)
+        if not match:
+            continue
+        show = match.group("show").strip()
+        season = int(match.group("season"))
+        stats[show][season] += 1
+
+    if not stats:
+        print("No recognizable TV show files found.")
+        return
+
+    print("Detected Series Summary:")
+    for show, seasons in stats.items():
+        print(f"  {show}:")
+        for season, count in sorted(seasons.items()):
+            print(f"    Season {season:02}: {count} episode(s)")
+
+
+def rename_files(directory, extensions, dry_run=False, verbose=False):
+    for filename in os.listdir(directory):
+        name, ext = os.path.splitext(filename)
+        if ext.lower() not in extensions:
+            continue
+
+        match = FILENAME_PATTERN.match(name)
+        if not match:
+            if verbose:
+                print(f"[skip] {filename}: doesn't match expected pattern")
+            continue
+
+        show = match.group("show").strip()
+        season = int(match.group("season"))
+        episode = int(match.group("episode"))
+
+        episode_title = get_episode_title(show, season, episode)
+        if not episode_title:
+            print(f"[fail] {filename}: could not fetch episode title")
+            continue
+
+        safe_title = sanitize_filename(episode_title)
+        new_filename = f"{show} S{season:02}E{episode:02} - {safe_title}{ext}"
+        src = os.path.join(directory, filename)
+        dst = os.path.join(directory, new_filename)
+
+        if dry_run:
+            print(f"[dry-run] {filename} → {new_filename}")
+        else:
+            os.rename(src, dst)
+            print(f"[renamed] {filename} → {new_filename}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Rename TV episode files by fetching episode titles from TVmaze."
+    )
+    parser.add_argument(
+        "--dir",
+        default=os.getcwd(),
+        help="Directory containing video files (default: script's directory)",
+    )
+    parser.add_argument(
+        "--ext",
+        nargs="*",
+        default=DEFAULT_EXTENSIONS,
+        help="List of allowed video file extensions (default: common types)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Preview renaming without making changes"
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="Show skipped files and debug info"
+    )
+    parser.add_argument(
+        "--version", action="store_true", help="Show tool version and exit"
+    )
+    parser.add_argument(
+        "--name", action="store_true", help="List show names and episode counts"
+    )
+
+    args = parser.parse_args()
+
+    extensions = [e if e.startswith(".") else "." + e for e in args.ext]
+
+    if args.version:
+        print(f"shownamer version {TOOL_VERSION}")
+        return
+
+    if args.name:
+        list_series_summary(args.dir, extensions)
+        return
+
+    rename_files(
+        directory=args.dir,
+        extensions=extensions,
+        dry_run=args.dry_run,
+        verbose=args.verbose,
+    )
+
+
+if __name__ == "__main__":
+    main()

shownamer-1.0.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: shownamer
+Version: 1.0.0
+Summary: Rename TV show Media files with Respective episode Titles/Names.
+Home-page: https://github.com/theamallalgi/shownamer
+Author: Amal Lalgi
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+![Intro](https://github.com/theamallalgi/shownamer/blob/main/dependencies/header.png?raw=true)
+# Shownamer - Media Renamer
+A lightweight Python CLI tool that renames TV show episode video files by fetching their actual episode titles. Movies are not supported, All TV Shows and Sitcoms are supported.
+
+>[!NOTE]
+> Fetches details and Names from [TVmaze](https://www.tvmaze.com/).
+
+## Features
+
+- Automatically detects and renames files like:
+
+  ```
+  Before: Malcolm in the Middle S01E10.mkv
+  After: Malcolm in the Middle S01E10 - Stock Car Races.mkv
+  ```
+- Fetches episode titles using the free TVmaze API.
+- Cleans illegal filename characters automatically.
+- CLI flags for:
+  - Custom directory
+  - File extension filter
+  - Dry-run mode
+  - Verbose logging
+
+## Usage
+
+### Requirements
+
+- Python 3.6+
+- `requests` module
+
+Install requirements:
+```bash
+pip install requests
+```
+
+### Run the script
+
+```bash
+python shownamer.py
+```
+
+### Example Usage
+
+```bash
+# Rename all valid video files in the current directory
+python shownamer.py
+
+# Specify a custom directory
+python shownamer.py --dir "/path/to/your/episodes"
+
+# Preview changes without renaming files
+python shownamer.py --dry-run
+
+# Limit to specific extensions
+python shownamer.py --ext mkv mp4 avi
+
+# Verbose mode (shows skipped files, debug info)
+python shownamer.py --verbose
+```
+
+## Supported Formats
+
+The script supports the following file name pattern:
+
+```
+Show Name S01E01.ext
+```
+
+It handles these video formats by default:
+
+- `.mkv`
+- `.mp4`
+- `.avi`
+- `.mov`
+- `.flv`
+
+You can customize this with the `--ext` flag.
+
+## FAQ
+
+### Will this overwrite existing files?
+No. The script does not overwrite files. It renames only when the target filename does not exist. You can use `--dry-run` to preview the result first.
+
+### Does it fetch subtitles or cover images?
+No. This tool only renames the video files with accurate episode titles.
+
+## Contributions
+
+Pull requests, suggestions, and issues are welcome! Let's make it smarter and broader (e.g., subtitle renaming, fuzzy matching, show aliases, etc.).

shownamer-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+shownamer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shownamer/cli.py,sha256=EDhQZK1ipasyj_wE9cAT2obhoh01t9b9JXAWQOTEJPc,4739
+shownamer-1.0.0.dist-info/licenses/LICENSE,sha256=PqJKXIwhmeOuMo-i9B6aXn9GgjJ9TcMkIglF_uhesYg,1088
+shownamer-1.0.0.dist-info/METADATA,sha256=qblwCA8L5VnbVNccPfIiBJolpzWqZQ634edbosiRuq4,2839
+shownamer-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+shownamer-1.0.0.dist-info/entry_points.txt,sha256=Cgm3ZYbYuwA9y2ygRxk618jsXc3qeqEQ4EKEwQzIADI,49
+shownamer-1.0.0.dist-info/top_level.txt,sha256=gFru4EHM37wcJ4uZ8dSEYz1Frj2URzqt--WDVarUHYg,10
+shownamer-1.0.0.dist-info/RECORD,,

shownamer-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shownamer-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shownamer = shownamer.cli:main

shownamer-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Amal lalgi
+
+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.

shownamer-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shownamer