Some refactoring.

Signed-off-by: Cliff Hill <xlorep@darkhelm.org>

.cookiecutter.json

@@ -1,11 +1,16 @@
 {
+  "_checkout": "2022.6.3",
+  "_output_dir": "/config/workspace/DarkHelm.org/plex-playlist",
+  "_repo_dir": "/config/.cookiecutters/cookiecutter-hypermodern-python",
   "_template": "gh:cjolowicz/cookiecutter-hypermodern-python",
   "author": "Cliff Hill",
+  "copyright_year": "2023",
+  "development_status": "Development Status :: 1 - Planning",
   "email": "xlorep@darkhelm.org",
-  "friendly_name": "Automated Daily Playlist Generator for Plex Music",
+  "friendly_name": "Plex Playlist",
   "github_user": "xlorepdarkhelm",
   "license": "MIT",
   "package_name": "playlist",
   "project_name": "plex-playlist",
-  "version": "0.1.0"
+  "version": "0.0.0"
 }

.darglint

@@ -1,2 +1,2 @@
 [darglint]
-strictness = short
+strictness = long

.flake8

@@ -1,21 +1,9 @@
 [flake8]
 select = B,B9,C,D,DAR,E,F,N,RST,S,W
 ignore = E203,E501,RST201,RST203,RST301,W503
-max-line-length = 88
+max-line-length = 100
 max-complexity = 10
 docstring-convention = google
-per-file-ignores = tests/*:S101
-based-on-style = "pep8"
-column-limit = 88
-indent-width = 4
-spaces_before_comment = 2
-ALLOW_SPLIT_BEFORE_DICT_VALUE = false
-DEDENT_CLOSING_BRACKETS = true
-EACH_DICT_ENTRY_ON_SEPARATE_LINE = true
-COALESCE_BRACKETS = true
-USE_TABS = false
-ALLOW_MULTILINE_LAMBDAS = true
-BLANK_LINE_BEFORE_NESTED_CLASS_ON_DEF = true
-INDENT_DICTIONARY_VALUE = true
-SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN = true
-DISABLE_ENDING_COMMA_HEURISTIC = true
+per-file-ignores = backend/tests/*:S101
+rst-roles = class,const,func,meth,mod,ref
+rst-directives = deprecated

.github/dependabot.yml

@@ -16,3 +16,6 @@ updates:
     directory: "/"
     schedule:
       interval: daily
+    versioning-strategy: lockfile-only
+    allow:
+      - dependency-type: "all"

.github/docs/adrs/000-template.md

@@ -0,0 +1,20 @@
+# ADR N: brief decision title
+
+Describe here the forces that influence the design decision, including technological, cost-related, and project local.
+
+## Decision
+
+Describe here our response to these forces, that is, the design decision that was made. State the decision in full sentences, with active voice ("We will...").
+
+## Rationale
+
+Describe here the rationale for the design decision. Also indicate the rationale for significant _rejected_ alternatives. This section may also indicate assumptions, constraints, requirements, and results of evaluations and experiments.
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded]
+If deprecated, indicate why. If superseded, include a link to the new ADR.
+
+## Consequences
+
+Describe here the resulting context, after applying the decision. All consequences should be listed, not just the "positive" ones.

.github/docs/diagrams/updater.mermaid

@@ -0,0 +1,10 @@
+flowchart TD
+    A[Start] --> B[[Update start timestamp & get last updated]]
+    B --> C([Get track from plex])
+    C --> |more tracks| D[[Remove recently played tracks from playlist]]
+    D --> E[[Insert/update track into database]]
+    E --> C
+    C --> |no more tracks| F[[Clean up genres]]
+    F --> G[[Calculate statistics]]
+    G --> H[[Update end timestamp]]
+    H --> I[End]

.github/workflows/constraints.txt

@@ -1,5 +1,5 @@
-pip==21.0.1
-nox==2020.12.31
-nox-poetry==0.8.2
-poetry==1.1.5
-virtualenv==20.4.2
+pip==22.1.2
+nox==2022.1.7
+nox-poetry==1.0.0
+poetry==1.1.13
+virtualenv==20.14.1

.github/workflows/labeler.yml

@@ -11,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.3.3
+        uses: actions/checkout@v3
 
       - name: Run Labeler
-        uses: crazy-max/ghaction-github-labeler@v3.1.1
+        uses: crazy-max/ghaction-github-labeler@v4.0.0
         with:
           skip-delete: true

.github/workflows/release.yml

@@ -12,14 +12,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.3.4
+        uses: actions/checkout@v3
         with:
           fetch-depth: 2
 
       - name: Set up Python
-        uses: actions/setup-python@v2.2.1
+        uses: actions/setup-python@v3
         with:
-          python-version: "3.9"
+          python-version: "3.10"
 
       - name: Upgrade pip
         run: |
@@ -57,21 +57,21 @@ jobs:
 
       - name: Publish package on PyPI
         if: steps.check-version.outputs.tag
-        uses: pypa/gh-action-pypi-publish@v1.4.2
+        uses: pypa/gh-action-pypi-publish@v1.5.0
         with:
           user: __token__
           password: ${{ secrets.PYPI_TOKEN }}
 
       - name: Publish package on TestPyPI
         if: "! steps.check-version.outputs.tag"
-        uses: pypa/gh-action-pypi-publish@v1.4.2
+        uses: pypa/gh-action-pypi-publish@v1.5.0
         with:
           user: __token__
           password: ${{ secrets.TEST_PYPI_TOKEN }}
           repository_url: https://test.pypi.org/legacy/
 
       - name: Publish the release notes
-        uses: release-drafter/release-drafter@v5.14.0
+        uses: release-drafter/release-drafter@v5.20.0
         with:
           publish: ${{ steps.check-version.outputs.tag != '' }}
           tag: ${{ steps.check-version.outputs.tag }}

.github/workflows/tests.yml

@@ -6,53 +6,65 @@ on:
 
 jobs:
   tests:
-    name: ${{ matrix.session }} ${{ matrix.python-version }} / ${{ matrix.os }}
+    name: ${{ matrix.session }} ${{ matrix.python }} / ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         include:
-          - { python-version: 3.9, os: ubuntu-latest, session: "pre-commit" }
-          - { python-version: 3.9, os: ubuntu-latest, session: "safety" }
-          - { python-version: 3.9, os: ubuntu-latest, session: "mypy" }
-          - { python-version: 3.8, os: ubuntu-latest, session: "mypy" }
-          - { python-version: 3.7, os: ubuntu-latest, session: "mypy" }
-          - { python-version: 3.6, os: ubuntu-latest, session: "mypy" }
-          - { python-version: 3.9, os: ubuntu-latest, session: "tests" }
-          - { python-version: 3.8, os: ubuntu-latest, session: "tests" }
-          - { python-version: 3.7, os: ubuntu-latest, session: "tests" }
-          - { python-version: 3.6, os: ubuntu-latest, session: "tests" }
-          - { python-version: 3.9, os: windows-latest, session: "tests" }
-          - { python-version: 3.9, os: macos-latest, session: "tests" }
-          - { python-version: 3.9, os: ubuntu-latest, session: "typeguard" }
-          - { python-version: 3.9, os: ubuntu-latest, session: "xdoctest" }
-          - { python-version: 3.8, os: ubuntu-latest, session: "docs-build" }
+          - { python: "3.10", os: "ubuntu-latest", session: "pre-commit" }
+          - { python: "3.10", os: "ubuntu-latest", session: "safety" }
+          - { python: "3.10", os: "ubuntu-latest", session: "mypy" }
+          - { python: "3.9", os: "ubuntu-latest", session: "mypy" }
+          - { python: "3.8", os: "ubuntu-latest", session: "mypy" }
+          - { python: "3.7", os: "ubuntu-latest", session: "mypy" }
+          - { python: "3.10", os: "ubuntu-latest", session: "tests" }
+          - { python: "3.9", os: "ubuntu-latest", session: "tests" }
+          - { python: "3.8", os: "ubuntu-latest", session: "tests" }
+          - { python: "3.7", os: "ubuntu-latest", session: "tests" }
+          - { python: "3.10", os: "windows-latest", session: "tests" }
+          - { python: "3.10", os: "macos-latest", session: "tests" }
+          - { python: "3.10", os: "ubuntu-latest", session: "typeguard" }
+          - { python: "3.10", os: "ubuntu-latest", session: "xdoctest" }
+          - { python: "3.10", os: "ubuntu-latest", session: "docs-build" }
 
     env:
       NOXSESSION: ${{ matrix.session }}
+      FORCE_COLOR: "1"
+      PRE_COMMIT_COLOR: "always"
 
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.3.4
+        uses: actions/checkout@v3
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2.2.1
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v3
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ matrix.python }}
 
       - name: Upgrade pip
         run: |
           pip install --constraint=.github/workflows/constraints.txt pip
           pip --version
 
+      - name: Upgrade pip in virtual environments
+        shell: python
+        run: |
+          import os
+          import pip
+
+          with open(os.environ["GITHUB_ENV"], mode="a") as io:
+              print(f"VIRTUALENV_PIP={pip.__version__}", file=io)
+
       - name: Install Poetry
         run: |
-          pip install --constraint=.github/workflows/constraints.txt poetry
+          pipx install --pip-args=--constraint=.github/workflows/constraints.txt poetry
           poetry --version
 
       - name: Install Nox
         run: |
-          pip install --constraint=.github/workflows/constraints.txt nox nox-poetry
+          pipx install --pip-args=--constraint=.github/workflows/constraints.txt nox
+          pipx inject --pip-args=--constraint=.github/workflows/constraints.txt nox nox-poetry
           nox --version
 
       - name: Compute pre-commit cache key
@@ -71,7 +83,7 @@ jobs:
           print("::set-output name=result::{}".format(result))
 
       - name: Restore pre-commit cache
-        uses: actions/cache@v2.1.4
+        uses: actions/cache@v3
         if: matrix.session == 'pre-commit'
         with:
           path: ~/.cache/pre-commit
@@ -81,18 +93,18 @@ jobs:
 
       - name: Run Nox
         run: |
-          nox --force-color --python=${{ matrix.python-version }}
+          nox --python=${{ matrix.python }}
 
       - name: Upload coverage data
         if: always() && matrix.session == 'tests'
-        uses: "actions/upload-artifact@v2.2.2"
+        uses: "actions/upload-artifact@v3"
         with:
           name: coverage-data
           path: ".coverage.*"
 
       - name: Upload documentation
         if: matrix.session == 'docs-build'
-        uses: actions/upload-artifact@v2.2.2
+        uses: actions/upload-artifact@v3
         with:
           name: docs
           path: docs/_build
@@ -102,12 +114,12 @@ jobs:
     needs: tests
     steps:
       - name: Check out the repository
-        uses: actions/checkout@v2.3.4
+        uses: actions/checkout@v3
 
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v2.2.1
+      - name: Set up Python
+        uses: actions/setup-python@v3
         with:
-          python-version: 3.9
+          python-version: "3.10"
 
       - name: Upgrade pip
         run: |
@@ -116,26 +128,27 @@ jobs:
 
       - name: Install Poetry
         run: |
-          pip install --constraint=.github/workflows/constraints.txt poetry
+          pipx install --pip-args=--constraint=.github/workflows/constraints.txt poetry
           poetry --version
 
       - name: Install Nox
         run: |
-          pip install --constraint=.github/workflows/constraints.txt nox nox-poetry
+          pipx install --pip-args=--constraint=.github/workflows/constraints.txt nox
+          pipx inject --pip-args=--constraint=.github/workflows/constraints.txt nox nox-poetry
           nox --version
 
       - name: Download coverage data
-        uses: actions/download-artifact@v2.0.8
+        uses: actions/download-artifact@v3
         with:
           name: coverage-data
 
       - name: Combine coverage data and display human readable report
         run: |
-          nox --force-color --session=coverage
+          nox --session=coverage
 
       - name: Create coverage report
         run: |
-          nox --force-color --session=coverage -- xml
+          nox --session=coverage -- xml
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v1.2.2
+        uses: codecov/codecov-action@v3.1.0

.gitignore

@@ -1,158 +1,11 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-.python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
 .mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# Swap
-[._]*.s[a-v][a-z]
-!*.svg  # comment out if you don't need vector files
-[._]*.sw[a-p]
-[._]s[a-rt-v][a-z]
-[._]ss[a-gi-z]
-[._]sw[a-p]
-
-# Session
-Session.vim
-Sessionx.vim
-
-# Temporary
-.netrwhist
-*~
-# Auto-generated tag files
-tags
-# Persistent undo
-[._]*.un~
+/.coverage
+/.coverage.*
+/.nox/
+/.python-version
+/.pytype/
+/dist/
+/docs/_build/
+/src/*.egg-info/
+__pycache__/
+.env

.pre-commit-config.yaml

@@ -1,4 +1,3 @@
----
 repos:
   - repo: local
     hooks:
@@ -22,6 +21,12 @@ repos:
         entry: check-yaml
         language: system
         types: [yaml]
+      - id: darglint
+        name: darglint
+        entry: darglint
+        language: system
+        types: [python]
+        stages: [manual]
       - id: end-of-file-fixer
         name: Fix End of Files
         entry: end-of-file-fixer
@@ -34,24 +39,28 @@ repos:
         language: system
         types: [python]
         require_serial: true
-      - id: reorder-python-imports
-        name: Reorder python imports
-        entry: reorder-python-imports
+        args: [--darglint-ignore-regex, .*]
+      - id: isort
+        name: isort
+        entry: isort
+        require_serial: true
+        language: system
+        types_or: [cython, pyi, python]
+        args: ["--filter-files"]
+      - id: pyupgrade
+        name: pyupgrade
+        description: Automatically upgrade syntax for newer versions.
+        entry: pyupgrade
         language: system
         types: [python]
-        args:
-          [
-            --application-directories=src,
-            --py39-plus,
-            --exit-zero-even-if-changed,
-          ]
+        args: [--py37-plus]
       - id: trailing-whitespace
         name: Trim Trailing Whitespace
         entry: trailing-whitespace-fixer
         language: system
         types: [text]
         stages: [commit, push, manual]
-  - repo: https://github.com/prettier/pre-commit
-    rev: v2.1.2
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v2.6.0
     hooks:
       - id: prettier

.readthedocs.yml

@@ -1,9 +1,12 @@
 version: 2
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
 sphinx:
   configuration: docs/conf.py
 formats: all
 python:
-  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - path: .

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[xlorep@darkhelm.org](mailto:xlorep@darkhelm.org).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CODE_OF_CONDUCT.rst

@@ -1,105 +0,0 @@
-Contributor Covenant Code of Conduct
-====================================
-
-Our Pledge
-----------
-
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
-
-
-Our Standards
--------------
-
-Examples of behavior that contributes to a positive environment for our community include:
-
-- Demonstrating empathy and kindness toward other people
-- Being respectful of differing opinions, viewpoints, and experiences
-- Giving and gracefully accepting constructive feedback
-- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
-- Focusing on what is best not just for us as individuals, but for the overall community
-
-Examples of unacceptable behavior include:
-
-- The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-- Trolling, insulting or derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or email
-  address, without their explicit permission
-- Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-Enforcement Responsibilities
-----------------------------
-
-Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
-
-
-Scope
------
-
-This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
-
-
-Enforcement
------------
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at xlorep@darkhelm.org. All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the reporter of any incident.
-
-
-Enforcement Guidelines
-----------------------
-
-Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
-
-
-1. Correction
-~~~~~~~~~~~~~
-
-**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
-
-
-2. Warning
-~~~~~~~~~~
-
-**Community Impact**: A violation through a single incident or series of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
-
-3. Temporary Ban
-~~~~~~~~~~~~~~~~
-
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
-
-4. Permanent Ban
-~~~~~~~~~~~~~~~~
-
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the community.
-
-
-Attribution
------------
-
-This Code of Conduct is adapted from the `Contributor Covenant <homepage_>`__, version 2.0,
-available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
-
-Community Impact Guidelines were inspired by `Mozilla’s code of conduct enforcement ladder <https://github.com/mozilla/diversity>`__.
-
-.. _homepage: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributor Guide
+
+Thank you for your interest in improving this project.
+This project is open-source under the [MIT license] and
+welcomes contributions in the form of bug reports, feature requests, and pull requests.
+
+Here is a list of important resources for contributors:
+
+- [Source Code]
+- [Documentation]
+- [Issue Tracker]
+- [Code of Conduct]
+
+[mit license]: https://opensource.org/licenses/MIT
+[source code]: https://github.com/xlorepdarkhelm/plex-playlist
+[documentation]: https://plex-playlist.readthedocs.io/
+[issue tracker]: https://github.com/xlorepdarkhelm/plex-playlist/issues
+
+## How to report a bug
+
+Report bugs on the [Issue Tracker].
+
+When filing an issue, make sure to answer these questions:
+
+- Which operating system and Python version are you using?
+- Which version of this project are you using?
+- What did you do?
+- What did you expect to see?
+- What did you see instead?
+
+The best way to get your bug fixed is to provide a test case,
+and/or steps to reproduce the issue.
+
+## How to request a feature
+
+Request features on the [Issue Tracker].
+
+## How to set up your development environment
+
+You need Python 3.7+ and the following tools:
+
+- [Poetry]
+- [Nox]
+- [nox-poetry]
+
+Install the package with development requirements:
+
+```console
+$ poetry install
+```
+
+You can now run an interactive Python session,
+or the command-line interface:
+
+```console
+$ poetry run python
+$ poetry run plex-playlist
+```
+
+[poetry]: https://python-poetry.org/
+[nox]: https://nox.thea.codes/
+[nox-poetry]: https://nox-poetry.readthedocs.io/
+
+## How to test the project
+
+Run the full test suite:
+
+```console
+$ nox
+```
+
+List the available Nox sessions:
+
+```console
+$ nox --list-sessions
+```
+
+You can also run a specific Nox session.
+For example, invoke the unit test suite like this:
+
+```console
+$ nox --session=tests
+```
+
+Unit tests are located in the _tests_ directory,
+and are written using the [pytest] testing framework.
+
+[pytest]: https://pytest.readthedocs.io/
+
+## How to submit changes
+
+Open a [pull request] to submit changes to this project.
+
+Your pull request needs to meet the following guidelines for acceptance:
+
+- The Nox test suite must pass without errors and warnings.
+- Include unit tests. This project maintains 100% code coverage.
+- If your changes add functionality, update the documentation accordingly.
+
+Feel free to submit early, though—we can always iterate on this.
+
+To run linting and code formatting checks before committing your change, you can install pre-commit as a Git hook by running the following command:
+
+```console
+$ nox --session=pre-commit -- install
+```
+
+It is recommended to open an issue before starting work on anything.
+This will allow a chance to talk it over with the owners and validate your approach.
+
+[pull request]: https://github.com/xlorepdarkhelm/plex-playlist/pulls
+
+<!-- github-only -->
+
+[code of conduct]: CODE_OF_CONDUCT.md

CONTRIBUTING.rst

@@ -1,123 +0,0 @@
-Contributor Guide
-=================
-
-Thank you for your interest in improving this project.
-This project is open-source under the `MIT license`_ and
-welcomes contributions in the form of bug reports, feature requests, and pull requests.
-
-Here is a list of important resources for contributors:
-
-- `Source Code`_
-- `Documentation`_
-- `Issue Tracker`_
-- `Code of Conduct`_
-
-.. _MIT license: https://opensource.org/licenses/MIT
-.. _Source Code: https://github.com/xlorepdarkhelm/plex-playlist
-.. _Documentation: https://plex-playlist.readthedocs.io/
-.. _Issue Tracker: https://github.com/xlorepdarkhelm/plex-playlist/issues
-
-How to report a bug
--------------------
-
-Report bugs on the `Issue Tracker`_.
-
-When filing an issue, make sure to answer these questions:
-
-- Which operating system and Python version are you using?
-- Which version of this project are you using?
-- What did you do?
-- What did you expect to see?
-- What did you see instead?
-
-The best way to get your bug fixed is to provide a test case,
-and/or steps to reproduce the issue.
-
-
-How to request a feature
-------------------------
-
-Request features on the `Issue Tracker`_.
-
-
-How to set up your development environment
-------------------------------------------
-
-You need Python 3.6+ and the following tools:
-
-- Poetry_
-- Nox_
-- nox-poetry_
-
-Install the package with development requirements:
-
-.. code:: console
-
-   $ poetry install
-
-You can now run an interactive Python session,
-or the command-line interface:
-
-.. code:: console
-
-   $ poetry run python
-   $ poetry run plex-playlist
-
-.. _Poetry: https://python-poetry.org/
-.. _Nox: https://nox.thea.codes/
-.. _nox-poetry: https://nox-poetry.readthedocs.io/
-
-
-How to test the project
------------------------
-
-Run the full test suite:
-
-.. code:: console
-
-   $ nox
-
-List the available Nox sessions:
-
-.. code:: console
-
-   $ nox --list-sessions
-
-You can also run a specific Nox session.
-For example, invoke the unit test suite like this:
-
-.. code:: console
-
-   $ nox --session=tests
-
-Unit tests are located in the ``tests`` directory,
-and are written using the pytest_ testing framework.
-
-.. _pytest: https://pytest.readthedocs.io/
-
-
-How to submit changes
----------------------
-
-Open a `pull request`_ to submit changes to this project.
-
-Your pull request needs to meet the following guidelines for acceptance:
-
-- The Nox test suite must pass without errors and warnings.
-- Include unit tests. This project maintains 100% code coverage.
-- If your changes add functionality, update the documentation accordingly.
-
-Feel free to submit early, though—we can always iterate on this.
-
-To run linting and code formatting checks before commiting your change, you can install pre-commit as a Git hook by running the following command:
-
-.. code:: console
-
-   $ nox --session=pre-commit -- install
-
-It is recommended to open an issue before starting work on anything.
-This will allow a chance to talk it over with the owners and validate your approach.
-
-.. _pull request: https://github.com/xlorepdarkhelm/plex-playlist/pulls
-.. github-only
-.. _Code of Conduct: CODE_OF_CONDUCT.rst

Jenkinsfile

@@ -1,20 +0,0 @@
-pipeline {
-    agent {
-        docker {
-            image 'python:3.10-alpine3.14'
-            args '--rm --name playlist-testing'
-        }
-    }
-    stages {
-        stage('Test') {
-            steps {
-                sh 'echo ${USER}'
-                sh 'set'
-                sh 'pip3 install -U pip'
-                sh 'pip3 install wheel nox nox_poetry poetry'
-                sh 'nox --version'
-                sh 'poetry --version'
-            }
-        }
-    }
-}

LICENSE

@@ -1,7 +1,6 @@
 MIT License
-===========
 
-Copyright © 2021 Cliff Hill
+Copyright © 2023 Cliff Hill
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -13,10 +12,10 @@ 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.**
+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.

README.md

@@ -0,0 +1,73 @@
+# Plex Playlist
+
+[![PyPI](https://img.shields.io/pypi/v/plex-playlist.svg)][pypi_]
+[![Status](https://img.shields.io/pypi/status/plex-playlist.svg)][status]
+[![Python Version](https://img.shields.io/pypi/pyversions/plex-playlist)][python version]
+[![License](https://img.shields.io/pypi/l/plex-playlist)][license]
+
+[![Read the documentation at https://plex-playlist.readthedocs.io/](https://img.shields.io/readthedocs/plex-playlist/latest.svg?label=Read%20the%20Docs)][read the docs]
+[![Tests](https://github.com/xlorepdarkhelm/plex-playlist/workflows/Tests/badge.svg)][tests]
+[![Codecov](https://codecov.io/gh/xlorepdarkhelm/plex-playlist/branch/main/graph/badge.svg)][codecov]
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
+
+[pypi_]: https://pypi.org/project/plex-playlist/
+[status]: https://pypi.org/project/plex-playlist/
+[python version]: https://pypi.org/project/plex-playlist
+[read the docs]: https://plex-playlist.readthedocs.io/
+[tests]: https://github.com/xlorepdarkhelm/plex-playlist/actions?workflow=Tests
+[codecov]: https://app.codecov.io/gh/xlorepdarkhelm/plex-playlist
+[pre-commit]: https://github.com/pre-commit/pre-commit
+[black]: https://github.com/psf/black
+
+## Features
+
+- TODO
+
+## Requirements
+
+- TODO
+
+## Installation
+
+You can install _Plex Playlist_ via [pip] from [PyPI]:
+
+```console
+$ pip install plex-playlist
+```
+
+## Usage
+
+Please see the [Command-line Reference] for details.
+
+## Contributing
+
+Contributions are very welcome.
+To learn more, see the [Contributor Guide].
+
+## License
+
+Distributed under the terms of the [MIT license][license],
+_Plex Playlist_ is free and open source software.
+
+## Issues
+
+If you encounter any problems,
+please [file an issue] along with a detailed description.
+
+## Credits
+
+This project was generated from [@cjolowicz]'s [Hypermodern Python Cookiecutter] template.
+
+[@cjolowicz]: https://github.com/cjolowicz
+[pypi]: https://pypi.org/
+[hypermodern python cookiecutter]: https://github.com/cjolowicz/cookiecutter-hypermodern-python
+[file an issue]: https://github.com/xlorepdarkhelm/plex-playlist/issues
+[pip]: https://pip.pypa.io/
+
+<!-- github-only -->
+
+[license]: https://github.com/xlorepdarkhelm/plex-playlist/blob/main/LICENSE
+[contributor guide]: https://github.com/xlorepdarkhelm/plex-playlist/blob/main/CONTRIBUTING.md
+[command-line reference]: https://plex-playlist.readthedocs.io/en/latest/usage.html

README.rst

@@ -1,99 +0,0 @@
-Automated Daily Playlist Generator for Plex Music
-=================================================
-
-|PyPI| |Python Version| |License|
-
-|Read the Docs| |Tests| |Codecov|
-
-|pre-commit| |Black|
-
-.. |PyPI| image:: https://img.shields.io/pypi/v/plex-playlist.svg
-   :target: https://pypi.org/project/plex-playlist/
-   :alt: PyPI
-.. |Python Version| image:: https://img.shields.io/pypi/pyversions/plex-playlist
-   :target: https://pypi.org/project/plex-playlist
-   :alt: Python Version
-.. |License| image:: https://img.shields.io/pypi/l/plex-playlist
-   :target: https://opensource.org/licenses/MIT
-   :alt: License
-.. |Read the Docs| image:: https://img.shields.io/readthedocs/plex-playlist/latest.svg?label=Read%20the%20Docs
-   :target: https://plex-playlist.readthedocs.io/
-   :alt: Read the documentation at https://plex-playlist.readthedocs.io/
-.. |Tests| image:: https://github.com/xlorepdarkhelm/plex-playlist/workflows/Tests/badge.svg
-   :target: https://github.com/xlorepdarkhelm/plex-playlist/actions?workflow=Tests
-   :alt: Tests
-.. |Codecov| image:: https://codecov.io/gh/xlorepdarkhelm/plex-playlist/branch/main/graph/badge.svg
-   :target: https://codecov.io/gh/xlorepdarkhelm/plex-playlist
-   :alt: Codecov
-.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
-   :target: https://github.com/pre-commit/pre-commit
-   :alt: pre-commit
-.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
-   :target: https://github.com/psf/black
-   :alt: Black
-
-
-Features
---------
-
-* TODO
-
-
-Requirements
-------------
-
-* TODO
-
-
-Installation
-------------
-
-You can install *Automated Daily Playlist Generator for Plex Music* via pip_ from PyPI_:
-
-.. code:: console
-
-   $ pip install plex-playlist
-
-
-Usage
------
-
-Please see the `Command-line Reference <Usage_>`_ for details.
-
-
-Contributing
-------------
-
-Contributions are very welcome.
-To learn more, see the `Contributor Guide`_.
-
-
-License
--------
-
-Distributed under the terms of the `MIT license`_,
-*Automated Daily Playlist Generator for Plex Music* is free and open source software.
-
-
-Issues
-------
-
-If you encounter any problems,
-please `file an issue`_ along with a detailed description.
-
-
-Credits
--------
-
-This project was generated from `@cjolowicz`_'s `Hypermodern Python Cookiecutter`_ template.
-
-.. _@cjolowicz: https://github.com/cjolowicz
-.. _Cookiecutter: https://github.com/audreyr/cookiecutter
-.. _MIT license: https://opensource.org/licenses/MIT
-.. _PyPI: https://pypi.org/
-.. _Hypermodern Python Cookiecutter: https://github.com/cjolowicz/cookiecutter-hypermodern-python
-.. _file an issue: https://github.com/xlorepdarkhelm/plex-playlist/issues
-.. _pip: https://pip.pypa.io/
-.. github-only
-.. _Contributor Guide: CONTRIBUTING.rst
-.. _Usage: https://plex-playlist.readthedocs.io/en/latest/usage.html

backend/docs/codeofconduct.md

@@ -0,0 +1,3 @@
+```{include} ../../CODE_OF_CONDUCT.md
+
+```

backend/docs/conf.py

@@ -0,0 +1,12 @@
+"""Sphinx configuration."""
+project = "Plex Playlist"
+author = "Cliff Hill"
+copyright = "2023, Cliff Hill"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_click",
+    "myst_parser",
+]
+autodoc_typehints = "description"
+html_theme = "furo"

backend/docs/contributing.md

@@ -0,0 +1,7 @@
+```{include} ../../CONTRIBUTING.md
+---
+end-before: <!-- github-only -->
+---
+```
+
+[code of conduct]: codeofconduct

backend/docs/index.md

@@ -0,0 +1,23 @@
+```{include} ../../README.md
+---
+end-before: <!-- github-only -->
+---
+```
+
+[license]: license
+[contributor guide]: contributing
+[command-line reference]: usage
+
+```{toctree}
+---
+hidden:
+maxdepth: 1
+---
+
+usage
+reference
+contributing
+Code of Conduct <codeofconduct>
+License <license>
+Changelog <https://github.com/xlorepdarkhelm/plex-playlist/releases>
+```

backend/docs/license.md

@@ -0,0 +1,7 @@
+# License
+
+```{literalinclude} ../../LICENSE
+---
+language: none
+---
+```

backend/docs/reference.md

@@ -0,0 +1,8 @@
+# Reference
+
+## playlist
+
+```{eval-rst}
+.. automodule:: playlist
+   :members:
+```

backend/docs/requirements.txt

@@ -0,0 +1,4 @@
+furo==2022.4.7
+sphinx==4.5.0
+sphinx-click==4.1.0
+myst_parser==0.17.2

backend/docs/usage.md

@@ -0,0 +1,7 @@
+# Usage
+
+```{eval-rst}
+.. click:: playlist.__main__:main
+    :prog: plex-playlist
+    :nested: full
+```

backend/src/playlist/__init__.py

@@ -0,0 +1 @@
+"""Plex Playlist."""

backend/src/playlist/__main__.py

@@ -1,14 +1,12 @@
 """Command-line interface."""
-import click
 
-from playlist.plex import server
+import click
 
 
 @click.command()
-@click.version_option()  # type: ignore
+@click.version_option()
 def main() -> None:
-    """Automated Daily Playlist Generator for Plex Music."""
-    print(server)
+    """Plex Playlist."""
 
 
 if __name__ == "__main__":

backend/src/playlist/enums.py

@@ -0,0 +1,53 @@
+"""All enums for the project are kept here."""
+
+from enum import StrEnum
+from enum import auto
+from typing import Generator
+
+
+class Sublist(StrEnum):
+    """StrEnum to categorize tracks within a playlist based on various criteria.
+
+    Values are auto-generated.
+
+    Attributes:
+        LEAST_RECENTLY_ADDED: Represents tracks that were added to the library the earliest.
+        LEAST_RECENTLY_PLAYED: Represents tracks that were last played the longest time ago.
+        LEAST_OFTEN_PLAYED: Represents tracks that have been played the least often.
+        RANDOM: Represents tracks that are selected randomly.
+    """
+
+    LEAST_RECENTLY_ADDED = auto()
+    LEAST_RECENTLY_PLAYED = auto()
+    LEAST_OFTEN_PLAYED = auto()
+    RANDOM = auto()
+
+    def standard(self) -> Generator["Sublist", None, None]:
+        """Generate the standard sublist types one at a time."""
+        yield self.LEAST_RECENTLY_ADDED
+        yield self.LEAST_RECENTLY_PLAYED
+        yield self.LEAST_OFTEN_PLAYED
+
+
+class TimedEvent(StrEnum):
+    """Enumerates the start/end for timed processes like updater.
+
+    Attributes:
+        START: Represents the start of the event.
+        END: Represents the end of the event.
+    """
+
+    START = auto()
+    END = auto()
+
+
+class Event(StrEnum):
+    """Enumerates the major backend events that are run.
+
+    Attributes:
+        UPDATER: Represents the track updater process.
+        GENERATOR: Represents the playlist generator process.
+    """
+
+    UPDATER: auto()
+    GENERATOR: auto()

backend/src/playlist/env.py

@@ -0,0 +1,30 @@
+"""Environment variables used throughout the application."""
+
+import os
+
+from dotenv import load_dotenv
+
+
+load_dotenv()  # Take environment variables from .env.
+
+PLEX_SERVER_URL = os.getenv("PLEX_SERVER_URL", "http://default-plex-server-url")
+PLEX_TOKEN = os.getenv("PLEX_TOKEN", "default-plex-token")
+
+DATABASE_URL = os.getenv(
+    "DATABASE_URL", "postgres://user:password@localhost/database"
+)  # Default fallback
+
+MAX_TRACKS_QUERIED = int(
+    os.getenv("MAX_TRACKS_QUERIED", 1000)
+)  # Default to 1000 if not set
+
+MAX_PLAYTIME = (
+    int(os.getenv("MAX_PLAYTIME", 16)) * 60 * 60
+)  # In seconds, but env var is in hours.
+
+PODCAST_DAYS = os.getenv("PODCAST_DAYS")
+
+SSH_USER = os.getenv("SSH_USER")
+SSH_SERVER = os.getenv("SSH_SERVER")
+SSH_PATH = os.getenv("SSH_PATH")
+SSH_KEY_PATH = os.getenv("SSH_KEY_PATH")

backend/src/playlist/models.py

@@ -0,0 +1,405 @@
+"""All database models are defined here."""
+
+from datetime import datetime
+
+from playlist import enums
+from sqlalchemy import Boolean
+from sqlalchemy import Column
+from sqlalchemy import DateTime
+from sqlalchemy import Enum
+from sqlalchemy import Float
+from sqlalchemy import ForeignKey
+from sqlalchemy import Integer
+from sqlalchemy import String
+from sqlalchemy import Table
+from sqlalchemy import UniqueConstraint
+from sqlalchemy import func
+from sqlalchemy.orm import Mapped
+from sqlalchemy.orm import mapped_column
+from sqlalchemy.orm import registry
+from sqlalchemy.orm import relationship
+
+
+# Registry initialization using SQLAlchemy's new ORM 2.0 style
+mapper_registry = registry()
+
+holiday_track_association = Table(
+    "holiday_track_association",
+    mapper_registry.metadata,
+    Column("holiday_id", ForeignKey("holidays.id"), primary_key=True),
+    Column("track_id", ForeignKey("tracks.id"), primary_key=True),
+)
+
+
+@mapper_registry.mapped_as_dataclass
+class User:
+    """Represents a system user, capable of owning a single playlist.
+
+    Attributes:
+        id (int): Unique identifier for the user.
+        username (str): Unique username for the user.
+
+    Relationships:
+        playlist (Playlist): The playlist owned by the user, one-to-one relationship.
+    """
+
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    username: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    playlist: Mapped["Playlist"] = relationship(
+        "Playlist", back_populates="owner", uselist=False
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class Playlist:
+    """Represents a playlist containing multiple unique tracks, owned by a user.
+
+    Attributes:
+        id (int): Unique identifier for the playlist.
+        name (str): Name of the playlist.
+        owner (User): The user who owns the playlist, one-to-one relationship.
+
+    Relationships:
+        tracks (list[Track]): List of tracks in the playlist, many-to-many relationship.
+    """
+
+    __tablename__ = "playlists"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    owner_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+    owner: Mapped[User] = relationship("User", back_populates="playlist")
+    playlist_tracks: Mapped[list["PlaylistTrack"]] = relationship(
+        "PlaylistTrack", back_populates="playlist"
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class PlaylistTrack:
+    """Represents an entry in a playlist that associates a track with additional context.
+
+    Each playlist track is tied to exactly one track and optionally linked to a category,
+    a holiday, or a podcast episode. The playlist track can also categorize the track
+    as part of a specific sublist based on how the track was added to the playlist.
+
+    Attributes:
+        id (int): The primary key for the playlist track.
+        track_id (int): The foreign key linked to the track's primary key.
+        category_id (int, optional): The foreign key linked to the category's primary key, nullable.
+        holiday_id (int, optional): The foreign key linked to the holiday's primary key, nullable.
+        episode_id (int, optional): The foreign key linked to the podcast episode's primary
+            key, nullable.
+        favorite (bool, optional): Flag to indicate if the track is marked as a favorite, nullable.
+        sublist (SublistType, optional): The type of sublist the track belongs to, nullable.
+
+    Relationships:
+        track (Track): The track associated with this playlist track.
+        category (Category, optional): The category associated with this playlist track, nullable.
+        holiday (Holiday, optional): The holiday associated with this playlist track, nullable.
+        episode (Episode, optional): The podcast episode associated with this playlist
+            track, nullable.
+
+    Constraints:
+        At least one of `category_id`, `holiday_id`, or `episode_id` must be non-null.
+        Fields `favorite` and `sublist` must be null if `episode_id` is not null.
+    """
+
+    __tablename__ = "playlist_tracks"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    playlist_id: Mapped[int] = mapped_column(ForeignKey("playlists.id"), nullable=False)
+    track_id: Mapped[int] = mapped_column(ForeignKey("tracks.id"), nullable=False)
+    category_id: Mapped[int] = mapped_column(ForeignKey("categories.id"), nullable=True)
+    holiday_id: Mapped[int] = mapped_column(ForeignKey("holidays.id"), nullable=True)
+    episode_id: Mapped[int] = mapped_column(ForeignKey("episodes.id"), nullable=True)
+    favorite: Mapped[bool] = mapped_column(Boolean, nullable=True)
+    sublist: Mapped[str] = mapped_column(Enum(enums.Sublist), nullable=True)
+
+    playlist: Mapped["Playlist"] = relationship("Playlist")
+    track: Mapped["Track"] = relationship("Track")
+    category: Mapped["Category"] = relationship("Category")
+    holiday: Mapped["Holiday"] = relationship("Holiday")
+    episode: Mapped["Episode"] = relationship("Episode")
+
+    __table_args__ = (
+        # Check constraint to ensure one of the category, holiday, or episode must be not null
+        {
+            "sqlite_with_rowid": False,
+            "postgresql_where": (
+                (
+                    category_id.is_not(None)
+                    | holiday_id.is_not(None)
+                    | episode_id.is_not(None)
+                )
+                & (episode_id.is_not(None) & favorite.is_(None) & sublist.is_(None))
+            ),
+        }
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class Track:
+    """Represents a musical track with comprehensive metadata.
+
+    Attributes:
+        id (int): Unique identifier for the track.
+        title (str): Title of the track.
+        artist (str): Artist of the track.
+        album (str): Album name.
+        cover_image (str): URL or path to the album cover image.
+        duration (int): Duration of the track in seconds.
+        times_played (int): Number of times the track has been played.
+        date_last_played (DateTime): Date the track was last played.
+        date_added (DateTime): Date the track was added to the database.
+        rating (float): Rating of the track on a 1-5 scale.
+        genre_id (int): ForeignKey linking to the genre.
+        category_id (int): Foreign key linking to the category.
+        server_id (str): Identifier for the server where the track is hosted, indexed.
+
+    Relationships:
+        genre (Genre): The genre for this track.
+        playlist_tracks (list[PlaylistTrack]): List of playlist tracks for this track.
+        category (Category): The category for this track.
+        holidays (list[Holiday]): The list of holidays this track is assigned to.
+        podcast_episode (Episode | None): The optional podcast episode this track is linked to.
+    """
+
+    __tablename__ = "tracks"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    artist: Mapped[str] = mapped_column(String(255), nullable=False)
+    album: Mapped[str] = mapped_column(String(255), nullable=False)
+    cover_image: Mapped[str] = mapped_column(String(255))
+    duration: Mapped[int] = mapped_column(Integer)
+    times_played: Mapped[int] = mapped_column(Integer, default=0)
+    date_last_played: Mapped[DateTime] = mapped_column(DateTime)
+    date_added: Mapped[DateTime] = mapped_column(DateTime, default=func.now())
+    rating: Mapped[float] = mapped_column(Float)
+    genre_id: Mapped[int] = mapped_column(ForeignKey("genres.id"))
+    category_id: Mapped[int] = mapped_column(ForeignKey("categories.id"))
+    server_id: Mapped[str] = mapped_column(
+        String(255), nullable=False, index=True, unique=True
+    )
+
+    genre: Mapped["Genre"] = relationship("Genre", back_populates="tracks")
+    category: Mapped["Category"] = relationship("Category", back_populates="tracks")
+    holidays: Mapped[list["Holiday"]] = relationship(
+        "Holiday", secondary=holiday_track_association, back_populates="tracks"
+    )
+    playlist_tracks: Mapped[list["PlaylistTrack"]] = relationship(
+        "PlaylistTrack", back_populates="track"
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class Genre:
+    """Represents a music genre.
+
+    Each genre can be associated with multiple tracks and belongs to exactly one category.
+
+    Attributes:
+        id (int): Primary key.
+        name (str): Name of the genre, which is unique within the same category.
+        category_id (int): Foreign key linking to the category the genre belongs to.
+        category (Category): The category this genre is part of.
+
+    Relationships:
+        tracks (list[Track]): List of tracks associated with this genre.
+    """
+
+    __tablename__ = "genres"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    category_id: Mapped[int] = mapped_column(ForeignKey("categories.id"))
+    category: Mapped["Category"] = relationship("Category", back_populates="genres")
+    tracks: Mapped[list["Track"]] = relationship("Track", back_populates="genre")
+
+    __table_args__ = (
+        UniqueConstraint("name", "category_id", name="uix_genre_name_category_id"),
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class Category:
+    """Represents a category of music that can encompass multiple genres.
+
+    Each category can include various genres, providing a way to classify tracks into different
+    musical styles or themes.
+
+    Attributes:
+        id (int): Primary key.
+        name (str): Unique name of the category.
+
+    Relationships:
+        genres (list[Genre]): List of genres associated with this category.
+    """
+
+    __tablename__ = "categories"
+    __sa_dataclass_metadata_key__ = "sa"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    genres: Mapped[list["Genre"]] = relationship("Genre", back_populates="category")
+    tracks: Mapped[list["Track"]] = relationship("Track", back_populates="category")
+
+
+@mapper_registry.mapped_as_dataclass
+class Holiday:
+    """Represents a holiday, which can be linked to specific tracks for special occasions.
+
+    Attributes:
+        id (Mapped[int]): The primary key.
+        name (Mapped[str]): The name of the holiday.
+        start_date (Mapped[DateTime]): The starting date of the holiday.
+        end_date (Mapped[DateTime]): The ending date of the holiday.
+        is_active (property): A calculated property that checks if the holiday is currently active.
+
+    Relationships:
+        tracks (Mapped[list[Track]]): List of tracks associated with this holiday.
+    """
+
+    __tablename__ = "holidays"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    start_date: Mapped[DateTime] = mapped_column(DateTime, nullable=False)
+    end_date: Mapped[DateTime] = mapped_column(DateTime, nullable=False)
+    tracks: Mapped[list[Track]] = relationship(
+        "Track", secondary=holiday_track_association, back_populates="holidays"
+    )
+
+    @property
+    def is_active(self) -> bool:
+        """Calculate whether the holiday is currently active based on the system's current date.
+
+        This does not use the database but computes based on the current datetime.
+        """
+        return self.start_date <= datetime.now() <= self.end_date
+
+
+@mapper_registry.mapped_as_dataclass
+class Podcast:
+    """Represents a podcast, which consists of multiple episodes.
+
+    Attributes:
+        id (Mapped[int]): The primary key.
+        name (Mapped[str]): The name of the podcast.
+        feed_url (Mapped[str]): The URL of the podcast's RSS feed.
+
+    Relationships:
+        episodes (Mapped[list[Episode]]): List of episodes associated with this podcast.
+    """
+
+    __tablename__ = "podcasts"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    feed_url: Mapped[str] = mapped_column(String(255), nullable=False)
+    episodes: Mapped[list["Episode"]] = relationship(
+        "Episode", back_populates="podcast"
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class Episode:
+    """Represents an episode of a podcast.
+
+    Attributes:
+        id (Mapped[int]): The primary key.
+        name (Mapped[str]): The title of the episode.
+        filename (Mapped[str]): The filename of the episode's media file.
+        podcast_id (Mapped[int]): Foreign key linking to the associated podcast.
+        server_id (Mapped[str | None]): Identifier for the server where the episode is hosted, indexed.
+        date_published (Mapped[datetime]): The publication date of the episode in the podcast feed.
+        track_id (Mapped[int | None]): Optional foreign key linking to the associated track.
+
+    Relationships:
+        podcast (Mapped[Podcast]): The podcast this episode belongs to.
+        track (Mapped[Track | None]): Optional relation to the track from the plex server.
+    """
+
+    __tablename__ = "episodes"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    filename: Mapped[str] = mapped_column(String(255), nullable=False)
+    podcast_id: Mapped[int] = mapped_column(ForeignKey("podcasts.id"))
+    server_id: Mapped[str | None] = mapped_column(
+        String(255), nullable=True, index=True, unique=True
+    )
+    date_published: Mapped[datetime] = mapped_column(datetime, nullable=False)
+    track_id: Mapped[int | None] = mapped_column(ForeignKey("tracks.id"), nullable=True)
+
+    podcast: Mapped[Podcast] = relationship("Podcast", back_populates="episodes")
+    track: Mapped[Track | None] = relationship(
+        "Track", back_populates="podcast_episode"
+    )
+
+
+@mapper_registry.mapped_as_dataclass
+class Statistics:
+    """Stores various computed statistics and operational metrics for the application.
+
+    Attributes:
+        id (Mapped[int]): The primary key.
+        average_track_length (Mapped[float]): The average length of tracks in seconds.
+        total_podcast_length (Mapped[float]): The total length of all podcast episodes in seconds.
+        max_playtime (Mapped[float]): The maximum playtime after accounting for podcasts, in seconds.
+        max_tracks_per_day (Mapped[int]): The maximum number of tracks that can be played in a day.
+        active_holiday_count (Mapped[int]): The number of active holidays affecting today's playlist.
+        category_count (Mapped[int]): The number of categories affecting today's playlist.
+        max_holiday_tracks (Mapped[int]): The maximum number of tracks that can be allocated to holidays.
+        max_regular_tracks (Mapped[int]): The maximum number of regular tracks per day.
+        max_regular_favorite_tracks (Mapped[int]): The maximum number of favorite tracks per day.
+        max_holiday_favorite_tracks (Mapped[int]): The maximum number of favorite tracks that can be
+            allocated to holidays.
+        max_regular_general_tracks (Mapped[int]): The maximum number of general tracks per day.
+        max_holiday_general_tracks (Mapped[int]): The maximum number of general tracks that can be
+            allocated to holidays.
+        max_regular_favorite_base (Mapped[int]): The maximum number of favorite tracks in one sublist.
+        max_regular_general_base (Mapped[int]): The maximum number of general tracks in one sublist.
+        max_holiday_favorite_base (Mapped[int]): The maximum number of favorite tracks in one sublist
+            for holidays.
+        max_holiday_general_base (Mapped[int]): The maximum number of general tracks in one sublist for
+            holidays.
+        start_update (Mapped[DateTime]): The timestamp when track updates begin.
+        end_update (Mapped[DateTime]): The timestamp when track updates end.
+        start_playlist_gen (Mapped[DateTime]): The timestamp when the playlist generation begins.
+        end_playlist_gen (Mapped[DateTime]): The timestamp when the playlist generation ends.
+    """
+
+    __tablename__ = "statistics"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    average_track_length: Mapped[float] = mapped_column(Float)
+    total_podcast_length: Mapped[float] = mapped_column(Float)
+    max_playtime: Mapped[float] = mapped_column(Float)
+    max_tracks_per_day: Mapped[int] = mapped_column(Integer)
+    active_holiday_count: Mapped[int] = mapped_column(Integer)
+    category_count: Mapped[int] = mapped_column(Integer)
+    max_holiday_tracks: Mapped[int] = mapped_column(Integer)
+    max_regular_tracks: Mapped[int] = mapped_column(Integer)
+    max_regular_favorite_tracks: Mapped[int] = mapped_column(Integer)
+    max_regular_general_tracks: Mapped[int] = mapped_column(Integer)
+    max_holiday_favorite_tracks: Mapped[int] = mapped_column(Integer)
+    max_holiday_general_tracks: Mapped[int] = mapped_column(Integer)
+    max_regular_favorite_base: Mapped[int] = mapped_column(Integer)
+    max_regular_general_base: Mapped[int] = mapped_column(Integer)
+    max_holiday_favorite_base: Mapped[int] = mapped_column(Integer)
+    max_holiday_general_base: Mapped[int] = mapped_column(Integer)
+    start_update: Mapped[DateTime | None] = mapped_column(
+        DateTime, nullable=True, server_default=None
+    )
+    end_update: Mapped[DateTime | None] = mapped_column(
+        DateTime, nullable=True, server_default=None
+    )
+    start_playlist_gen: Mapped[DateTime | None] = mapped_column(
+        DateTime, nullable=True, server_default=None
+    )
+    end_playlist_gen: Mapped[DateTime | None] = mapped_column(
+        DateTime, nullable=True, server_default=None
+    )

backend/src/playlist/playlist_generator.py

@@ -0,0 +1,204 @@
+"""Contains the functions that are used to generate the playlist."""
+
+import asyncio
+
+from aiologger import Logger
+from playlist import enums
+from playlist import sql
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+logger = Logger.with_default_handlers()
+
+
+async def generate_sublists(
+    session: AsyncSession,
+    playlist_entries: set[int],
+    sublist_counts: dict[enums.Sublist, int],
+    is_category: bool,
+    type_id: int,
+    is_favorite: bool,
+    base_count: int,
+    max_count: int,
+) -> None:
+    """Generate sublists for a given category and type (favorites or general).
+
+    Args:
+        session (AsyncSession): The database session.
+        playlist_entries (set[int]): The set of track IDs in the playlist.
+        sublist_counts (dict[enums.Sublist, int]): The counts of existing tracks in the
+            given sublist in the current playlist.
+        is_category (bool): True if it is a category, false if it is a holiday.
+        type_id (int): The category or holiday ID for which to generate playlists.
+        is_favorite (bool): True for favorites only, False for general tracks.
+        base_count (int): The base number of tracks to be included from regular sublists.
+        max_count (int): The max number of tracks to be included from regular sublists.
+    """
+    for sublist in enums.Sublist.standard():
+        existing_count = sublist_counts.get(sublist, 0)
+        allowed_count = base_count - existing_count
+        tracks = await sql.fetch_tracks_for_sublist(
+            session,
+            is_category,
+            type_id,
+            is_favorite,
+            sublist,
+            allowed_count,
+            playlist_entries,
+        )
+        for track in tracks:
+            await sql.insert_into_playlist(
+                session, is_category, type_id, track.id, sublist, is_favorite
+            )
+            playlist_entries.add(track.id)
+
+    # Calculate how many tracks to randomly add
+    remaining_count = max_count - len(playlist_entries)
+    if remaining_count > 0:
+        await generate_random_sublist(
+            session,
+            playlist_entries,
+            sublist_counts.get(enums.Sublist.RANDOM, 0),
+            type_id,
+            is_favorite,
+            remaining_count,
+        )
+
+
+async def generate_random_sublist(
+    session: AsyncSession,
+    playlist_entries: set[int],
+    existing_count: int,
+    is_category: bool,
+    type_id: int,
+    is_favorite: bool,
+    count: int,
+) -> None:
+    """Generate random sublist for the remaining slots in the playlist.
+
+    Args:
+        session (AsyncSession): The database session.
+        playlist_entries (set[int]): The set of track IDs in the playlist.
+        existing_count (int): The number of random tracks already existing in the playlist.
+        is_category (bool): True if it is a category, false if it is a holiday.
+        type_id (int): The category or holiday ID for which to generate the random sublist.
+        is_favorite (bool): True for favorites only, False for general tracks.
+        count (int): Number of random tracks to add.
+        existing_entries (set): Set of track IDs already added to avoid duplicates.
+    """
+    allowed_count = count - existing_count
+    random_tracks = await sql.fetch_tracks_for_sublist(
+        session,
+        type_id,
+        is_favorite,
+        enums.Sublist.RANDOM,
+        count,
+        allowed_count,
+        playlist_entries,
+    )
+    for track in random_tracks:
+        await sql.insert_into_playlist(
+            session, type_id, track.id, enums.Sublist.RANDOM, is_favorite
+        )
+        playlist_entries.add(track.id)
+        if len(playlist_entries) >= count:
+            break
+
+
+async def process_playlists(
+    playlist_entries: set[int],
+    playlist_counts: dict[tuple[bool, int, bool, enums.Sublist], int],
+    is_category: bool,
+    type_id: int,
+    favorite_base: int,
+    general_base: int,
+    favorite_max: int,
+    general_max: int,
+) -> None:
+    """Process playlists for both favorites and general tracks for a given category or holiday.
+
+    Args:
+        playlist_entries (set[int]): The IDs of the tracks currently in the playlist.
+        playlist_counts (dict[tuple[bool, int, bool, enums.Sublist], int]): Counts of the
+            different sublist types within the playlist.
+        is_category (bool): True if it is a category, false if it is a holiday.
+        type_id (int): The category or holiday ID for which to generate the random sublist.
+        favorite_base (int): The maximum number of tracks for a favorite standard sublist.
+        general_base (int): The maximum number of tracks for a general standard sublist.
+        favorite_max (int): The maximum number of tracks for favorite tracks.
+        general_max (int): The maximum number of tracks for general tracks.
+    """
+    async with sql.async_session_maker() as session:
+        favorite_counts = {
+            key[3]: count
+            for key, count in playlist_counts.items()
+            if key[0] is is_category and key[1] == type_id and key[2] is True
+        }
+        general_counts = {
+            key[3]: count
+            for key, count in playlist_counts.items()
+            if key[0] is is_category and key[1] == type_id and key[2] is False
+        }
+        await generate_sublists(
+            session,
+            playlist_entries,
+            favorite_counts,
+            is_category,
+            type_id,
+            True,
+            favorite_base,
+            favorite_max,
+        )
+        await generate_sublists(
+            session,
+            playlist_entries,
+            general_counts,
+            is_category,
+            type_id,
+            False,
+            general_base,
+            general_max,
+        )
+
+
+async def generate_playlist_for_all() -> None:
+    """Generate playlists for all categories & holidays."""
+    (
+        existing_track_ids,
+        existing_playlist_counts,
+    ) = await sql.get_existing_playlist_track_info()
+    category_ids = tuple(await sql.gen_all_category_ids())
+    holiday_ids = tuple(sql.gen_active_holiday_ids())
+    stats = await sql.get_statistics()
+    category_favorite_base = stats.max_regular_favorite_base
+    category_general_base = stats.max_regular_general_base
+    category_favorite_max = stats.max_regular_favorite_tracks
+    category_general_max = stats.max_regular_general_tracks
+    holiday_favorite_base = stats.max_holiday_favorite_base
+    holiday_general_base = stats.max_holiday_general_base
+    holiday_favorite_max = stats.max_holiday_favorite_tracks
+    holiday_general_max = stats.max_holiday_general_tracks
+    tasks = [
+        process_playlists(
+            playlist_entries=existing_track_ids,
+            playlist_counts=existing_playlist_counts,
+            is_category=True,
+            type_id=category_id,
+            favorite_base=category_favorite_base,
+            general_base=category_general_base,
+            favorite_max=category_favorite_max,
+            general_max=category_general_max,
+        )
+        for category_id in category_ids
+    ] + [
+        process_playlists(
+            is_category=False,
+            type_id=holiday_id,
+            favorite_base=holiday_favorite_base,
+            general_base=holiday_general_base,
+            favorite_max=holiday_favorite_max,
+            general_max=holiday_general_max,
+        )
+        for holiday_id in holiday_ids
+    ]
+    await asyncio.gather(*tasks)

backend/src/playlist/plex.py

@@ -0,0 +1,90 @@
+"""Contains all plex code here."""
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from typing import AsyncGenerator
+
+import env  # Make sure to import your environment configuration
+from aiologger import Logger
+from plexapi.server import PlexServer
+
+
+logger = Logger.with_default_handlers(name="plex_logger")
+executor = ThreadPoolExecutor()
+
+
+async def fetch_tracks_from_plex(
+    server_url: str = env.PLEX_SERVER_URL, token: str = env.PLEX_TOKEN
+) -> AsyncGenerator[dict, None]:
+    """Asynchronously fetches tracks from a Plex server.
+
+    Uses plexapi, employing a ThreadPoolExecutor to handle blocking calls from plexapi.
+
+    Args:
+        server_url (str): URL of the Plex server, defaults to environment variable.
+        token (str): Authentication token for accessing the Plex server, defaults to environment variable.
+
+    Yields:
+        AsyncGenerator[Dict, None]: An asynchronous generator yielding track data dictionaries.
+    """
+    try:
+        # Initialize Plex server connection using plexapi in a non-blocking way
+        plex = await asyncio.get_event_loop().run_in_executor(
+            executor, lambda: PlexServer(server_url, token)
+        )
+
+        # Fetch all music sections asynchronously
+        sections = await asyncio.get_event_loop().run_in_executor(
+            executor, plex.library.sections
+        )
+        music_section = next(
+            (section for section in sections if section.type == "artist"), None
+        )
+
+        if not music_section:
+            await logger.error("No music section found on the Plex server.")
+            return
+
+        # Asynchronously fetch tracks by paging through the music section
+        total_tracks = await asyncio.get_event_loop().run_in_executor(
+            executor, music_section.totalSize
+        )
+        size = env.MAX_TRACKS_QUERIED  # Maximum number of tracks to query at once
+
+        for offset in range(0, total_tracks, size):
+            tracks = await asyncio.get_event_loop().run_in_executor(
+                executor,
+                lambda offset=offset, size=size: music_section.searchTracks(
+                    container_start=offset, container_size=size
+                ),
+            )
+            for track in tracks:
+                track_data = {
+                    "title": track.title,
+                    "artist": (
+                        track.grandparentTitle
+                        if track.grandparentTitle
+                        else "Unknown Artist"
+                    ),
+                    "album": (
+                        track.parentTitle if track.parentTitle else "Unknown Album"
+                    ),
+                    "cover_image": track.thumbUrl if track.thumbUrl else "",
+                    "duration": track.duration,
+                    "times_played": getattr(track, "userRatingCount", 0),
+                    "date_last_played": (
+                        track.lastViewedAt.isoformat() if track.lastViewedAt else None
+                    ),
+                    "date_added": track.addedAt.isoformat(),
+                    "rating": getattr(track, "userRating", None),
+                    "genre": (
+                        ", ".join(genre.tag for genre in track.genres)
+                        if track.genres
+                        else "Unknown"
+                    ),
+                    "server_id": track.ratingKey,  # Using Plex track ratingKey as the server_id
+                }
+                yield track_data
+    except Exception as e:
+        await logger.error(f"Failed to fetch tracks from Plex: {e}")
+        raise

backend/src/playlist/podcast.py

@@ -0,0 +1,190 @@
+"""Podcast processing/updating contained here."""
+
+import asyncio
+import tempfile
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+from datetime import timedelta
+
+import asyncpathlib
+import asyncssh
+import eyed3
+import feedparser
+from aiologger import Logger
+from env import PODCAST_DAYS
+from env import SSH_KEY_PATH
+from env import SSH_PATH
+from env import SSH_SERVER
+from env import SSH_USER
+from models import Episode
+from models import Podcast
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.future import select
+
+
+logger = Logger.with_default_handlers()
+
+
+async def fetch_and_process_podcasts(session: AsyncSession):
+    """Asynchronously fetches all podcasts from the database and processes each one.
+
+    Args:
+        session (AsyncSession): The database session to use for querying.
+    """
+    podcasts = await session.execute(select(Podcast))
+    tasks = [process_podcast(podcast, session) for podcast in podcasts.scalars().all()]
+    await asyncio.gather(*tasks)
+
+
+async def process_podcast(podcast: Podcast, session: AsyncSession):
+    """Processes each podcast.
+
+    By parsing its feed, checking for new episodes, downloading,
+    modifying, uploading, and saving them.
+
+    Args:
+        podcast (Podcast): A podcast object containing metadata.
+        session (AsyncSession): The database session to use for ORM operations.
+    """
+    feed = feedparser.parse(podcast.url)
+    threshold_date = datetime.now() - timedelta(days=PODCAST_DAYS)
+    for entry in feed.entries:
+        if datetime(*entry.published_parsed[:6]) > threshold_date:
+            if not await episode_exists(session, entry.title, podcast.id):
+                episode_path = await download_episode(entry)
+                if episode_path:
+                    await modify_id3_tags(episode_path, entry.title, podcast.name)
+                    await upload_episode(episode_path, podcast.name)
+                    await save_episode(session, entry, podcast.id, episode_path)
+
+
+async def episode_exists(
+    session: AsyncSession, episode_name: str, podcast_id: int
+) -> bool:
+    """Determines whether an episode already exists in the database.
+
+    Args:
+        session (AsyncSession): The database session.
+        episode_name (str): The name of the episode to check.
+        podcast_id (int): The ID of the podcast to check against.
+
+    Returns:
+        bool: True if the episode exists, False otherwise.
+    """
+    result = await session.execute(
+        select(Episode).where(
+            Episode.name == episode_name, Episode.podcast_id == podcast_id
+        )
+    )
+    return result.scalar() is not None
+
+
+async def download_episode(entry):
+    """Download an episode's audio file to a temporary location based on its feed entry.
+
+    Args:
+        entry (FeedParserDict): A single episode entry from the parsed feed.
+
+    Returns:
+        asyncpathlib.Path: Path to the downloaded file, or None if the download fails.
+    """
+    temp_dir = tempfile.TemporaryDirectory()
+    episode_path = (
+        asyncpathlib.Path(temp_dir.name) / f"{entry.title.replace('/', '-')}.mp3"
+    )
+    try:
+        audio_url = entry.enclosures[0].href
+        content = await fetch_content(audio_url)
+        await episode_path.write_bytes(content)
+        return episode_path
+    except Exception as e:
+        logger.error(f"Failed to download episode {entry.title}: {e}")
+        return None
+
+
+async def fetch_content(url: str) -> bytes:
+    """Fetch content from a URL asynchronously.
+
+    Args:
+        url (str): The URL from which to fetch the content.
+
+    Returns:
+        bytes: The content fetched from the URL.
+    """
+    import aiohttp
+
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.read()
+
+
+async def modify_id3_tags(file_path: asyncpathlib.Path, title: str, album: str):
+    """Modify the ID3 tags of a downloaded audio file asynchronously using eyed3.
+
+    Args:
+        file_path (asyncpathlib.Path): The path to the audio file.
+        title (str): The title to set in the ID3 tags.
+        album (str): The album name to set in the ID3 tags.
+    """
+    executor = ThreadPoolExecutor()
+    loop = asyncio.get_running_loop()
+    await loop.run_in_executor(executor, lambda: _edit_tags(file_path, title, album))
+
+
+def _edit_tags(file_path, title, album):
+    """Helper function to modify ID3 tags using eyed3, called within a ThreadPoolExecutor.
+
+    Args:
+        file_path (asyncpathlib.Path): The path to the file.
+        title (str): The title to apply to the ID3 tags.
+        album (str): The album name to apply to the ID3 tags.
+    """
+    audiofile = eyed3.load(str(file_path))
+    if audiofile.tag is None:
+        audiofile.initTag()
+    audiofile.tag.title = title
+    audiofile.tag.album = album
+    audiofile.tag.genre = "Podcast"
+    audiofile.tag.save()
+
+
+async def upload_episode(file_path: asyncpathlib.Path, podcast_name: str):
+    """Asynchronously uploads an episode file to a remote server using SCP.
+
+    Args:
+        file_path (asyncpathlib.Path): The path to the episode file.
+        podcast_name (str): The name of the podcast, used to organize files on the server.
+    """
+    remote_path = f"{SSH_PATH}/{podcast_name}/{file_path.name}"
+    try:
+        async with asyncssh.connect(
+            host=SSH_SERVER, username=SSH_USER, client_keys=[SSH_KEY_PATH]
+        ) as conn:
+            await conn.run(f"mkdir -p {SSH_PATH}/{podcast_name}", check=True)
+            await asyncssh.scp(str(file_path), (conn, remote_path))
+            logger.info(f"Successfully uploaded {file_path} to {remote_path}")
+    except Exception as e:
+        logger.error(f"Error uploading file {file_path} to {remote_path}: {e}")
+        raise
+
+
+async def save_episode(
+    session: AsyncSession, entry, podcast_id: int, episode_path: asyncpathlib.Path
+):
+    """Save the details of a new podcast episode to the database after it has been processed.
+
+    Args:
+        session (AsyncSession): The database session.
+        entry (FeedParserDict): The parsed feed entry.
+        podcast_id (int): The ID of the podcast.
+        episode_path (asyncpathlib.Path): The path to the downloaded and processed episode file.
+    """
+    new_episode = Episode(
+        podcast_id=podcast_id,
+        name=entry.title,
+        filename=str(episode_path),
+        date_published=datetime(*entry.published_parsed[:6]),
+    )
+    session.add(new_episode)
+    await session.commit()
+    logger.info(f"New episode saved: {entry.title}")

backend/src/playlist/sql.py

@@ -0,0 +1,677 @@
+"""Contains all SQL code here."""
+
+import collections
+import contextlib
+import functools
+import inspect
+from collections.abc import AsyncGenerator
+from collections.abc import Coroutine
+from datetime import datetime
+from typing import Any
+from typing import Protocol
+
+import aiologger
+import sqlalchemy
+import sqlalchemy.orm
+from playlist import enums
+from playlist import env
+from playlist import models
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.ext.asyncio import create_async_engine
+
+
+# Initialize asynchronous logger
+logger = aiologger.Logger.with_default_handlers(name=__name__)
+
+# Create an asynchronous SQLAlchemy engine
+_engine = create_async_engine(env.DATABASE_URL, echo=True)
+
+# Create a session maker for asynchronous sessions
+_async_session_maker = sqlalchemy.orm.sessionmaker(
+    _engine, class_=AsyncSession, expire_on_commit=False
+)
+
+
+class Sessionizable(Protocol):
+    """Protocol defining the signature of a sessionizable function."""
+
+    def __call__(
+        self,
+        *args: tuple[Any, ...],
+        session: AsyncSession | None = None,
+        **kwargs: dict[str, Any],
+    ) -> (AsyncGenerator, Coroutine):
+        """The signature for a sessionizable function.
+
+        Args:
+            args: The positional arguments for the function.
+            kwargs: The keyword arguments for the function (except for session).
+
+        Keyword Args:
+            session: The database session. If set to None, this will be filled with a new session.
+
+        Returns:
+            (AsyncGenerator, Coroutine): The async generator or
+            coroutine that would be created by this function.
+        """
+        ...
+
+
+@contextlib.asynccontextmanager
+async def _db_logger(
+    func_name: str, session: AsyncSession
+) -> AsyncGenerator[None, None]:
+    """Asynchronous context manager for logging database errors and handling rollbacks.
+
+    This context manager logs SQLAlchemy-specific exceptions and other exceptions that occur during
+    the execution of a function. It also handles rolling back the session in case of an error.
+
+    Args:
+        func_name (str): The name of the function being executed.
+        session (AsyncSession): The database session used in the function.
+
+    Yields:
+        None: This context manager does not yield any value.
+
+    Raises:
+        SQLAlchemyError: Re-raises any SQLAlchemy-specific exceptions after logging and rollback.
+        Exception: Re-raises any other exceptions after logging and rollback.
+    """
+    try:
+        yield
+
+    except SQLAlchemyError as e:
+        await logger.exception(f"Database error in {func_name}: {e}")
+        await session.rollback()
+        raise
+
+    except Exception as e:
+        await logger.exception(f"Unexpected error in {func_name}: {e}")
+        await session.rollback()
+        raise
+
+
+def _validate_signature(func: Sessionizable) -> None:
+    """Validate that the given function has a 'session' keyword argument.
+
+    This function checks if the 'session' parameter is present in the function's signature.
+    If the 'session' parameter is missing, it raises an UnboundLocalError.
+
+    Args:
+        func (Sessionizable): The function to validate.
+
+    Raises:
+        UnboundLocalError: If the function does not have a 'session' parameter.
+    """
+    sig = inspect.signature(func)
+    try:
+        sig.parameters["session"]
+
+    except KeyError as e:
+        msg = f"{func.__name__} does not have a session parameter."
+        raise UnboundLocalError(msg) from e
+
+
+def sessionize(func: Sessionizable) -> Sessionizable:
+    """Decorator that ensures a database session is available to an async function or generator.
+
+    This decorator automatically injects a `session` of type AsyncSession
+    into the decorated function if one is not provided. If the `session` keyword argument is
+    missing or set to None, a new session is created using the `_async_session_maker` and passed
+    to the function. If a session is already provided when the function is called, it uses the
+    existing session.
+
+    The decorator is intended for use with coroutine functions and async generator functions that
+    are expected to interact with a database using SQLAlchemy's asynchronous session management.
+
+    Features:
+    - Automatically manages database sessions to ensure efficient and correct usage of database
+        connections.
+    - Logs any SQLAlchemy-specific exceptions or other exceptions that occur during the execution
+        of the decorated function, handling rollbacks if necessary.
+    - Ensures that functions without a proper 'session' keyword argument are not decorated, raising
+        an UnboundLocalError.
+
+    Args:
+        func (Sessionizable): A coroutine function or an async generator function that accepts a
+        'session' keyword argument.
+
+    Returns:
+        Sessionizable: A wrapped version of the input function that manages a database session.
+
+    Raises:
+        TypeError: If `func` is neither a coroutine function nor an async generator function.
+        UnboundLocalError: If `func` lacks a 'session' keyword argument.
+
+    Example:
+        @sessionize
+        async def fetch_data(session: AsyncSession | None = None):
+            # Function body using session
+            ...
+
+    Note:
+        - The function must include a 'session' parameter in its signature, which can be None by
+            default.
+        - This decorator is only applicable to functions intended to perform database operations
+            asynchronously.
+
+    See Also:
+        - Sessionizable: The Protocol for sessionizable functions.
+        - AsyncSession: SQLAlchemy class used for asynchronous session management.
+    """
+    _validate_signature(func)
+
+    ret: Sessionizable
+    match func:
+        case func if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def _coro_wrapper[
+                **P
+            ](*args: P.args, **kwargs: P.kwargs) -> Coroutine:
+                """Wrap a sessionized coroutine function to inject the session if needed.
+
+                This wrapper function manages the database session for coroutine functions.
+                """
+                if kwargs["session"] is None:
+                    async with (
+                        _async_session_maker() as kwargs["session"],
+                        _db_logger(func.__name__, kwargs["session"]),
+                    ):
+                        return await func(*args, **kwargs)
+                else:
+                    async with _db_logger(func.__name__, kwargs["session"]):
+                        return await func(*args, **kwargs)
+
+            ret = _coro_wrapper
+
+        case func if inspect.isasyncgenfunction(func):
+
+            @functools.wraps(func)
+            async def _asyncgen_wrapper[
+                **P
+            ](*args: P.args, **kwargs: P.kwargs) -> AsyncGenerator:
+                """Wrap a sessionized async generator function to inject the session if needed.
+
+                This wrapper function manages the database session for async generator functions.
+                """
+                if kwargs["session"] is None:
+                    async with (
+                        _async_session_maker() as kwargs["session"],
+                        _db_logger(func.__name__, kwargs["session"]),
+                    ):
+                        async for element in func(*args, **kwargs):
+                            yield element
+                else:
+                    async with _db_logger(func.__name__, kwargs["session"]):
+                        async for element in func(*args, **kwargs):
+                            yield element
+
+            ret = _asyncgen_wrapper
+
+        case _:
+            msg = f"{func.__name__} is not an async generator or coroutine function."
+            logger.error(msg)
+            raise TypeError(msg)
+
+    return ret
+
+
+async def init_db() -> None:
+    """Create all tables asynchronously."""
+    try:
+        async with _engine.begin() as conn:
+            await conn.run_sync(models.mapper_registry.metadata.create_all)
+            await logger.info("Database tables created.")
+    except Exception as e:
+        await logger.exception(f"Failed to create tables: {e}")
+
+
+async def drop_db() -> None:
+    """Drop all tables asynchronously for clean slate testing or teardown."""
+    try:
+        async with _engine.begin() as conn:
+            await conn.run_sync(models.mapper_registry.metadata.drop_all)
+            await logger.info("Database tables dropped.")
+    except Exception as e:
+        await logger.exception(f"Failed to drop tables: {e}")
+
+
+@sessionize
+async def insert_or_update_track(
+    track_data: dict[str, Any],
+    *,
+    session: AsyncSession | None = None,
+) -> None:
+    """Insert a new track or update an existing one in the database asynchronously.
+
+    Args:
+        track_data: The track data to write to the database.
+
+    Keyword Args:
+        session: The database session.
+    """  # noqa: D417
+    async with session.begin():
+        genre = await session.get(models.Genre, track_data.get("genre_id"))
+        if not genre:
+            genre = models.Genre(name=track_data["genre_name"])
+            session.add(genre)
+            await session.flush()  # Ensures 'genre' is persisted and has an 'id'
+
+        track = await session.get(models.Track, track_data.get("id"))
+        if track:
+            for key, value in track_data.items():
+                setattr(track, key, value)
+            await logger.info(f"Updated track: {track.title}")
+        else:
+            track = models.Track(**track_data)
+            session.add(track)
+            await logger.info(f"Inserted new track: {track.title}")
+
+        await session.commit()
+
+
+@sessionize
+async def cleanup_unused_genres(*, session: AsyncSession | None = None) -> None:
+    """Remove genres that are no longer used by any tracks.
+
+    Keyword Args:
+        session: The database session.
+    """
+    async with session.begin():
+        stmt = (
+            sqlalchemy.select(models.Genre)
+            .outerjoin(models.Track)
+            .filter(models.Track.id is None)
+        )
+        result = await session.execute(stmt)
+        unused_genres = result.scalars().all()
+
+        for genre in unused_genres:
+            await session.delete(genre)
+
+        await session.commit()
+        await logger.info(f"Cleaned up {len(unused_genres)} unused genres.")
+
+
+@sessionize
+async def set_timestamp(
+    event: enums.Event,
+    operation: enums.TimedEvent,
+    *,
+    session: AsyncSession | None = None,
+) -> datetime:
+    """Mark the start or end timestamps in the statistics model.
+
+    Args:
+        event: Identifies what event is being affected.
+        operation: Identifies if it is the start or end of the event.
+
+    Keyword Args:
+        session: The database session.
+
+    Returns:
+        datetime: The datetime of the last update.
+    """
+    async with session.begin():
+        stats = await session.get(models.Statistics, 1)
+        stats_obj = stats.scalars().first()
+
+        match [event, operation]:
+            case [enums.Event.UPDATER, enums.EventTime.START]:
+                stats_obj.start_update = datetime.now()
+                log_message = "Updater start timestamp updated."
+            case [enums.Event.UPDATER, enums.EventTime.END]:
+                stats_obj.end_update = datetime.now()
+                log_message = "Updater end timestamp updated."
+            case [enums.Event.GENERATOR, enums.EventTime.START]:
+                stats_obj.start_playlist_gen = datetime.now()
+                log_message = "Generator start timestamp updated."
+            case [enums.Event.GENERATOR, enums.EventTime.END]:
+                stats_obj.end_playlist_gen = datetime.now()
+                log_message = "Generator end timestamp updated."
+            case _:
+                raise ValueError(
+                    f"Invalid event {event} or operation {operation} specified."
+                )
+
+        match event:
+            case enums.Event.UPDATER:
+                last_updated = stats_obj.end_update
+            case enums.Event.GENERATOR:
+                last_updated = stats_obj.end_playlist_gen
+            case _:
+                raise ValueError(f"Invalid event {event} specified.")
+
+        await session.commit()
+        await logger.info(log_message)
+
+        return last_updated
+
+
+@sessionize
+async def remove_holiday_by_id(
+    holiday_id: int, *, session: AsyncSession | None = None
+) -> None:
+    """Remove a holiday from the database by ID.
+
+    Captures and logs database-specific errors and general exceptions.
+
+    Args:
+        holiday_id: The holiday ID to remove.
+
+    Keyword Args:
+        session: The database session.
+    """  # noqa: D417
+    holiday = await session.get(models.Holiday, holiday_id)
+    if holiday:
+        await session.delete(holiday)
+        await session.commit()
+    else:
+        await logger.warning(f"No holiday found with ID: {holiday_id}")
+
+
+@sessionize
+async def update_statistics(
+    new_average_duration: float,
+    new_podcast_length: float,
+    new_max_playtime: float,
+    new_category_count: int,
+    new_active_holidays: int,
+    new_max_tracks: int,
+    new_max_regular: int,
+    new_max_holiday: int,
+    new_max_regular_favorite: int,
+    new_max_regular_general: int,
+    new_max_holiday_favorite: int,
+    new_max_holiday_general: int,
+    new_max_regular_favorite_base: int,
+    new_max_regular_general_base: int,
+    new_max_holiday_favorite_base: int,
+    new_max_holiday_general_base: int,
+    *,
+    session: AsyncSession | None = None,
+) -> None:
+    """Update the statistics model.
+
+    Args:
+        new_average_duration: The new average duration of a track by geometric mean
+            of all track durations as a float.
+        new_podcast_length: The new total podcast length of all current episodes as a float.
+        new_max_playtime: The new max playtime as a float.
+        new_category_count: The new count of categories as an int.
+        new_active_holidays: The new active holidays as an int.
+        new_max_tracks: The new max tracks per day as an int.
+        new_max_regular: The new max regular tracks as an int.
+        new_max_holiday: The new max holiday tracks as an int.
+        new_max_regular_favorite: The new max regular favorite tracks as an int.
+        new_max_regular_general: The new max regular general tracks as an int.
+        new_max_holiday_favorite: The new max holiday favorite tracks as an int.
+        new_max_holiday_general: The new max holiday general tracks as an int.
+        new_max_regular_favorite_base: The new max regular favorite base unit as an int.
+        new_max_regular_general_base: The new max regular general base unit as an int.
+        new_max_holiday_favorite_base: The new max holiday favorite base unit as an int.
+        new_max_holiday_general_base: The new max holiday general base unit as an int.
+
+    Keyword Args:
+        session: The database session.
+    """  # noqa: D417
+    async with session.begin():
+        # Assuming there's only one statistics record, or you might need to handle this differently
+        stats = await session.get(models.Statistics, 1)
+        if stats:
+            stats.average_track_length = new_average_duration
+            stats.total_podcast_length = new_podcast_length
+            stats.max_playtime = new_max_playtime
+            stats.category_count = new_category_count
+            stats.active_holiday_count = new_active_holidays
+            stats.max_tracks_per_day = new_max_tracks
+            stats.max_regular_tracks = new_max_regular
+            stats.max_holiday_tracks = new_max_holiday
+            stats.max_regular_favorite_tracks = new_max_regular_favorite
+            stats.max_regular_general_tracks = new_max_regular_general
+            stats.max_holiday_favorite_tracks = new_max_holiday_favorite
+            stats.max_holiday_general_tracks = new_max_holiday_general
+            stats.max_regular_favorite_base = new_max_regular_favorite_base
+            stats.max_regular_general_base = new_max_regular_general_base
+            stats.max_holiday_favorite_base = new_max_holiday_favorite_base
+            stats.max_holiday_general_base = new_max_holiday_general_base
+            await session.commit()
+        else:
+            # If no statistics entry exists, create one
+            new_stats = models.Statistics(
+                average_track_length=new_average_duration,
+                total_podcast_length=new_podcast_length,
+                max_playtime=new_max_playtime,
+                active_holiday_count=new_active_holidays,
+                max_tracks_per_day=new_max_tracks,
+                max_regular_tracks=new_max_regular,
+                max_holiday_tracks=new_max_holiday,
+                max_regular_favorite_tracks=new_max_regular_favorite,
+                max_regular_general_tracks=new_max_regular_general,
+                max_holiday_favorite_tracks=new_max_holiday_favorite,
+                max_holiday_general_tracks=new_max_holiday_general,
+                max_regular_favorite_base=new_max_regular_favorite_base,
+                max_regular_general_base=new_max_regular_general_base,
+                max_holiday_favorite_base=new_max_holiday_favorite_base,
+                max_holiday_general_base=new_max_holiday_general_base,
+            )
+            session.add(new_stats)
+            await session.commit()
+
+
+@sessionize
+async def fetch_tracks_for_sublist(
+    is_category: bool,
+    type_id: int,
+    is_favorite: bool,
+    sublist: enums.Sublist,
+    limit: int,
+    playlist_entries: set[int],
+    *,
+    session: AsyncSession | None = None,
+) -> AsyncGenerator[models.Track, None]:
+    """Fetch tracks for a given sublist type within a category.
+
+    Args:
+        is_category: True if a category, false if a holiday.
+        type_id: Category or holiday ID for track filtering.
+        is_favorite: Flag indicating if only favorite tracks should be fetched.
+        sublist: Type of sublist to fetch.
+        limit: Number of tracks to fetch.
+        playlist_entries: The set of track IDs already in the playlist.
+
+    Keyword Args:
+        session: The database session.
+
+    Returns:
+        AsyncGenerator[models.Track, None]: Generates the tracks fitting the
+        criteria.
+    """
+    query = sqlalchemy.select(models.Track)
+    if is_category:
+        query = query.where(models.Track.category_id == type_id)
+    else:
+        query = query.join(models.Track.holidays).where(models.Holiday.id == type_id)
+
+    query = query.filter(models.Track.id.not_in(playlist_entries))
+
+    if is_favorite:
+        query = query.filter(models.Track.rating == 5)
+
+    match sublist:
+        case enums.Sublist.LEAST_RECENTLY_PLAYED:
+            query = query.order_by(models.Track.last_played.asc())
+        case enums.Sublist.LEAST_OFTEN_PLAYED:
+            query = query.order_by(models.Track.play_count.asc())
+        case enums.Sublist.LEAST_RECENTLY_ADDED:
+            query = query.order_by(models.Track.date_added.asc())
+        case enums.Sublist.RANDOM:
+            query = query.order_by(sqlalchemy.func.random())
+        case _:
+            raise ValueError(f"Unknown sublist type: {sublist}")
+
+    query = query.limit(limit)
+    result = await session.execute(query)
+    for track in result.scalars():
+        yield track
+
+
+@sessionize
+async def insert_into_playlist(  # noqa: C901
+    is_category: bool,
+    type_id: int,
+    track_id: int,
+    sublist: enums.Sublist,
+    is_favorite: bool,
+    *,
+    session: AsyncSession | None = None,
+) -> None:
+    """Insert a track into the playlist.
+
+    Args:
+        is_category: True is a category, false is a holiday.
+        type_id: Category or holiday ID associated with the playlist.
+        track_id: Track ID to be added to the playlist.
+        sublist: Sublist type under which the track is added.
+        is_favorite: Indicates if the track is added as a favorite.
+
+    Keyword Args:
+        session: The database session.
+    """  # noqa: D417
+    if is_category:
+        playlist_track = models.PlaylistTrack(
+            category_id=type_id,
+            track_id=track_id,
+            sublist_type=sublist,
+            is_favorite=is_favorite,
+        )
+    else:
+        playlist_track = models.PlaylistTrack(
+            holiday_id=type_id,
+            track_id=track_id,
+            sublist_type=sublist,
+            is_favorite=is_favorite,
+        )
+    session.add(playlist_track)
+    await session.commit()
+
+
+@sessionize
+async def gen_all_category_ids(
+    *, session: AsyncSession | None = None
+) -> AsyncGenerator[int, None, None]:
+    """Generate the current category ids from the database.
+
+    Keyword Args:
+        session: The database session.
+
+    Yields:
+        int: The category id.
+    """
+    query = sqlalchemy.select(models.Category)
+    result = session.execute(query)
+    for row in result.scalars():
+        yield row.id
+
+
+@sessionize
+async def gen_active_holiday_ids(
+    *, session: AsyncSession | None = None
+) -> AsyncGenerator[int, None, None]:
+    """Generate the current active holiday ids from the database.
+
+    Keyword Args:
+        session: The database session.
+
+    Yields:
+        int: The holiday id.
+    """
+    query = sqlalchemy.select(models.Holiday).where(models.Holiday.is_active is True)
+    result = session.execute(query)
+    for row in result.scalars():
+        yield row.id
+
+
+@sessionize
+async def get_existing_playlist_track_info(
+    *,
+    session: AsyncSession | None = None,
+) -> tuple[set[int], dict[tuple[bool, int, bool, enums.Sublist], int]]:
+    """Get the existing playlist track information.
+
+    Keyword Args:
+        session: The database session.
+
+    Returns:
+        tuple[set[int], dict[tuple[bool, int, bool, enums.Sublist], int]]: Two pieces:
+        First is a set of the ids of all of the tracks in the playlist. Second is a
+        dict with the key being the combination of is_category, type_id, is_favorite,
+        and sublist; the value is the count of that unique key combination.
+    """
+    # TODO: Set up user-specific query here.
+    query = sqlalchemy.select(models.PlaylistTrack).where(
+        models.PlaylistTrack.episode_id is None
+    )
+    result = session.execute(query)
+    ids = set()
+    data = []
+    for row in result.scalars():
+        if row.episode_id is not None:
+            continue
+        ids.append(row.track_id)
+        is_category = row.category_id is not None
+        type_id = row.category_id if is_category else row.holiday_id
+        is_favorite = row.is_favorite
+        sublist = row.sublist
+        data.append((is_category, type_id, is_favorite, sublist))
+    data_counts = collections.Counter(data)
+    return ids, data_counts
+
+
+@sessionize
+async def get_statistics(*, session: AsyncSession | None = None) -> models.Statistics:
+    """Get the statistics object for the database.
+
+    Keyword Args:
+        session: The database session.
+
+    Returns:
+        models.Statistics: The statistics object used for playlist processing.
+    """
+    stats = await session.get(models.Statistics, 1)
+    stats_obj = stats.scalars().first()
+    return stats_obj
+
+
+@sessionize
+async def remove_track_from_playlist(
+    server_id: str, *, session: AsyncSession | None = None
+):
+    """Directly removes all entries from PlaylistTrack that are associated with a given server_id.
+
+    Args:
+        server_id: The unique server ID of the track to remove from the playlist.
+
+    Keyword Args:
+        session: The current database session.
+
+    Returns:
+        int: Number of rows affected by the delete operation.
+    """
+    # Delete directly using a join on Track where server_id matches
+    delete_query = sqlalchemy.delete(models.PlaylistTrack).where(
+        models.PlaylistTrack.track_id
+        == sqlalchemy.select(models.Track.id)
+        .where(models.Track.server_id == server_id)
+        .scalar_subquery()
+    )
+    result = await session.execute(delete_query)
+    await session.commit()
+
+    affected_rows = result.rowcount
+    logger.info(
+        f"Removed {affected_rows} entries from PlaylistTrack for server_id {server_id}."
+    )
+    return affected_rows

backend/src/playlist/updater.py

@@ -0,0 +1,127 @@
+"""Handles updating the tracks stored in the database from plex."""
+
+import enums
+import env
+import numpy as np
+import plex
+import sql
+from aiologger import Logger
+
+
+logger = Logger.with_default_handlers(name="updater_logger")
+
+
+async def process_tracks(server_url: str, token: str) -> None:
+    """Asynchronously processes track data fetched from a Plex server.
+
+    Updates tracks in the database, and handles genre cleanup after updates.
+
+    Args:
+        server_url (str): The URL of the Plex server.
+        token (str): The authentication token used for accessing the Plex server.
+    """
+    found_genres = set()
+    durations: list[float] = []
+    try:
+        with sql.async_session_maker() as session:
+            last_updated = await sql.update_timestamp(
+                session, enums.Event.UPDATER, enums.Event.START
+            )
+
+            async for track_data in plex.fetch_tracks_from_plex(server_url, token):
+                if track_data["date_last_played"] > last_updated:
+                    await sql.remove_track_from_playlist(
+                        session, track_data["server_id"]
+                    )
+                    logger.info(
+                        f"Track {track_data['server_id']} with title {track_data['title']}"
+                        f" by artist {track_data['artist']} removed from playlist because it"
+                        " was recently played."
+                    )
+                await sql.insert_or_update_track(session, track_data, found_genres)
+                # TODO: Exclude podcast episodes from the list of durations.
+                if (
+                    track_data["duration"] > 0
+                ):  # Ensure only positive durations are added
+                    durations.append(track_data["duration"])
+                else:
+                    logger.warning(
+                        f"Track {track_data['server_id']} with title {track_data['title']}"
+                        f" by artist {track_data['artist']} has a duration of: {track_data['duration']}."
+                    )
+
+            await sql.cleanup_unused_genres(session, found_genres)
+
+            await calculate_statistics(session, durations)
+
+            await sql.update_timestamp(session, enums.Event.UPDATER, enums.Event.END)
+        await logger.info("Track processing completed successfully.")
+    except Exception as e:
+        await logger.error(f"An error occurred during track processing: {e}")
+        raise
+
+
+async def calculate_statistics(durations: list[float]) -> None:
+    """Calculate the statistics to be used for playlist processing.
+
+    Args:
+        durations (list[float]): The list of durations of all tracks gathered during
+            the track updating process.
+    """
+    if durations:
+        average_duration = np.exp(np.log(durations).mean())
+
+        # TODO: Get the total duration of all podcast episodes.
+        total_podcast_length = 0
+
+        max_playtime = env.MAX_PLAYTIME - total_podcast_length
+        max_tracks_per_day = int(max_playtime / average_duration)
+
+        # TODO: Calculate the number of categories in the database.abs
+        category_count = 1
+
+        # TODO: Calculate the amount of the playlist that will be for active holidays.
+        active_holidays = 0
+
+        ratio_denom = active_holidays * 2 + 1
+
+        max_regular_percentage = (active_holidays + 1) / ratio_denom / category_count
+        max_holiday_percentage = 1 / ratio_denom if active_holidays else 0
+
+        max_regular_tracks = int(max_tracks_per_day * max_regular_percentage)
+        max_holiday_tracks = int(max_tracks_per_day * max_holiday_percentage)
+
+        max_regular_favorite_tracks = int(max_regular_tracks / 3)
+        max_regular_general_tracks = int(2 * max_regular_tracks / 3)
+
+        max_holiday_favorite_tracks = int(max_holiday_tracks / 3)
+        max_holiday_general_tracks = int(2 * max_holiday_tracks / 3)
+
+        max_regular_favorite_base = int(max_regular_favorite_tracks / 6)
+        max_regular_general_base = int(max_regular_general_tracks / 6)
+
+        max_holiday_favorite_base = int(max_holiday_favorite_tracks / 6)
+        max_holiday_general_base = int(max_holiday_general_tracks / 6)
+
+        await sql.update_statistics(
+            average_duration,
+            total_podcast_length,
+            max_playtime,
+            category_count,
+            active_holidays,
+            max_tracks_per_day,
+            max_regular_tracks,
+            max_holiday_tracks,
+            max_regular_favorite_tracks,
+            max_regular_general_tracks,
+            max_regular_favorite_base,
+            max_regular_general_base,
+            max_holiday_favorite_tracks,
+            max_holiday_general_tracks,
+            max_holiday_favorite_base,
+            max_holiday_general_base,
+        )
+
+        # TODO: Remove any tracks that exceed a sublist's limit for the playlist after these adjustments.
+    else:
+        logger.warning("No valid track durations retrieved, statistics not updated.")

backend/tests/test_main.py

@@ -1,7 +1,6 @@
 """Test cases for the __main__ module."""
 import pytest
 from click.testing import CliRunner
-
 from playlist import __main__
 
 

codecov.yml

@@ -1,4 +1,3 @@
----
 comment: false
 coverage:
   status:

docs/codeofconduct.rst

@@ -1 +0,0 @@
-.. include:: ../CODE_OF_CONDUCT.rst

docs/conf.py

@@ -1,15 +0,0 @@
-"""Sphinx configuration."""
-from datetime import datetime
-
-
-project = "Automated Daily Playlist Generator for Plex Music"
-author = "Cliff Hill"
-copyright = f"{datetime.now().year}, {author}"
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
-    "sphinx_click",
-    "sphinx_rtd_theme",
-]
-autodoc_typehints = "description"
-html_theme = "sphinx_rtd_theme"

docs/contributing.rst

@@ -1,4 +0,0 @@
-.. include:: ../CONTRIBUTING.rst
-   :end-before: github-only
-
-.. _Code of Conduct: codeofconduct.html

docs/index.rst

@@ -1,16 +0,0 @@
-.. include:: ../README.rst
-   :end-before: github-only
-
-.. _Contributor Guide: contributing.html
-.. _Usage: usage.html
-
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-
-   usage
-   reference
-   contributing
-   Code of Conduct <codeofconduct>
-   License <license>
-   Changelog <https://github.com/xlorepdarkhelm/plex-playlist/releases>

docs/license.rst

@@ -1 +0,0 @@
-.. include:: ../LICENSE.rst

docs/reference.rst

@@ -1,13 +0,0 @@
-Reference
-=========
-
-.. contents::
-    :local:
-    :backlinks: none
-
-
-playlist.__main__
------------------
-
-.. automodule:: playlist.__main__
-   :members:

docs/requirements.txt

@@ -1,3 +0,0 @@
-sphinx==3.5.2
-sphinx-click==2.6.0
-sphinx-rtd-theme==0.5.1

docs/usage.rst

@@ -1,6 +0,0 @@
-Usage
-=====
-
-.. click:: playlist.__main__:main
-   :prog: plex-playlist
-   :nested: full

isort.cfg

@@ -1,6 +0,0 @@
-[settings]
-line-length = 88
-multi_line_output = 5
-include_trailing_comma = true
-known_future_library = "future"
-indent = '    ' '

mypy.ini

@@ -1,20 +0,0 @@
-[mypy]
-check_untyped_defs = True
-disallow_any_generics = True
-disallow_incomplete_defs = True
-disallow_subclassing_any = True
-disallow_untyped_calls = True
-disallow_untyped_decorators = True
-disallow_untyped_defs = True
-no_implicit_optional = True
-no_implicit_reexport = True
-pretty = True
-show_column_numbers = True
-show_error_codes = True
-show_error_context = True
-strict_equality = True
-warn_redundant_casts = True
-warn_return_any = True
-warn_unreachable = True
-warn_unused_configs = True
-warn_unused_ignores = True

noxfile.py

@@ -1,16 +1,30 @@
 """Nox sessions."""
+import os
+import shlex
 import shutil
 import sys
 from pathlib import Path
 from textwrap import dedent
 
 import nox
-from nox_poetry import Session
-from nox_poetry import session
+
+
+try:
+    from nox_poetry import Session
+    from nox_poetry import session
+except ImportError:
+    message = f"""\
+    Nox failed to import the 'nox-poetry' package.
+
+    Please install it using the following command:
+
+    {sys.executable} -m pip install nox-poetry"""
+    raise SystemExit(dedent(message)) from None
 
 
 package = "playlist"
-python_versions = ["3.9"]
+python_versions = ["3.10", "3.9", "3.8", "3.7"]
+nox.needs_version = ">= 2021.6.6"
 nox.options.sessions = (
     "pre-commit",
     "safety",
@@ -22,7 +36,7 @@ nox.options.sessions = (
 )
 
 
-def activate_virtualenv_in_precommit_hooks(session: Session) -> None:  # noqa: CCR001
+def activate_virtualenv_in_precommit_hooks(session: Session) -> None:
     """Activate virtualenv in hooks installed by pre-commit.
 
     This function patches git hooks installed by pre-commit to activate the
@@ -32,13 +46,42 @@ def activate_virtualenv_in_precommit_hooks(session: Session) -> None:  # noqa: C
     Args:
         session: The Session object.
     """
-    if session.bin is None:
-        return  # type: ignore [unreachable]
+    assert session.bin is not None  # noqa: S101
+
+    # Only patch hooks containing a reference to this session's bindir. Support
+    # quoting rules for Python and bash, but strip the outermost quotes so we
+    # can detect paths within the bindir, like <bindir>/python.
+    bindirs = [
+        bindir[1:-1] if bindir[0] in "'\"" else bindir
+        for bindir in (repr(session.bin), shlex.quote(session.bin))
+    ]
 
     virtualenv = session.env.get("VIRTUAL_ENV")
     if virtualenv is None:
         return
 
+    headers = {
+        # pre-commit < 2.16.0
+        "python": f"""\
+            import os
+            os.environ["VIRTUAL_ENV"] = {virtualenv!r}
+            os.environ["PATH"] = os.pathsep.join((
+                {session.bin!r},
+                os.environ.get("PATH", ""),
+            ))
+            """,
+        # pre-commit >= 2.16.0
+        "bash": f"""\
+            VIRTUAL_ENV={shlex.quote(virtualenv)}
+            PATH={shlex.quote(session.bin)}"{os.pathsep}$PATH"
+            """,
+        # pre-commit >= 2.17.0 on Windows forces sh shebang
+        "/bin/sh": f"""\
+            VIRTUAL_ENV={shlex.quote(virtualenv)}
+            PATH={shlex.quote(session.bin)}"{os.pathsep}$PATH"
+            """,
+    }
+
     hookdir = Path(".git") / "hooks"
     if not hookdir.is_dir():
         return
@@ -47,36 +90,35 @@ def activate_virtualenv_in_precommit_hooks(session: Session) -> None:  # noqa: C
         if hook.name.endswith(".sample") or not hook.is_file():
             continue
 
+        if not hook.read_bytes().startswith(b"#!"):
+            continue
+
         text = hook.read_text()
-        bindir = repr(session.bin)[1:-1]  # strip quotes
-        if not (
+
+        if not any(
             Path("A") == Path("a") and bindir.lower() in text.lower() or bindir in text
+            for bindir in bindirs
         ):
             continue
 
         lines = text.splitlines()
-        if not (lines[0].startswith("#!") and "python" in lines[0].lower()):
-            continue
 
-        header = dedent(
-            f"""\
-            import os
-            os.environ["VIRTUAL_ENV"] = {virtualenv!r}
-            os.environ["PATH"] = os.pathsep.join((
-                {session.bin!r},
-                os.environ.get("PATH", ""),
-            ))
-            """,
-        )
-
-        lines.insert(1, header)
-        hook.write_text("\n".join(lines))
+        for executable, header in headers.items():
+            if executable in lines[0].lower():
+                lines.insert(1, dedent(header))
+                hook.write_text("\n".join(lines))
+                break
 
 
-@session(name="pre-commit", python="3.9")
+@session(name="pre-commit", python=python_versions[0])
 def precommit(session: Session) -> None:
     """Lint using pre-commit."""
-    args = session.posargs or ["run", "--all-files", "--show-diff-on-failure"]
+    args = session.posargs or [
+        "run",
+        "--all-files",
+        "--hook-stage=manual",
+        "--show-diff-on-failure",
+    ]
     session.install(
         "black",
         "darglint",
@@ -85,30 +127,31 @@ def precommit(session: Session) -> None:
         "flake8-bugbear",
         "flake8-docstrings",
         "flake8-rst-docstrings",
+        "isort",
         "pep8-naming",
         "pre-commit",
         "pre-commit-hooks",
-        "reorder-python-imports",
+        "pyupgrade",
     )
     session.run("pre-commit", *args)
     if args and args[0] == "install":
         activate_virtualenv_in_precommit_hooks(session)
 
 
-@session(python="3.9")
+@session(python=python_versions[0])
 def safety(session: Session) -> None:
     """Scan dependencies for insecure packages."""
     requirements = session.poetry.export_requirements()
     session.install("safety")
-    session.run("safety", "check", f"--file={requirements}", "--bare")
+    session.run("safety", "check", "--full-report", f"--file={requirements}")
 
 
 @session(python=python_versions)
 def mypy(session: Session) -> None:
     """Type-check using mypy."""
-    args = session.posargs or ["src", "tests", "docs/conf.py"]
+    args = session.posargs or ["backend/src", "backend/tests", "backend/docs/conf.py"]
     session.install(".")
-    session.install("mypy", "pytest", "pytest-asyncio", "pytest-mock", "types-all")
+    session.install("mypy", "pytest")
     session.run("mypy", *args)
     if not session.posargs:
         session.run("mypy", f"--python-executable={sys.executable}", "noxfile.py")
@@ -118,59 +161,69 @@ def mypy(session: Session) -> None:
 def tests(session: Session) -> None:
     """Run the test suite."""
     session.install(".")
-    session.install(
-        "coverage[toml]",
-        "pytest",
-        "pytest-asyncio",
-        "pytest-mock",
-        "pygments",
-    )
+    session.install("coverage[toml]", "pytest", "pygments")
     try:
-        session.run("coverage", "run", "--parallel", "-m", "pytest", *session.posargs)
+        session.run(
+            "coverage",
+            "run",
+            "--parallel",
+            "-m",
+            "pytest",
+            "backend/tests",
+            *session.posargs,
+        )
     finally:
         if session.interactive:
-            session.notify("coverage")
+            session.notify("coverage", posargs=[])
 
 
-@session
+@session(python=python_versions[0])
 def coverage(session: Session) -> None:
     """Produce the coverage report."""
-    # Do not use session.posargs unless this is the only session.
-    nsessions = len(session._runner.manifest)
-    has_args = session.posargs and nsessions == 1
-    args = session.posargs if has_args else ["report"]
+    args = session.posargs or ["report"]
 
     session.install("coverage[toml]")
 
-    if not has_args and any(Path().glob(".coverage.*")):
+    if not session.posargs and any(Path().glob(".coverage.*")):
         session.run("coverage", "combine")
 
     session.run("coverage", *args)
 
 
-@session(python=python_versions)
+@session(python=python_versions[0])
 def typeguard(session: Session) -> None:
     """Runtime type checking using Typeguard."""
     session.install(".")
-    session.install("pytest", "pytest-asyncio", "pytest-mock", "typeguard", "pygments")
-    session.run("pytest", f"--typeguard-packages={package}", *session.posargs)
+    session.install("pytest", "typeguard", "pygments")
+    session.run(
+        "pytest", "backend/tests", f"--typeguard-packages={package}", *session.posargs
+    )
 
 
 @session(python=python_versions)
 def xdoctest(session: Session) -> None:
     """Run examples with xdoctest."""
-    args = session.posargs or ["all"]
+    if session.posargs:
+        args = [package, *session.posargs]
+    else:
+        args = [f"--modname={package}", "--command=all"]
+        if "FORCE_COLOR" in os.environ:
+            args.append("--colored=1")
+
     session.install(".")
     session.install("xdoctest[colors]")
-    session.run("python", "-m", "xdoctest", package, *args)
+    session.run("python", "-m", "xdoctest", "backend/src", *args)
 
 
-@session(name="docs-build", python="3.9")
+@session(name="docs-build", python=python_versions[0])
 def docs_build(session: Session) -> None:
     """Build the documentation."""
     args = session.posargs or ["docs", "docs/_build"]
+    if not session.posargs and "FORCE_COLOR" in os.environ:
+        args.insert(0, "--color")
+
     session.install(".")
-    session.install("sphinx", "sphinx-click", "sphinx-rtd-theme")
+    session.install("sphinx", "sphinx-click", "furo", "myst-parser")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():
@@ -179,12 +232,12 @@ def docs_build(session: Session) -> None:
     session.run("sphinx-build", *args)
 
 
-@session(python="3.9")
+@session(python=python_versions[0])
 def docs(session: Session) -> None:
     """Build and serve the documentation with live reloading on file changes."""
     args = session.posargs or ["--open-browser", "docs", "docs/_build"]
     session.install(".")
-    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "sphinx-rtd-theme")
+    session.install("sphinx", "sphinx-autobuild", "sphinx-click", "furo", "myst-parser")
 
     build_dir = Path("docs", "_build")
     if build_dir.exists():

pyproject.toml

@@ -1,68 +1,91 @@
 [tool.poetry]
 name = "plex-playlist"
-version = "0.1.0"
-description = "Automated Daily Playlist Generator for Plex Music"
+version = "0.0.0"
+description = "Plex Playlist"
 authors = ["Cliff Hill <xlorep@darkhelm.org>"]
 license = "MIT"
-readme = "README.rst"
-homepage = "https://gitlab.com/xlorepdarkhelm/plex-playlist"
-repository = "https://gitlab.com/xlorepdarkhelm/plex-playlist"
+readme = "README.md"
+homepage = "https://github.com/xlorepdarkhelm/plex-playlist"
+repository = "https://github.com/xlorepdarkhelm/plex-playlist"
 documentation = "https://plex-playlist.readthedocs.io"
 packages = [
-    { include = "playlist", from = "src" },
+    { include = "playlist", from = "backend/src" },
 ]
 classifiers = [
-    "Programming Language :: Python :: 3.10",
+    "Development Status :: 1 - Planning",
 ]
 
 [tool.poetry.urls]
-Changelog = "https://gitlab.com/xlorepdarkhelm/plex-playlist/releases"
+Changelog = "https://github.com/xlorepdarkhelm/plex-playlist/releases"
 
 [tool.poetry.dependencies]
-python = ">=3.10,<3.11"
-click = "^8.0.3"
-PlexAPI = "^4.5.2"
-appdirs = "^1.4.4"
-asyncpg = "^0.23.0"
-uvloop = "^0.15.2"
-desert = "^2020.11.18"
-numpy = "^1.21.2"
-typeguard = "^2.12.1"
-gino = "^1.0.1"
-quart = "^0.16.3"
-marshmallow-sqlalchemy = "^0.27.0"
-strictyaml = "^1.6.1"
+python = "^3.12"
+click = ">=8.0.1"
+asyncpg = "^0.28.0"
+sqlalchemy = "^2.0.23"
+pydantic = "^2.5.0"
+alembic = "^1.12.1"
+python-dotenv = "^1.0.1"
+aiologger = "^0.7.0"
+numpy = "^1.26.4"
 
 [tool.poetry.dev-dependencies]
-typeguard = "^2.12.0"
-jupyter = "^1.0.0"
-pre-commit = "^2.13.0"
-pre-commit-hooks = "^4.0.1"
-pytest = "^6.2.5"
-pytest-asyncio = "^0.15.1"
-pytest-mock = "^3.6.1"
-black = "^22.1.0"
-types-all = "^1.0.0"
-
+Pygments = ">=2.10.0"
+black = ">=21.10b0"
+coverage = {extras = ["toml"], version = ">=6.2"}
+darglint = ">=1.8.1"
+flake8 = ">=4.0.1"
+flake8-bandit = ">=2.1.2"
+flake8-bugbear = ">=21.9.2"
+flake8-docstrings = ">=1.6.0"
+flake8-rst-docstrings = ">=0.2.5"
+furo = ">=2021.11.12"
+isort = ">=5.10.1"
+mypy = ">=0.930"
+pep8-naming = ">=0.12.1"
+pre-commit = ">=2.16.0"
+pre-commit-hooks = ">=4.1.0"
+pytest = ">=6.2.5"
+pyupgrade = ">=2.29.1"
+safety = ">=1.10.3"
+sphinx = ">=4.3.2"
+sphinx-autobuild = ">=2021.3.14"
+sphinx-click = ">=3.0.2"
+typeguard = ">=2.13.3"
+xdoctest = {extras = ["colors"], version = ">=0.15.10"}
+myst-parser = {version = ">=0.16.1"}
 
 [tool.poetry.scripts]
 plex-playlist = "playlist.__main__:main"
 
-[tool.black]
-line-length = 88
-target-version = ["py310"]
+[tool.poetry.group.dev.dependencies]
+jupyter = "^1.0.0"
 
 [tool.coverage.paths]
 source = ["src", "*/site-packages"]
+tests = ["tests", "*/tests"]
 
 [tool.coverage.run]
 branch = true
-source = ["playlist"]
+source = ["playlist", "tests"]
 
 [tool.coverage.report]
 show_missing = true
 fail_under = 100
 
+[tool.isort]
+profile = "black"
+force_single_line = true
+lines_after_imports = 2
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+pretty = true
+show_column_numbers = true
+show_error_codes = true
+show_error_context = true
+
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

src/playlist/__init__.py

@@ -1 +0,0 @@
-"""Automated Daily Playlist Generator for Plex Music."""

src/playlist/data/__init__.py

@@ -1 +0,0 @@
-"""Package containing all data classes used for the application."""

src/playlist/data/base.py

@@ -1,35 +0,0 @@
-"""Utility functions & classes used in the application."""
-from __future__ import annotations
-
-import functools
-import typing
-
-import desert
-import marshmallow
-
-
-DataSub = typing.TypeVar("DataSub", bound="BaseData")
-
-
-class BaseData:
-    """Base class for data classes in the application."""
-
-    @classmethod  # type: ignore [misc]
-    @property
-    @functools.cache
-    def Schema(cls: type[BaseData]) -> marshmallow.Schema:  # noqa: N802
-        """The marshmallow Schema object for this data class."""
-        return desert.schema(cls)
-
-    @classmethod
-    def load(cls: type[BaseData], data: dict[str, object]) -> DataSub:
-        """Load the given data dictionary into a class instance."""
-        return typing.cast(DataSub, cls.Schema.load(data))  # type: ignore [attr-defined]
-
-    def dump(self: BaseData) -> dict[str, object]:
-        """Dump the class instance into a data dictionary."""
-        cls = type(self)
-        return typing.cast(
-            dict[str, object],
-            cls.Schema.dump(self),  # type: ignore [attr-defined]
-        )

src/playlist/data/const.py

@@ -1,53 +0,0 @@
-"""Application-level constants."""
-import concurrent.futures
-import dataclasses
-import datetime
-import pathlib
-
-import appdirs  # type: ignore
-
-
-@dataclasses.dataclass(frozen=True)
-class _Defaults:
-    BATCH_SIZE: int
-    PROCESS_DELAY: int
-    DURATION: int
-    PLAYTIME: datetime.timedelta
-    MAX_TRACKS: int
-
-
-@dataclasses.dataclass(frozen=True)
-class _Paths:
-    CONFIG: pathlib.Path
-    DATA: pathlib.Path
-    CACHE: pathlib.Path
-    LOG: pathlib.Path
-
-
-APPNAME = "plex-playlist"
-APPAUTHOR = "Cliff Hill"
-
-
-_dirs = appdirs.AppDirs(APPNAME, APPAUTHOR)
-
-
-DEFAULTS = _Defaults(
-    BATCH_SIZE=1000,
-    PROCESS_DELAY=0,
-    DURATION=0,
-    PLAYTIME=datetime.timedelta(days=1),
-    MAX_TRACKS=0,
-)
-
-
-PROCESS_POOL = concurrent.futures.ProcessPoolExecutor()
-MAX_PROCESSES = PROCESS_POOL._max_workers  # type: ignore [attr-defined]
-SETTINGS_FILENAME = "settings.yaml"
-
-
-PATHS = _Paths(
-    CONFIG=pathlib.Path(_dirs.user_config_dir),
-    DATA=pathlib.Path(_dirs.user_data_dir),
-    CACHE=pathlib.Path(_dirs.user_cache_dir),
-    LOG=pathlib.Path(_dirs.user_log_dir),
-)

src/playlist/data/models.py

@@ -1,41 +0,0 @@
-"""Contains the data models used throughout the application."""
-import dataclasses
-import datetime
-
-import desert
-import marshmallow
-
-from playlist.data import base
-from playlist.data.sql import db
-
-
-@dataclasses.dataclass
-class Track(db.Model, base.BaseData):  # type: ignore [misc]
-    """Model defining a Track object."""
-
-    ___tablename__ = "tracks"
-
-    id: int = dataclasses.field(
-        init=False,
-        repr=False,
-        default=db.Column(db.Integer(), primary_key=True),
-    )
-    plex_id: int = db.Column(db.Integer)
-    track_num: int = db.Column(db.Integer)
-    title: str = db.Column(db.String)
-    artist: str = db.Column(db.String)
-    album_num: int = db.Column(db.Integer)
-    album: str = db.Column(db.String)
-    album_artist: str = db.Column(db.String)
-    duration: int = db.Column(db.Integer)
-    comments: str = db.Column(db.String)
-    added: datetime.datetime = db.Column(db.DateTime)
-    play_count: int = db.Column(db.Integer)
-    rating: int | None = dataclasses.field(
-        default=db.Column(db.Integer(), nullable=True, default=None),
-        metadata=desert.metadata(marshmallow.fields.Int(allow_none=True)),
-    )
-    played: datetime.datetime | None = dataclasses.field(
-        default=db.Column(db.Integer, nullable=True, default=None),
-        metadata=desert.metadata(marshmallow.fields.DateTime(allow_none=True)),
-    )

src/playlist/data/settings.py

@@ -1,187 +0,0 @@
-"""Define and control the Settings object for the playlist app."""
-from __future__ import annotations
-
-import collections.abc
-import contextlib
-import dataclasses
-import datetime
-import functools
-import getpass
-import json
-import pathlib
-import typing
-
-import plexapi.myplex
-import strictyaml
-from playlist.data import base
-from playlist.data import const
-
-
-__all__ = ["get", "modify"]
-
-
-class YamlData(base.BaseData):
-    """Base class for strictyaml classes."""
-
-    @classmethod  # type: ignore [misc]
-    @property
-    @functools.cache
-    def strictyaml_schema(cls: type[YamlData]) -> strictyaml.Map:
-        """Get the strictyaml schema for this class."""
-        field_map = {}
-        for field in dataclasses.fields(cls):
-            try:
-                field_map[field.name] = globals()[field.type].strictyaml_schema
-            except (KeyError, AttributeError):
-                match field.type:
-                    case "int":
-                        field_type = strictyaml.Int
-                    case "str":
-                        field_type = strictyaml.Str
-                    case "float":
-                        field_type = strictyaml.Float
-                    case "datetime.timedelta":
-                        field_type = strictyaml.Int
-                    case "datetime.datetime":
-                        field_type = strictyaml.Datetime
-                    case _:
-                        raise TypeError
-                field_map[field.name] = field_type()
-        return strictyaml.Map(field_map)
-
-
-@dataclasses.dataclass
-class CredentialSettings(YamlData):
-    """Credentials component for Settings object."""
-
-    baseurl: str
-    token: str
-
-    @classmethod
-    def create(cls: type[CredentialSettings]) -> CredentialSettings:  # pragma: no cover
-        """Get the credentials to store in the Settings instance.
-
-        Returns:
-            CredentialSettings: The dictionary containing the baseurl and token string
-            to connect with.
-        """
-        username = input("Plex Username: ")
-        password = getpass.getpass("Plex Password: ")
-        server = input("Plex Server: ")
-
-        account = plexapi.myplex.MyPlexAccount(username, password)
-        plex = account.resource(server).connect()
-        return CredentialSettings(baseurl=plex._baseurl, token=plex._token)
-
-
-@dataclasses.dataclass
-class DownloadSettings(YamlData):
-    """DownloadSettingser options for Settings object."""
-
-    batch_size: int
-    process_delay: float
-
-    @classmethod
-    def create(cls: type[DownloadSettings]) -> DownloadSettings:
-        return cls(
-            batch_size=const.DEFAULTS.BATCH_SIZE,
-            process_delay=const.DEFAULTS.PROCESS_DELAY,
-        )
-
-
-@dataclasses.dataclass
-class TrackSettings(YamlData):
-    """Track options for Settings object."""
-
-    duration: float
-
-    @classmethod
-    def create(cls: type[TrackSettings]) -> TrackSettings:
-        return cls(duration=const.DEFAULTS.DURATION)
-
-
-@dataclasses.dataclass
-class PlaylistSettings(YamlData):
-    """Playlist options for Settings object."""
-
-    playtime: datetime.timedelta
-    max_tracks: int
-
-    @classmethod
-    def create(cls: type[PlaylistSettings]) -> PlaylistSettings:
-        return cls(
-            playtime=const.DEFAULTS.PLAYTIME,
-            max_tracks=const.DEFAULTS.MAX_TRACKS,
-        )
-
-
-@dataclasses.dataclass
-class Settings(YamlData):
-    """Settings object, loaded from settings.yaml file."""
-
-    creds: CredentialSettings = dataclasses.field(
-        default_factory=CredentialSettings.create,
-    )
-    download: DownloadSettings = dataclasses.field(
-        default_factory=DownloadSettings.create,
-    )
-    track: TrackSettings = dataclasses.field(default_factory=TrackSettings.create)
-    playlist: PlaylistSettings = dataclasses.field(
-        default_factory=PlaylistSettings.create,
-    )
-
-    @classmethod
-    def yaml_read(
-        cls: type[Settings],
-        filepath: pathlib.Path,
-    ) -> Settings:
-        """Read the given YAML file and convert it into an object."""
-        try:
-            with filepath.open() as fp:
-                yaml_data = strictyaml.load(fp.read(), cls.strictyaml_schema)
-            return typing.cast(Settings, cls.load(yaml_data.data))
-        except strictyaml.YAMLValidationError:
-            return cls.yaml_create(filepath)
-
-    def yaml_write(self: Settings, filepath: pathlib.Path) -> None:
-        """Write this object as the given YAML file."""
-        data: type(self).Dict = self.dump()  # type: ignore [valid-type]
-
-        with filepath.open(mode="w") as fp:
-            yaml_data = strictyaml.as_document(data)
-            fp.write(yaml_data.as_yaml())
-
-    @classmethod
-    def yaml_create(
-        cls: type[Settings],
-        filepath: pathlib.Path,
-    ) -> Settings:  # pragma: no cover
-        """Create the YAML file with this object."""
-        data = cls()
-        data.yaml_write(filepath)
-        return data
-
-
-@functools.cache
-def get() -> Settings:  # pragma: no cover
-    """Get the Settings object instance."""
-    filepath = const.PATHS.CONFIG / const.SETTINGS_FILENAME
-    instance: Settings
-    try:
-        instance = Settings.yaml_read(filepath)
-    except FileNotFoundError:
-        const.PATHS.CONFIG.mkdir(parents=True, exist_ok=True)
-        instance = Settings.yaml_create(filepath)
-
-    return instance
-
-
-@contextlib.contextmanager
-def modify() -> collections.abc.Generator[Settings, None, None]:  # pragma: no cover
-    """Provide the Settings object to make a modification and automatically save it."""
-    s = get()
-    try:
-        yield s
-    finally:
-        filepath = const.PATHS.CONFIG / const.SETTINGS_FILENAME
-        s.yaml_write(filepath)

src/playlist/data/sql.py

@@ -1,4 +0,0 @@
-"""Contains the gino DB connection for the application."""
-import gino
-
-db = gino.Gino()

src/playlist/plex/__init__.py

@@ -1 +0,0 @@
-"""Package containing the full plexapi wrapper/implementation."""

src/playlist/plex/server.py

@@ -1,207 +0,0 @@
-"""Contains the code to communicate to the Plex server."""
-import asyncio
-import collections.abc
-import statistics
-import time
-import typing
-
-import plexapi.audio  # type: ignore [import]
-import plexapi.myplex  # type: ignore [import]
-import plexapi.server  # type: ignore [import]
-
-from playlist import utils
-from playlist.data import const
-from playlist.data import models
-from playlist.data import settings
-
-__all__ = ["gen_tracks", "total_track_count"]
-
-throttle = asyncio.BoundedSemaphore(const.MAX_PROCESSES)
-
-
-def calc_delay(times: list[float], weights: list[float]) -> None:
-    """Calculate the process delay.
-
-    This is based on a weighted harmonic mean of the times the processes took in
-    the last run.
-
-    Args:
-        times: The list of times (as seconds) to use for the calculation.
-        weights: The list of weights from 0 to < 1.0 for the calculation.
-    """
-    with settings.modify() as s:
-        avg_time_per_batch = utils.harmonic_mean(times, weights=weights)
-        delay = avg_time_per_batch / const.MAX_PROCESSES
-        s.download.process_delay = round(delay, ndigits=3)
-
-
-def calc_duration(durations: list[int]) -> None:
-    """Calculate the average duration and max tracks to play each day.
-
-    This is based on the geometric mean of the durations of every track loaded from
-    Plex.  The maximum tracks to load for a day is based on the average duration calculated
-    and the amount of time that the system was played the previous day.
-
-    Args:
-        durations: The list of durations (in seconds) for the calculation.
-    """
-    with settings.modify() as s:
-        avg_track_duration = statistics.geometric_mean(durations)
-        s.track.duration = round(avg_track_duration / 1000, ndigits=3)
-        playtime_seconds = s.playlist.playtime.total_seconds()
-        s.playlist.max_tracks = int(playtime_seconds / avg_track_duration)
-
-
-async def gen_tracks(
-    *,
-    batch_size: int = settings.get().download.batch_size,
-) -> collections.abc.AsyncGenerator[models.Track, None]:
-    """Generate all Tracks from the Server, asynchronously.
-
-    Args:
-        batch_size: determines how many Tracks are pulled from the Server at a time.
-
-    Yields:
-        models.Track: The Track that was pulled from Plex.
-    """
-    loop = asyncio.get_running_loop()
-    times = []
-    weights = []
-    durations = []
-    batches = [
-        asyncio.create_task(_downloader(ndx, size, loop))
-        async for ndx, size in _gen_batch_params(batch_size)
-    ]
-    for batch_task in asyncio.as_completed(batches):
-        process_time, batch = await batch_task
-        weight = len(batch) / batch_size
-        times.append(process_time * weight)
-        weights.append(weight)
-        for track in batch:
-            durations.append(track.duration)
-            yield track
-
-    calc_delay(times, weights)
-    calc_duration(durations)
-
-
-async def total_track_count() -> int:
-    """Get the total number of tracks in the server.
-
-    Returns:
-        int: The total number of tracks in plex.
-    """
-    server = plexapi.server.PlexServer(**settings.get().creds.dump())
-    loop = asyncio.get_running_loop()
-    num_tracks: int = await loop.run_in_executor(
-        None,
-        (
-            lambda: typing.cast(
-                int,
-                server.library.section("Music").totalViewSize("track"),
-            )
-        ),
-    )
-    return num_tracks
-
-
-async def _downloader(
-    pos: int,
-    size: int,
-    loop: asyncio.AbstractEventLoop,
-) -> tuple[float, list[models.Track]]:
-    """Download a batch of tracks from Plex, by running it inside a Process Pool.
-
-    Args:
-        pos: The index number of the batch to retrieve.
-        size: The size of the batch to retrieve.
-        loop: The asyncio event loop to use.
-
-    Returns:
-        tuple[float, list[models.Track]: The time (in seconds) to process, and
-        the batch of Tracks that were retrieved, in dictionary form.
-    """
-    async with throttle:
-        start = time.time()
-        batch = await loop.run_in_executor(
-            const.PROCESS_POOL,
-            _get_track_batch,
-            size,
-            pos,
-        )
-        end = time.time()
-    process_time = end - start
-    return process_time, batch
-
-
-def _get_track_batch(
-    size: int,
-    pos: int,
-) -> list[models.Track]:
-    """Get a batch of Tracks from the Plex Server.
-
-    Args:
-        size: The size of the batch to retrieve.
-        pos: The index number of the batch to retrieve.
-
-    Returns:
-        list[models.Track]: The process time and list of Tracks retrieved,
-        in dictionary form.
-    """
-    server = plexapi.server.PlexServer(**settings.get().creds.dump())
-    batch = server.library.section("Music").searchTracks(
-        maxresults=size,
-        container_start=pos,
-        container_size=size,
-    )
-    return [_track_dump(track) for track in batch]
-
-
-def _track_dump(track: plexapi.audio.Track) -> models.Track:
-    """Convert a PlexAPI Audio Track object into a Track in dictionary form.
-
-    Args:
-        track: The PlexAPI Audio Track to convert from.
-
-    Returns:
-        models.Track: The dictionary form for the Track object converted to.
-    """
-    return models.Track(
-        plex_id=track.ratingKey,
-        track_num=track.index,
-        title=track.title,
-        artist=track.artist().title,
-        album_num=track.parentIndex,
-        album=track.parentTitle,
-        album_artist=track.grandparentTitle,
-        duration=track.duration,
-        rating=track.userRating,
-        comments=track.summary,
-        added=track.addedAt,
-        play_count=track.viewCount,
-        played=track.lastViewedAt,
-    )
-
-
-async def _gen_batch_params(
-    batch_size: int,
-) -> collections.abc.AsyncGenerator[tuple[int, int], None]:
-    """Generate parameters for batches to be processed with.
-
-    This slows down processing of the first few batches to allow for different process
-    pool workers to be staggered, and make the processing more smooth.
-
-    Args:
-        batch_size: determines how many Tracks are pulled from the Plex Server at a time.
-
-    Yields:
-        tuple[int, int]: The batch index and batch size to process.
-    """
-    quotient, remainder = divmod(await total_track_count(), batch_size)
-    for ndx in range(quotient):
-        if ndx and ndx < const.MAX_PROCESSES:
-            await asyncio.sleep(settings.get().download.process_delay)
-        yield ndx, batch_size
-    if quotient and quotient < const.MAX_PROCESSES:  # pragma: no cover
-        await asyncio.sleep(settings.get().download.process_delay)
-    yield quotient, remainder

src/playlist/utils.py

@@ -1,40 +0,0 @@
-"""Utility functions & classes used in the application."""
-from __future__ import annotations
-
-import collections.abc
-import contextlib
-import datetime
-
-
-@contextlib.contextmanager
-def time_this() -> collections.abc.Generator[None, None, None]:  # pragma: no cover
-    """Context manager to time the execution of a block of code."""
-    start = datetime.datetime.now()
-    try:
-        yield
-    finally:
-        end = datetime.datetime.now()
-        print(f"Elapsed time: {end - start}")
-
-
-def harmonic_mean(
-    data: collections.abc.Sequence[float],
-    *,
-    weights: collections.abc.Sequence[float] | None = None,
-) -> float:
-    """Calculate the [weighted] harmonic mean of the given data.
-
-    Args:
-        data: The sequence of values to calculate.
-        weights: The sequence of weights to apply to the calculation. If not
-            given it assumes all weights are 1.
-
-    Returns:
-        float: The [weighted] harmonic mean of the data.
-    """
-    if weights is None:  # pragma: no cover
-        weights = [1] * len(data)
-
-    numerator = sum(weights)
-    denominator = sum(weight / value for weight, value in zip(weights, data))
-    return numerator / denominator

tests/data/__init__.py

@@ -1 +0,0 @@
-"""Tests for the playlist.data package."""

tests/data/test_base.py

@@ -1,55 +0,0 @@
-"""Tests for the playlist.data.base module."""
-import dataclasses
-import datetime
-import typing
-
-import pytest
-
-from playlist.data import base
-
-
-@dataclasses.dataclass
-class Dummy(base.BaseData):
-    """Dummy class for tests."""
-
-    name: str
-    some_id: int
-    calc: float
-    flag: bool
-    modified: datetime.datetime
-
-
-@pytest.fixture
-def dummyobj() -> Dummy:
-    """Make a dummy object for testing."""
-    return Dummy(
-        name="Something",
-        some_id=1,
-        calc=0.1,
-        flag=True,
-        modified=datetime.datetime.now(),
-    )
-
-
-@pytest.fixture
-def dummydict(dummyobj: Dummy) -> dict[str, object]:
-    """Make a dummy dictionary for testing."""
-    return {
-        "name": dummyobj.name,
-        "some_id": dummyobj.some_id,
-        "calc": dummyobj.calc,
-        "flag": dummyobj.flag,
-        "modified": "T".join(str(dummyobj.modified).split(" ")),
-    }
-
-
-def test_load(dummydict: dict[str, object], dummyobj: Dummy) -> None:
-    """Validate that <data class>.load() works."""
-    result: Dummy = Dummy.load(dummydict)
-    assert result == dummyobj
-
-
-def test_dump(dummydict: dict[str, typing.Any], dummyobj: Dummy) -> None:
-    """Validate that <data class instance>.dump() works."""
-    result = dummyobj.dump()
-    assert result == dummydict

tests/data/test_settings.py

@@ -1,35 +0,0 @@
-"""Tests for validating the Settings object."""
-import base64
-import os
-import pathlib
-
-import pytest
-
-from playlist.data import settings
-
-
-@pytest.fixture
-def example_settings() -> settings.Settings:
-    """Make testable Settings object."""
-    return settings.Settings(
-        creds=settings.CredentialSettings(
-            baseurl="http://nowhere.huh",
-            token=base64.b64encode(os.urandom(8)).decode("utf-8"),
-        ),
-    )
-
-
-@pytest.fixture
-def settings_filepath(tmp_path: pathlib.Path) -> pathlib.Path:
-    """Get the path to use for the settings file."""
-    return tmp_path / "fake_settings.yaml"
-
-
-def test_yaml(
-    example_settings: settings.Settings,
-    settings_filepath: pathlib.Path,
-) -> None:
-    """Test the YAML read/write operations."""
-    example_settings.yaml_write(settings_filepath)
-    result = example_settings.yaml_read(settings_filepath)
-    assert result == example_settings

tests/plex/__init__.py

@@ -1 +0,0 @@
-"""Tests for the playlist.plex package."""

tests/plex/test_server.py

@@ -1,204 +0,0 @@
-"""Tests for the playlist.plex.server module."""
-import asyncio
-import datetime
-import unittest.mock
-
-import pytest
-
-from playlist.data import models
-from playlist.data import settings
-from playlist.plex import server
-
-
-def test_calc_delay(mocker):  # type: ignore [no-untyped-def]
-    """Test the calc_delay function."""
-    mock_settings = mocker.patch("playlist.plex.server.settings")
-    mock_const = mocker.patch("playlist.plex.server.const")
-    mock_s = mock_settings.modify.return_value.__enter__.return_value
-    mock_const.MAX_PROCESSES = 1
-
-    times: list[float] = [100, 100, 100]
-    weights: list[float] = [1, 1, 1]
-
-    server.calc_delay(times, weights)
-
-    result = mock_s.download.process_delay
-
-    assert result == 100
-
-
-def test_calc_duration(mocker):  # type: ignore [no-untyped-def]
-    """Test the calc_duration function."""
-    mock_settings = mocker.patch("playlist.plex.server.settings")
-    durations = [100, 100, 100]
-    mock_s = mock_settings.modify.return_value.__enter__.return_value
-    mock_s.playlist.playtime.total_seconds.return_value = 300
-    server.calc_duration(durations)
-    result = mock_s.playlist.max_tracks
-    assert result == 2
-
-
-@pytest.mark.asyncio
-async def test_gen_tracks(mocker, fake_track):  # type: ignore [no-untyped-def]
-    """Test the gen_tracks asynchronous generator."""
-    mock_downloader = mocker.patch(
-        "playlist.plex.server._downloader",
-        new_callable=unittest.mock.AsyncMock,
-    )
-    mock_gen_batch_params = mocker.patch("playlist.plex.server._gen_batch_params")
-    mock_models = mocker.patch("playlist.plex.server.models")
-    mock_calc_delay = mocker.patch("playlist.plex.server.calc_delay")
-    mock_calc_duration = mocker.patch("playlist.plex.server.calc_duration")
-    mock_downloader.return_value = (1, [fake_track])
-
-    async def fake_gen_batch_params(*args):  # type: ignore
-        for item in [(0, 1), (1, 1)]:
-            yield item
-
-    mock_gen_batch_params.side_effect = fake_gen_batch_params
-    mock_models.Track.load.return_value.duration = 1
-
-    results = [item async for item in server.gen_tracks(batch_size=1)]
-
-    assert len(results) == 2
-    assert mock_calc_delay.called
-    assert mock_calc_duration.called
-
-
-@pytest.mark.asyncio
-async def test_total_track_count(mocker):  # type: ignore [no-untyped-def]
-    """Test the total_track_count coroutine."""
-    mock_plexapi_server = mocker.patch("playlist.plex.server.plexapi.server")
-    mock_server = mock_plexapi_server.PlexServer.return_value
-    mock_total_view_size = mock_server.library.section.return_value.totalViewSize
-    mock_total_view_size.return_value = 1
-
-    result = await server.total_track_count()
-
-    assert result == 1
-
-
-def test_get_creds(mocker):  # type: ignore [no-untyped-def]
-    """Test the get_creds function."""
-    mock_plexapi_myplex = mocker.patch("playlist.plex.server.plexapi.myplex")
-    mock_input = mocker.patch("builtins.input")
-    mock_getpass = mocker.patch("playlist.plex.server.getpass")
-    mock_account = mock_plexapi_myplex.MyPlexAccount.return_value
-    mock_plex = mock_account.resource.return_value.connect.return_value
-    mock_plex._baseurl = "Not a valid URL"
-    mock_plex._token = "Fake token"
-
-    expected = settings.CredentialSettings(
-        baseurl=mock_plex._baseurl,
-        token=mock_plex._token,
-    )
-
-    result = server.get_creds()
-
-    assert result == expected
-    assert mock_input.called
-    assert mock_getpass.getpass.called
-
-
-@pytest.mark.asyncio
-async def test_downloader(mocker):  # type: ignore [no-untyped-def]
-    """Test the _downloader coroutine."""
-
-    async def fake_run_in_executor(*args):  # type: ignore
-        await asyncio.sleep(0.1)
-        return "Fake batch"
-
-    mock_loop = unittest.mock.MagicMock()
-    mock_loop.run_in_executor.side_effect = fake_run_in_executor
-
-    result = await server._downloader(1, 1, mock_loop)
-
-    process_time, batch = result
-
-    assert batch
-    assert process_time >= 0.1
-
-
-@pytest.fixture
-def fake_track(fake_plextrack):  # type: ignore [no-untyped-def]
-    """Make a fake track dict object."""
-    return models.Track(
-        plex_id=fake_plextrack.ratingKey,
-        track_num=fake_plextrack.index,
-        title=fake_plextrack.title,
-        artist=fake_plextrack.artist().title,
-        album_num=fake_plextrack.parentIndex,
-        album=fake_plextrack.parentTitle,
-        album_artist=fake_plextrack.grandparentTitle,
-        duration=fake_plextrack.duration,
-        rating=fake_plextrack.userRating,
-        comments=fake_plextrack.summary,
-        added=fake_plextrack.addedAt,
-        play_count=fake_plextrack.viewCount,
-        played=fake_plextrack.lastViewedAt,
-    )
-
-
-def test_get_track_batch(mocker, fake_track):  # type: ignore [no-untyped-def]
-    """Test _get_track_batch function."""
-    mock_plexapi_server = mocker.patch("playlist.plex.server.plexapi.server")
-    mock_server = mock_plexapi_server.PlexServer.return_value
-    mock_search_tracks = mock_server.library.section.return_value.searchTracks
-    mock_search_tracks.return_value = ["Not a track."]
-    mock_track_dump = mocker.patch("playlist.plex.server._track_dump")
-    mock_track_dump.return_value = fake_track
-
-    result = server._get_track_batch(1, 1)
-
-    assert len(result)
-    assert mock_track_dump.called
-
-
-@pytest.fixture
-def fake_plextrack():  # type: ignore [no-untyped-def]
-    """Mock up a fake Plex track for testing."""
-    mock_track = unittest.mock.MagicMock()
-    mock_track.configure_mock(
-        ratingKey=1,
-        index=1,
-        title="Nothing",
-        parentIndex=1,
-        parentTile="Nothing",
-        grandparentTitle="Nothing",
-        duration=1000,
-        userRating=1,
-        summary="Whatever",
-        addedAt=datetime.datetime.now(),
-        viewCount=1,
-        lastViewedAt=None,
-    )
-    mock_track.artist.return_value.title = "Nothing"
-    return mock_track
-
-
-def test_track_dump(fake_plextrack, fake_track):  # type: ignore [no-untyped-def]
-    """Test the _track_dump function."""
-    result = server._track_dump(fake_plextrack)
-
-    assert result == fake_track
-
-
-@pytest.mark.asyncio
-async def test_gen_batch_params(mocker):  # type: ignore [no-untyped-def]
-    """Test the _gen_batch_params asynchronous generator."""
-    mock_total_track_count = mocker.patch(
-        "playlist.plex.server.total_track_count",
-        new_callable=unittest.mock.AsyncMock,
-    )
-    mock_total_track_count.return_value = 12
-    mock_const = mocker.patch("playlist.plex.server.const")
-    mock_const.MAX_PROCESSES = 10
-    mocker.patch("playlist.plex.server.settings")
-    mocker.patch(
-        "playlist.plex.server.asyncio",
-        new_callable=unittest.mock.AsyncMock,
-    )
-
-    result = [item async for item in server._gen_batch_params(5)]
-
-    assert len(result) == 3