episoder 0.12.0__tar.gz → 1.1.0__tar.gz

episoder-1.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include episoder.1
+include examples/home.episoder

episoder-1.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: episoder
+Version: 1.1.0
+Summary: TV episode notifier
+Home-page: https://code.ott.net/episoder/
+Author: Stefan Ott
+Author-email: stefan@ott.net
+License: GPL-3.0-or-later
+Project-URL: Source, https://git.ott.net/episoder/
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: COPYING
+Requires-Dist: argparse
+Requires-Dist: beautifulsoup4
+Requires-Dist: platformdirs
+Requires-Dist: requests
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: test
+Requires-Dist: mypy; extra == "test"
+Requires-Dist: flake8; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pyfakefs; extra == "test"
+Requires-Dist: types-requests; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# episoder
+
+![episoder](https://code.ott.net/episoder/screenshot.png "episoder 0.8.0")
+
+Episoder is a command-line tool that tells you about new episodes of your
+favourite TV shows. It gets its data from online TV episode guides such as
+epguides.com and TheTVDB.
+
+There is also a web frontend for episoder, called
+[webisoder](https://code.ott.net/webisoder).
+
+## Dependencies
+
+In order to use episoder, you need to have Python installed on your system. In
+addition to the default distribution, episoder uses the `requests`, `argparse`,
+`sqlalchemy` and `beautifulsoup4` packages.
+
+## Downloading
+
+The official website, bug tracker etc. for episoder can be found at
+[code.ott.net/episoder](https://code.ott.net/episoder/).
+
+## Installation
+
+You can install episoder from PyPI by running `pip install episoder` or you can
+download the tarball from the official website and install it manually using
+`pip install episoder-<version>.tar.gz`.
+
+## Getting started
+
+First, find a show you're interested in:
+
+    $ episoder search firefly
+    ID	Name
+    -------	--------------------
+    78874	Firefly
+    384248	Firefly Lane
+    329088	Firefly (2017)
+
+Add that show to episoder:
+
+    $ episoder add 78874
+
+Update your database:
+
+    $ episoder update
+
+And finally show your episodes:
+
+    $ episoder list
+
+The list may be empty, by default episoder deletes old episodes and will only
+show you the next few days. The `--nodate` option to the `update` and `list`
+command will change that, in case you care about days long gone and/or far in
+the future.
+
+## Configuration
+
+Episoder does not need any configuration, it should run fine out of the box.
+Still, some of its behaviour can be tweaked through a config file at
+`~/.episoder`, the [man page](https://code.ott.net/episoder/doc/config.html) has
+all the details.
+
+## Using episoder
+
+To use episoder you will typically:
+
+* Create a cron job to update your database once a day using `episoder update`
+* Add `episoder list` to your `~/.bashrc`, `~/.bash_profile`, `/etc/bash.bashrc`
+  or `/etc/profile` if you want to see your upcoming shows every time you start
+  a shell. Consult your shell's documentation to find out which file to use.
+* Or run `episoder notify` at regular intervals to get notifications by e-mail.
+
+## More documentation
+
+There is some documentation to help you get started:
+
+* [Using episoder](https://code.ott.net/episoder/doc/use.html)
+* [Episoder configuration](https://code.ott.net/episoder/doc/config.html)

episoder-1.1.0/README.md

@@ -0,0 +1,79 @@
+# episoder
+
+![episoder](https://code.ott.net/episoder/screenshot.png "episoder 0.8.0")
+
+Episoder is a command-line tool that tells you about new episodes of your
+favourite TV shows. It gets its data from online TV episode guides such as
+epguides.com and TheTVDB.
+
+There is also a web frontend for episoder, called
+[webisoder](https://code.ott.net/webisoder).
+
+## Dependencies
+
+In order to use episoder, you need to have Python installed on your system. In
+addition to the default distribution, episoder uses the `requests`, `argparse`,
+`sqlalchemy` and `beautifulsoup4` packages.
+
+## Downloading
+
+The official website, bug tracker etc. for episoder can be found at
+[code.ott.net/episoder](https://code.ott.net/episoder/).
+
+## Installation
+
+You can install episoder from PyPI by running `pip install episoder` or you can
+download the tarball from the official website and install it manually using
+`pip install episoder-<version>.tar.gz`.
+
+## Getting started
+
+First, find a show you're interested in:
+
+    $ episoder search firefly
+    ID	Name
+    -------	--------------------
+    78874	Firefly
+    384248	Firefly Lane
+    329088	Firefly (2017)
+
+Add that show to episoder:
+
+    $ episoder add 78874
+
+Update your database:
+
+    $ episoder update
+
+And finally show your episodes:
+
+    $ episoder list
+
+The list may be empty, by default episoder deletes old episodes and will only
+show you the next few days. The `--nodate` option to the `update` and `list`
+command will change that, in case you care about days long gone and/or far in
+the future.
+
+## Configuration
+
+Episoder does not need any configuration, it should run fine out of the box.
+Still, some of its behaviour can be tweaked through a config file at
+`~/.episoder`, the [man page](https://code.ott.net/episoder/doc/config.html) has
+all the details.
+
+## Using episoder
+
+To use episoder you will typically:
+
+* Create a cron job to update your database once a day using `episoder update`
+* Add `episoder list` to your `~/.bashrc`, `~/.bash_profile`, `/etc/bash.bashrc`
+  or `/etc/profile` if you want to see your upcoming shows every time you start
+  a shell. Consult your shell's documentation to find out which file to use.
+* Or run `episoder notify` at regular intervals to get notifications by e-mail.
+
+## More documentation
+
+There is some documentation to help you get started:
+
+* [Using episoder](https://code.ott.net/episoder/doc/use.html)
+* [Episoder configuration](https://code.ott.net/episoder/doc/config.html)

episoder-1.1.0/episoder/cache.py

@@ -0,0 +1,49 @@
+# episoder, https://code.ott.net/episoder
+#
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+from typing import Optional
+
+_FILE_NAME_TVDB_TOKEN = "tvdb_token"
+
+
+class Cache:
+    def __init__(self, path: str) -> None:
+        self._path = path
+
+    def set_tvdb_token(self, token: str) -> None:
+        if not os.path.exists(self._path):
+            os.mkdir(self._path)
+
+        fn = os.path.join(self._path, _FILE_NAME_TVDB_TOKEN)
+        with open(fn, 'w', encoding='utf8') as file:
+            file.write(token)
+
+    def get_tvdb_token(self) -> Optional[str]:
+        fn = os.path.join(self._path, _FILE_NAME_TVDB_TOKEN)
+        if not os.path.exists(fn):
+            return None
+
+        with open(fn, 'r', encoding='utf8') as file:
+            token = file.read()
+
+        return token
+
+    def clear_tvdb_token(self) -> None:
+        fn = os.path.join(self._path, _FILE_NAME_TVDB_TOKEN)
+        if os.path.exists(fn):
+            os.unlink(fn)

{episoder-0.12.0 → episoder-1.1.0}/episoder/config.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2025 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -35,7 +35,7 @@ class EpisoderConfig:
         self.datafile = path.join(environ['HOME'], '.episodes')
         self.dateformat = '%a, %b %d, %Y'
         self.format = '%airdate %show %seasonx%epnum'
-        self.tvdb_key = '8F15287C4B23B36E'
+        self.tvdb_key = '1f4c52fc-410a-4868-9724-4c3eba19bdc7'
 
         self.email_to: Optional[str] = None
         self.email_username: Optional[str] = None

{episoder-0.12.0 → episoder-1.1.0}/episoder/database.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2024 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -15,98 +15,105 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-from datetime import datetime
+from datetime import date, datetime
+from typing import Any, Optional
 
-from sqlalchemy import Column, Integer, Text, Date, ForeignKey, Sequence
-from sqlalchemy import DateTime, Boolean
-from sqlalchemy.orm import backref, declarative_base, relationship
+from sqlalchemy import Boolean, Date, DateTime, ForeignKey, Integer, Text
+from sqlalchemy import Sequence
+from sqlalchemy.orm import backref, DeclarativeBase, relationship
+from sqlalchemy.orm import mapped_column
 
-Base = declarative_base()
 
+# pylint: disable=too-few-public-methods
+class Base(DeclarativeBase):
+    pass
 
-class Show(Base):
 
+class Show(Base):
     RUNNING = 1
     SUSPENDED = 2
     ENDED = 3
 
     __tablename__ = "shows"
 
-    id = Column("show_id", Integer, Sequence("shows_show_id_seq"),
-                primary_key=True)
-    name = Column("show_name", Text)
-    url = Column(Text, unique=True)
-    updated = Column(DateTime)
-    enabled = Column(Boolean)
-    status = Column(Integer, default=RUNNING)
-
-    def __init__(self, name, url="", updated=datetime.fromtimestamp(0)):
-
+    id = mapped_column("show_id", Integer, Sequence("shows_show_id_seq"),
+                       primary_key=True)
+    name = mapped_column("show_name", Text)
+    url = mapped_column(Text, unique=True)
+    updated = mapped_column(DateTime)
+    enabled = mapped_column(Boolean)
+    status = mapped_column(Integer, default=RUNNING)
+
+    def __init__(self, name: str, url: str = "",
+                 updated: datetime = datetime.fromtimestamp(0)) -> None:
+        super().__init__()
         self.name = name
         self.url = url
         self.updated = updated
         self.status = Show.RUNNING
-        self.episodes = []
+        self.episodes: list[Episode] = []
         self.enabled = True
 
-    def __str__(self):
-
+    def __str__(self) -> str:
         return f"Show: {self.name}"
 
-    def __repr__(self):
-
+    def __repr__(self) -> str:
         return f'Show("{self.name}", "{self.url}")'
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> Any:
+        if not isinstance(other, Show):
+            return NotImplemented
 
         return self.name == other.name and self.url == other.url
 
 
 # pylint: disable=too-many-instance-attributes
 class Episode(Base):
-
     __tablename__ = "episodes"
 
-    show_id = Column(Integer, ForeignKey(Show.id), primary_key=True)
-    episode = Column("num", Integer, primary_key=True)
-    airdate = Column(Date)
-    season = Column(Integer, primary_key=True)
-    title = Column(Text)
-    totalnum = Column(Integer)
-    prodnum = Column(Text)
-    notified = Column(Date)
+    show_id = mapped_column(Integer, ForeignKey(Show.id), primary_key=True)
+    episode = mapped_column("num", Integer, primary_key=True)
+    airdate = mapped_column(Date)
+    season = mapped_column(Integer, primary_key=True)
+    title = mapped_column(Text)
+    totalnum = mapped_column(Integer)
+    prodnum = mapped_column(Text)
+    notified = mapped_column(Date)
     show = relationship(Show, backref=backref("episodes", cascade="all"))
 
     # pylint: disable=too-many-arguments,too-many-positional-arguments
-    def __init__(self, name, season, episode, aired, prodnum, total):
-
+    def __init__(self, name: str, season: int, episode: int, aired: date,
+                 prodnum: Optional[str], total: int) -> None:
+        super().__init__()
         self.title = name
-        self.season = int(season)
-        self.episode = int(episode)
+        self.season = season
+        self.episode = episode
         self.airdate = aired
         self.prodnum = prodnum
-        self.totalnum = int(total)
-
-    def __lt__(self, other):
-
-        return ((self.season < other.season)
-                or ((self.season == other.season)
-                    and (self.episode < other.episode)))
-
-    def __str__(self):
+        self.totalnum = total
 
+    def __str__(self) -> str:
         return f"{self.show.name} {self.season}x{self.episode:02d}: " \
                 f"{self.title}"
 
-    def __repr__(self):
-
+    def __repr__(self) -> str:
         airdate = self.airdate
 
         return f'Episode("{self.title}", {self.season}, {self.episode}, ' \
                f'date({airdate.year}, {airdate.month}, {airdate.day}), ' \
                f'"{self.prodnum}", {self.totalnum})'
 
-    def __eq__(self, other):
+    def __lt__(self, other: object) -> Any:
+        if not isinstance(other, Episode):
+            return NotImplemented
+
+        return ((self.season < other.season)
+                or ((self.season == other.season)
+                    and (self.episode < other.episode)))
+
+    def __eq__(self, other: object) -> Any:
+        if not isinstance(other, Episode):
+            return NotImplemented
 
         return (self.show_id == other.show_id
                 and self.season == other.season
@@ -114,15 +121,12 @@ class Episode(Base):
 
 
 class Meta(Base):
-
     __tablename__ = "meta"
-    key = Column(Text, primary_key=True)
-    value = Column(Text)
-
-    def __str__(self):
+    key = mapped_column(Text, primary_key=True)
+    value = mapped_column(Text)
 
+    def __str__(self) -> str:
         return f"Meta: {self.key} = {self.value}"
 
-    def __repr__(self):
-
+    def __repr__(self) -> str:
         return str(self)

{episoder-0.12.0 → episoder-1.1.0}/episoder/episoder.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2024 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -20,7 +20,7 @@ from datetime import date, timedelta
 from typing import Optional
 
 import sqlite3
-from sqlalchemy import create_engine, or_, and_, select, inspect
+from sqlalchemy import create_engine, or_, and_, select, inspect, Table
 from sqlalchemy.orm import sessionmaker
 
 from .database import Episode, Show, Meta
@@ -45,12 +45,19 @@ class Database:
 
         # Initialize the database if all tables are missing
         names = [Show, Episode, Meta]
-        tables = [t for t in names if inspector.has_table(t.__table__.name)]
+        tables = [t for t in names
+                  if inspector.has_table(t.__table__.name)]  # type: ignore
 
         if len(tables) < 1:
+            assert isinstance(Show.__table__, Table)
             Show.__table__.create(bind=self.engine)
+
+            assert isinstance(Episode.__table__, Table)
             Episode.__table__.create(bind=self.engine)
+
+            assert isinstance(Meta.__table__, Table)
             Meta.__table__.create(bind=self.engine)
+
             self.set_schema_version(4)
 
     def open(self) -> None:
@@ -78,6 +85,8 @@ class Database:
 
     def get_schema_version(self) -> int:
         inspector = inspect(self.engine)
+
+        assert isinstance(Meta.__table__, Table)
         if not inspector.has_table(Meta.__table__.name):
             return 1
 
@@ -114,8 +123,13 @@ class Database:
             upgrade.execute("DROP TABLE shows")
             upgrade.close()
 
+            assert isinstance(Show.__table__, Table)
             Show.__table__.create(bind=self.engine)
+
+            assert isinstance(Episode.__table__, Table)
             Episode.__table__.create(bind=self.engine)
+
+            assert isinstance(Meta.__table__, Table)
             Meta.__table__.create(bind=self.engine)
 
             schema_version = 4

episoder-1.1.0/episoder/errors.py

@@ -0,0 +1,9 @@
+
+
+class RemoteError(Exception):
+    pass
+
+
+class NotAuthenticated(Exception):
+    def __init__(self) -> None:
+        super().__init__('Not authenticated')

{episoder-0.12.0 → episoder-1.1.0}/episoder/main.py

@@ -2,7 +2,7 @@
 
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2025 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -26,6 +26,9 @@ from datetime import date
 from traceback import print_exc
 from typing import Any, Callable, Optional
 
+from platformdirs import PlatformDirs
+
+from .cache import Cache
 from .config import ConfigLoader, EpisoderConfig
 from .database import Show
 from .episoder import Database
@@ -33,7 +36,8 @@ from .options import OptionsLoader
 from .output import ColorfulRenderer, ColorlessRenderer, EmailNotifier
 from .output import ConsoleRenderer, NewEpisodesNotification, SmtpTestMessage
 from .sources import parser_for, setup_sources
-from .sources.thetvdb import TVDB, TVDBShowNotFoundError
+from .sources.thetvdb_legacy import TVDBLegacy
+from .sources.thetvdb_v4 import TVDBv4
 
 
 def configure_logging(args: Namespace) -> None:
@@ -65,7 +69,7 @@ class DatabaseWrapper:
         self._conn.close()
 
 
-def with_db(func: Callable) -> Callable:
+def with_db(func: Callable) -> Callable:  # type: ignore
     @functools.wraps(func)
     def wrapped(*args: str, **kwargs: str) -> Any:
         self = args[0]
@@ -220,15 +224,12 @@ class Episoder:
 
     def search(self, keyword: str) -> None:
         tvdb = parser_for('123')  # numeric IDs are TVDB entries
-        assert isinstance(tvdb, TVDB)
-
-        try:
-            print('ID\tName\n-------\t--------------------')
-            for show in tvdb.lookup(keyword):
-                print(f'{show.url}\t{show.name}')
+        assert isinstance(tvdb, (TVDBLegacy, TVDBv4))
+        shows = tvdb.lookup(keyword)
 
-        except TVDBShowNotFoundError:
-            print('Nothing found')
+        print('ID\tName\n-------\t--------------------')
+        for show in shows:
+            print(f'{show.url}\t{show.name}')
 
     def _update_shows(self, shows: list[Show], after: Optional[date]) -> None:
         assert self.database is not None
@@ -237,8 +238,7 @@ class Episoder:
                 parser = parser_for(show.url)
                 assert parser is not None
                 parser.parse(show, self.database)
-            # pylint: disable=broad-exception-caught
-            except Exception:
+            except Exception:  # pylint: disable=broad-exception-caught
                 self._log.error('Error parsing %s', show)
                 print_exc()
                 self.database.rollback()
@@ -358,6 +358,9 @@ class CommandWrapper:
 
 
 def main() -> None:
+    dirs = PlatformDirs('episoder', 'cockroach')
+    cache = Cache(dirs.user_cache_dir)
+
     loader = OptionsLoader()
     options = loader.parse_cmdline(sys.argv[1:])
     loader.validate(options)
@@ -367,7 +370,7 @@ def main() -> None:
     cfg = config_loader.load(options.c)
     config_loader.validate(cfg)
 
-    setup_sources(cfg.agent, cfg.tvdb_key)
+    setup_sources(cfg.agent, cfg.tvdb_key, cache)
 
     command = CommandWrapper(options, cfg)
     command.run(options.func)

{episoder-0.12.0 → episoder-1.1.0}/episoder/options.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2025 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

{episoder-0.12.0 → episoder-1.1.0}/episoder/output.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2025 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

{episoder-0.12.0 → episoder-1.1.0}/episoder/sources/__init__.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2024 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -18,8 +18,10 @@
 from typing import Optional, List
 import requests
 
+from episoder.cache import Cache
 from .epguides import Epguides
-from .thetvdb import TVDB
+from .thetvdb_legacy import TVDBLegacy
+from .thetvdb_v4 import TVDBv4
 from .tvcom import TVCom
 from .parser import Parser
 
@@ -28,13 +30,14 @@ session = requests.Session()
 PARSERS: List[Parser] = []
 
 
-def setup_sources(user_agent: str, tvdb_api_key: str) -> None:
+def setup_sources(user_agent: str, tvdb_api_key: str, cache: Cache) -> None:
     session.headers.update({'User-Agent': user_agent})
 
     while len(PARSERS) > 0:
         PARSERS.pop()
 
-    PARSERS.append(TVDB(session, tvdb_api_key))
+    PARSERS.append(TVDBv4(session, tvdb_api_key, cache))
+    PARSERS.append(TVDBLegacy(session, tvdb_api_key))
     PARSERS.append(Epguides(session))
     PARSERS.append(TVCom())
 

{episoder-0.12.0 → episoder-1.1.0}/episoder/sources/epguides.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2024 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -140,7 +140,7 @@ class Epguides(Parser):
         then = self._get_date(day)
 
         # prodnum is None, we don't have those
-        return Episode(title, season, epnum, then, None, total)
+        return Episode(title, int(season), int(epnum), then, None, total)
 
     def _load_text_episode(self, line: str) -> Optional[Episode]:
         # Known formatting supported by this fine regex:

{episoder-0.12.0 → episoder-1.1.0}/episoder/sources/parser.py

@@ -1,6 +1,6 @@
 # episoder, https://code.ott.net/episoder
 #
-# Copyright (C) 2004-2024 Stefan Ott. All rights reserved.
+# Copyright (C) 2004-2026 Stefan Ott. All rights reserved.
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by