podryk 0.1.0__tar.gz

podryk-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Hadley Jack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

podryk-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: podryk
+Version: 0.1.0
+Summary: A podcast feed generator
+Keywords: podcast,rss,feed,podcasting,audio
+Author: Julien Hadley Jack
+Author-email: Julien Hadley Jack <git@jlhj.de>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Typing :: Typed
+Requires-Dist: content-types>=0.3.0
+Requires-Dist: pydantic-xml[lxml]>=2.18.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/julien-hadleyjack/podryk
+Project-URL: Repository, https://github.com/julien-hadleyjack/podryk
+Project-URL: Issues, https://github.com/julien-hadleyjack/podryk/issues
+Description-Content-Type: text/markdown
+
+# podryk: A podcast feed generator
+
+An RSS 2.0 feed writer for Python for generating Podcast feeds. Supported features:
+
+- [RSS 2.0](http://www.rssboard.org/rss-2-0)
+- [iTunes](https://help.apple.com/itc/podcasts_connect/#/itcb54353390) (Apple Podcast Connect)
+- [Podlove](https://podlove.org/simple-chapters/): chapters
+- [Podcasting 2.0](https://podcasting2.org/docs/podcast-namespace): transcripts & text records
+
+Podryk is opinionated: If there is multiple conflicting specifications for a feature (like chapters), only one will be implemented.
+
+## Installation
+
+You can install the python library with:
+
+```bash
+pip install podryk
+```
+
+## Usage
+
+An example with only required attributes:
+
+<!-- [[[cog
+from scripts.cog_readme import print_example
+from test_readme import test_minimal_feed
+print_example(test_minimal_feed)
+]]] -->
+```python
+from podryk import Enclosure, Episode, Guid, Podcast
+
+feed = Podcast(
+    canonical_link="https://example.com/canonical.rss",
+    title="Podcast title",
+    description="Podcast description",
+    link="https://example.com/episode.html",
+    language="en",
+    explicit=False,
+    image="https://example.com/podcast.png",
+    episodes=[
+        Episode(
+            title="Episode title",
+            guid=Guid(guid="12345678-1234-5678-1234-567812345678"),
+            enclosure=Enclosure(
+                url="https://example.com/audio.mp3",
+                length=30000,
+                type="audio/mpeg",
+            ),
+        )
+    ],
+).to_feed()
+```
+<!-- [[[end]]] -->
+
+An example with all possible attributes:
+
+<!-- [[[cog
+from test_readme import test_full_feed
+print_example(test_full_feed)
+]]] -->
+```python
+from datetime import datetime, timedelta, timezone
+
+from podryk import (
+    Chapter,
+    Enclosure,
+    Episode,
+    EpisodeType,
+    Guid,
+    Podcast,
+    PodcastCategory,
+    PodcastType,
+    TextRecord,
+    Transcript,
+)
+
+feed = Podcast(
+    canonical_link="https://example.com/canonical.rss",
+    title="Podcast title",
+    description="Podcast description",
+    link="https://example.com/episode.html",
+    language="en",
+    copyright="Copyright notice",
+    categories=[
+        PodcastCategory.FILM_REVIEWS,
+        PodcastCategory.FILM_INTERVIEWS,
+    ],
+    explicit=True,
+    image="https://example.com/podcast.png",
+    author="Podcast author",
+    type=PodcastType.SERIAL,
+    complete=False,
+    locked=False,
+    guid="3595bd1c-50a4-504d-baf4-99de513b3737",
+    text_records=[TextRecord(purpose="verify", content="S6lpp-7ZCn8-dZfGc-OoyaG")],
+    episodes=[
+        Episode(
+            title="Episode title",
+            guid=Guid(guid="12345678-1234-5678-1234-567812345678"),
+            enclosure=Enclosure(
+                url="https://example.com/audio.mp3",
+                length=30000,
+                type="audio/mpeg",
+            ),
+            link="https://example.com/episode.html",
+            publication_date=datetime(2014, 6, 20, 10, 35, tzinfo=timezone.utc),
+            description="Episode description",
+            duration=timedelta(hours=1, minutes=10, seconds=50),
+            image="https://example.com/episode.png",
+            explicit=False,
+            season_number=2,
+            episode_number=30,
+            type=EpisodeType.FULL,
+            block=False,
+            transcripts=[
+                Transcript(url="https://example.com/episode.vtt", type="text/vtt"),
+            ],
+            chapters=[
+                Chapter(start=timedelta(seconds=10), title="Episode chapter 1"),
+                Chapter(
+                    start=timedelta(minutes=2),
+                    title="Episode chapter 2",
+                    href="https://example.com/chapter.html",
+                ),
+            ],
+        )
+    ],
+).to_feed()
+```
+<!-- [[[end]]] -->
+
+
+
+## Miscellaneous
+
+Podryk implements a subset from the following Podcast specifications:
+
+- [PSP-1: The Podcast RSS Standard](https://github.com/Podcast-Standards-Project/PSP-1-Podcast-RSS-Specification)
+- [Podcasting 2.0](https://podcasting2.org/docs/podcast-namespace)
+- [Spotify's Podcast Delivery Specification](https://support.spotify.com/us/creators/article/podcast-specification-doc/)
+- [iTunes' Podcast RSS feed requirements](https://podcasters.apple.com/support/823-podcast-requirements)
+
+Create a ticket if you find any deviations from the mentioned specifications. 
+
+You can validate your podcast feed using one of these services:
+
+- https://www.castfeedvalidator.com/
+- https://podba.se/validate/
+- https://podcasters.apple.com/support/829-validate-your-podcast
+

podryk-0.1.0/README.md

@@ -0,0 +1,150 @@
+# podryk: A podcast feed generator
+
+An RSS 2.0 feed writer for Python for generating Podcast feeds. Supported features:
+
+- [RSS 2.0](http://www.rssboard.org/rss-2-0)
+- [iTunes](https://help.apple.com/itc/podcasts_connect/#/itcb54353390) (Apple Podcast Connect)
+- [Podlove](https://podlove.org/simple-chapters/): chapters
+- [Podcasting 2.0](https://podcasting2.org/docs/podcast-namespace): transcripts & text records
+
+Podryk is opinionated: If there is multiple conflicting specifications for a feature (like chapters), only one will be implemented.
+
+## Installation
+
+You can install the python library with:
+
+```bash
+pip install podryk
+```
+
+## Usage
+
+An example with only required attributes:
+
+<!-- [[[cog
+from scripts.cog_readme import print_example
+from test_readme import test_minimal_feed
+print_example(test_minimal_feed)
+]]] -->
+```python
+from podryk import Enclosure, Episode, Guid, Podcast
+
+feed = Podcast(
+    canonical_link="https://example.com/canonical.rss",
+    title="Podcast title",
+    description="Podcast description",
+    link="https://example.com/episode.html",
+    language="en",
+    explicit=False,
+    image="https://example.com/podcast.png",
+    episodes=[
+        Episode(
+            title="Episode title",
+            guid=Guid(guid="12345678-1234-5678-1234-567812345678"),
+            enclosure=Enclosure(
+                url="https://example.com/audio.mp3",
+                length=30000,
+                type="audio/mpeg",
+            ),
+        )
+    ],
+).to_feed()
+```
+<!-- [[[end]]] -->
+
+An example with all possible attributes:
+
+<!-- [[[cog
+from test_readme import test_full_feed
+print_example(test_full_feed)
+]]] -->
+```python
+from datetime import datetime, timedelta, timezone
+
+from podryk import (
+    Chapter,
+    Enclosure,
+    Episode,
+    EpisodeType,
+    Guid,
+    Podcast,
+    PodcastCategory,
+    PodcastType,
+    TextRecord,
+    Transcript,
+)
+
+feed = Podcast(
+    canonical_link="https://example.com/canonical.rss",
+    title="Podcast title",
+    description="Podcast description",
+    link="https://example.com/episode.html",
+    language="en",
+    copyright="Copyright notice",
+    categories=[
+        PodcastCategory.FILM_REVIEWS,
+        PodcastCategory.FILM_INTERVIEWS,
+    ],
+    explicit=True,
+    image="https://example.com/podcast.png",
+    author="Podcast author",
+    type=PodcastType.SERIAL,
+    complete=False,
+    locked=False,
+    guid="3595bd1c-50a4-504d-baf4-99de513b3737",
+    text_records=[TextRecord(purpose="verify", content="S6lpp-7ZCn8-dZfGc-OoyaG")],
+    episodes=[
+        Episode(
+            title="Episode title",
+            guid=Guid(guid="12345678-1234-5678-1234-567812345678"),
+            enclosure=Enclosure(
+                url="https://example.com/audio.mp3",
+                length=30000,
+                type="audio/mpeg",
+            ),
+            link="https://example.com/episode.html",
+            publication_date=datetime(2014, 6, 20, 10, 35, tzinfo=timezone.utc),
+            description="Episode description",
+            duration=timedelta(hours=1, minutes=10, seconds=50),
+            image="https://example.com/episode.png",
+            explicit=False,
+            season_number=2,
+            episode_number=30,
+            type=EpisodeType.FULL,
+            block=False,
+            transcripts=[
+                Transcript(url="https://example.com/episode.vtt", type="text/vtt"),
+            ],
+            chapters=[
+                Chapter(start=timedelta(seconds=10), title="Episode chapter 1"),
+                Chapter(
+                    start=timedelta(minutes=2),
+                    title="Episode chapter 2",
+                    href="https://example.com/chapter.html",
+                ),
+            ],
+        )
+    ],
+).to_feed()
+```
+<!-- [[[end]]] -->
+
+
+
+## Miscellaneous
+
+Podryk implements a subset from the following Podcast specifications:
+
+- [PSP-1: The Podcast RSS Standard](https://github.com/Podcast-Standards-Project/PSP-1-Podcast-RSS-Specification)
+- [Podcasting 2.0](https://podcasting2.org/docs/podcast-namespace)
+- [Spotify's Podcast Delivery Specification](https://support.spotify.com/us/creators/article/podcast-specification-doc/)
+- [iTunes' Podcast RSS feed requirements](https://podcasters.apple.com/support/823-podcast-requirements)
+
+Create a ticket if you find any deviations from the mentioned specifications. 
+
+You can validate your podcast feed using one of these services:
+
+- https://www.castfeedvalidator.com/
+- https://podba.se/validate/
+- https://podcasters.apple.com/support/829-validate-your-podcast
+

podryk-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "podryk"
+version = "0.1.0"
+description = "A podcast feed generator"
+keywords = ["podcast", "rss", "feed", "podcasting", "audio"]
+readme = "README.md"
+authors = [
+    { name = "Julien Hadley Jack", email = "git@jlhj.de" }
+]
+license = "MIT"
+license-files = [
+    "LICENSE.txt",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "content-types>=0.3.0",
+    "pydantic-xml[lxml]>=2.18.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/julien-hadleyjack/podryk"
+Repository = "https://github.com/julien-hadleyjack/podryk"
+Issues = "https://github.com/julien-hadleyjack/podryk/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.6,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+build = [
+    "python-semantic-release>=10.5.3",
+]
+dev = [
+    "cogapp>=3.6.0",
+    "coverage>=7.13.3",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pytest-github-report>=0.0.1",
+    "ruff>=0.15.0",
+    "syrupy>=5.1.0",
+]
+
+[tool.uv]
+required-version = ">=0.9.6"
+
+[tool.pytest.ini_options]
+addopts = ["--snapshot-patch-pycharm-diff"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.semantic_release]
+build_command = """
+    uv lock --upgrade-package "$PACKAGE_NAME"
+    git add uv.lock
+    uv build
+"""
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"
+exclude_commit_patterns = [
+    '''chore(?:\([^)]*?\))?: .+''',
+    '''ci(?:\([^)]*?\))?: .+''',
+    '''refactor(?:\([^)]*?\))?: .+''',
+    '''style(?:\([^)]*?\))?: .+''',
+    '''test(?:\([^)]*?\))?: .+''',
+    '''docs(?:\([^)]*?\))?: .+''',
+    '''build(?:\([^)]*?\))?: .+''',
+    '''build\((?!deps\): .+)''',
+    '''project scaffold''',
+]

podryk-0.1.0/src/podryk/__init__.py

@@ -0,0 +1,18 @@
+from podryk.models.enum import EpisodeType, Explicit, PodcastCategory, PodcastType
+from podryk.models.episode import Episode
+from podryk.models.podcast import Podcast
+from podryk.models.sub_types import Chapter, Enclosure, Guid, TextRecord, Transcript
+
+__all__ = [
+    "Podcast",
+    "Episode",
+    "PodcastType",
+    "EpisodeType",
+    "Explicit",
+    "PodcastCategory",
+    "Guid",
+    "Enclosure",
+    "Transcript",
+    "Chapter",
+    "TextRecord",
+]

podryk-0.1.0/src/podryk/models/enum.py

@@ -0,0 +1,174 @@
+from enum import Enum, StrEnum, auto, unique
+
+
+@unique
+class Explicit(StrEnum):
+    YES = auto()
+    NO = auto()
+    CLEAN = auto()
+
+
+@unique
+class PodcastType(StrEnum):
+    EPISODIC = auto()
+    SERIAL = auto()
+
+
+@unique
+class EpisodeType(StrEnum):
+    FULL = auto()
+    """A complete podcast episode"""
+
+    TRAILER = auto()
+    """A short promotional or preview episode for a podcast"""
+
+    BONUS = auto()
+    """
+    Additional content that is unlike a typical episode
+    (e.g., behind-the-scenes or a promotional episode for another podcast)
+    """
+
+
+@unique
+class AtomLinkRel(StrEnum):
+    ALTERNATE = auto()
+    RELATED = auto()
+    SELF = auto()
+    ENCLOSURE = auto()
+    VIA = auto()
+
+
+@unique
+class PodcastCategory(Enum):
+    ARTS = ("Arts", None)
+    BOOKS = ("Arts", "Books")
+    DESIGN = ("Arts", "Design")
+    FASHION_AND_BEAUTY = ("Arts", "Fashion & Beauty")
+    FOOD = ("Arts", "Food")
+    PERFORMING_ARTS = ("Arts", "Performing Arts")
+    VISUAL_ARTS = ("Arts", "Visual Arts")
+
+    BUSINESS = ("Business", None)
+    CAREERS = ("Business", "Careers")
+    ENTREPRENEURSHIP = ("Business", "Entrepreneurship")
+    INVESTING = ("Business", "Investing")
+    MANAGEMENT = ("Business", "Management")
+    MARKETING = ("Business", "Marketing")
+    NON_PROFIT = ("Business", "Non-Profit")
+
+    COMEDY = ("Comedy", None)
+    COMEDY_INTERVIEWS = ("Comedy", "Comedy Interviews")
+    IMPROV = ("Comedy", "Improv")
+    STAND_UP = ("Comedy", "Stand-Up")
+
+    EDUCATION = ("Education", None)
+    COURSES = ("Education", "Courses")
+    HOW_TO = ("Education", "How To")
+    LANGUAGE_LEARNING = ("Education", "Language Learning")
+    SELF_IMPROVEMENT = ("Education", "Self-Improvement")
+
+    FICTION = ("Fiction", None)
+    COMEDY_FICTION = ("Fiction", "Comedy Fiction")
+    DRAMA = ("Fiction", "Drama")
+    SCIENCE_FICTION = ("Fiction", "Science Fiction")
+
+    GOVERNMENT = ("Government", None)
+
+    HISTORY = ("History", None)
+
+    HEALTH_AND_FITNESS = ("Health & Fitness", None)
+    ALTERNATIVE_HEALTH = ("Health & Fitness", "Alternative Health")
+    FITNESS = ("Health & Fitness", "Fitness")
+    MEDICINE = ("Health & Fitness", "Medicine")
+    MENTAL_HEALTH = ("Health & Fitness", "Mental Health")
+    NUTRITION = ("Health & Fitness", "Nutrition")
+    SEXUALITY = ("Health & Fitness", "Sexuality")
+
+    KIDS_AND_FAMILY = ("Kids & Family", None)
+    EDUCATION_FOR_KIDS = ("Kids & Family", "Education for Kids")
+    PARENTING = ("Kids & Family", "Parenting")
+    PETS_AND_ANIMALS = ("Kids & Family", "Pets & Animals")
+    STORIES_FOR_KIDS = ("Kids & Family", "Stories for Kids")
+
+    LEISURE = ("Leisure", None)
+    ANIMATION_AND_MANGA = ("Leisure", "Animation & Manga")
+    AUTOMOTIVE = ("Leisure", "Automotive")
+    AVIATION = ("Leisure", "Aviation")
+    CRAFTS = ("Leisure", "Crafts")
+    GAMES = ("Leisure", "Games")
+    HOBBIES = ("Leisure", "Hobbies")
+    HOME_AND_GARDEN = ("Leisure", "Home & Garden")
+    VIDEO_GAMES = ("Leisure", "Video Games")
+
+    MUSIC = ("Music", None)
+    MUSIC_COMMENTARY = ("Music", "Music Commentary")
+    MUSIC_HISTORY = ("Music", "Music History")
+    MUSIC_INTERVIEWS = ("Music", "Music Interviews")
+
+    NEWS = ("News", None)
+    BUSINESS_NEWS = ("News", "Business News")
+    DAILY_NEWS = ("News", "Daily News")
+    ENTERTAINMENT_NEWS = ("News", "Entertainment News")
+    NEWS_COMMENTARY = ("News", "News Commentary")
+    POLITICS = ("News", "Politics")
+    SPORTS_NEWS = ("News", "Sports News")
+    TECH_NEWS = ("News", "Tech News")
+
+    RELIGION_AND_SPIRITUALITY = ("Religion & Spirituality", None)
+    BUDDHISM = ("Religion & Spirituality", "Buddhism")
+    CHRISTIANITY = ("Religion & Spirituality", "Christianity")
+    HINDUISM = ("Religion & Spirituality", "Hinduism")
+    ISLAM = ("Religion & Spirituality", "Islam")
+    JUDAISM = ("Religion & Spirituality", "Judaism")
+    RELIGION = ("Religion & Spirituality", "Religion")
+    SPIRITUALITY = ("Religion & Spirituality", "Spirituality")
+
+    SCIENCE = ("Science", None)
+    ASTRONOMY = ("Science", "Astronomy")
+    CHEMISTRY = ("Science", "Chemistry")
+    EARTH_SCIENCES = ("Science", "Earth Sciences")
+    LIFE_SCIENCES = ("Science", "Life Sciences")
+    MATHEMATICS = ("Science", "Mathematics")
+    NATURAL_SCIENCES = ("Science", "Natural Sciences")
+    NATURE = ("Science", "Nature")
+    PHYSICS = ("Science", "Physics")
+    SOCIAL_SCIENCES = ("Science", "Social Sciences")
+
+    SOCIETY_AND_CULTURE = ("Society & Culture", None)
+    DOCUMENTARY = ("Society & Culture", "Documentary")
+    PERSONAL_JOURNALS = ("Society & Culture", "Personal Journals")
+    PHILOSOPHY = ("Society & Culture", "Philosophy")
+    PLACES_AND_TRAVEL = ("Society & Culture", "Places & Travel")
+    RELATIONSHIPS = ("Society & Culture", "Relationships")
+
+    SPORTS = ("Sports", None)
+    BASEBALL = ("Sports", "Baseball")
+    BASKETBALL = ("Sports", "Basketball")
+    CRICKET = ("Sports", "Cricket")
+    FANTASY_SPORTS = ("Sports", "Fantasy Sports")
+    FOOTBALL = ("Sports", "Football")
+    GOLF = ("Sports", "Golf")
+    HOCKEY = ("Sports", "Hockey")
+    RUGBY = ("Sports", "Rugby")
+    RUNNING = ("Sports", "Running")
+    SOCCER = ("Sports", "Soccer")
+    SWIMMING = ("Sports", "Swimming")
+    TENNIS = ("Sports", "Tennis")
+    VOLLEYBALL = ("Sports", "Volleyball")
+    WILDERNESS = ("Sports", "Wilderness")
+    WRESTLING = ("Sports", "Wrestling")
+
+    TECHNOLOGY = ("Technology", None)
+
+    TRUE_CRIME = ("True Crime", None)
+
+    TV_AND_FILM = ("TV & Film", None)
+    AFTER_SHOWS = ("TV & Film", "After Shows")
+    FILM_HISTORY = ("TV & Film", "Film History")
+    FILM_INTERVIEWS = ("TV & Film", "Film Interviews")
+    FILM_REVIEWS = ("TV & Film", "Film Reviews")
+    TV_REVIEWS = ("TV & Film", "TV Reviews")
+
+    def __init__(self, category: str | None, sub_category: str):
+        self.category = category
+        self.sub_category = sub_category

podryk-0.1.0/src/podryk/models/episode.py

@@ -0,0 +1,118 @@
+from datetime import timedelta
+
+from pydantic import Field, PositiveInt
+from pydantic_xml import attr, computed_element, element, wrapped
+
+from podryk.models.enum import EpisodeType
+from podryk.models.field_types import (
+    URL,
+    CData,
+    DateTime,
+    DurationInSeconds,
+    YesBool,
+)
+from podryk.models.namespaces import NAMESPACES, Namespace
+from podryk.models.sub_types import (
+    Chapter,
+    Chapters,
+    Enclosure,
+    Guid,
+    Transcript,
+)
+from podryk.models.xml_model import XmlModel
+
+
+class Episode(XmlModel, tag="item", nsmap=NAMESPACES):
+    title: str = element()
+    """
+    The title for the podcast episode.
+    
+    The title value is a string containing a concise name for your episode.
+    Title values should not include season or episode numbers, as there are specific elements to capture those values.
+    """
+
+    enclosure: Enclosure = element()
+    """
+    The audio/video episode content, file size, and file type information.
+    
+    Supported file formats include MP3 (.mp3) and MPEG-4 (.m4a, .m4v, .mp4).
+    """
+
+    guid: Guid = element()
+    """
+    The globally unique identifier (GUID) for a podcast episode.
+    
+    Each episode must have a unique GUID that never changes. Values are case-sensitive strings.
+    """
+
+    # Optional fields
+    link: URL | None = element(default=None)
+    """
+    The URL of a web page associated with the podcast episode.
+    
+    Useful when an episode has a corresponding webpage.
+    """
+
+    publication_date: DateTime | None = element(tag="pubDate", default=None)
+    """The release date and time of an episode."""
+
+    description: CData[str | None] = element(default=None)
+    """
+    The description of the podcast episode.
+    """
+
+    # Fields from itunes namespace
+
+    duration: DurationInSeconds[timedelta | None] = element(ns=Namespace.ITUNES, default=None)
+    """The duration of a podcast episode in seconds."""
+
+    image: URL | None = wrapped(
+        "image",
+        ns=Namespace.ITUNES,
+        entity=attr(name="href", default=None),
+    )
+    """
+    The episode-specific artwork.
+    
+    Verify the web server hosting your image allows HTTP head requests.
+    
+    Image must be a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels,
+    in JPEG or PNG format, 72 dpi, with appropriate file extensions (.jpg, .png), and in the sRGB colorspace.
+    File type extension must match the actual file type of the image file.
+    """
+    explicit: bool | None = element(ns=Namespace.ITUNES, default=None)
+    """
+    The parental advisory information for a podcast episode.
+    
+    The value can be true, indicating the presence of explicit content, or false,
+    indicating that a podcast doesn’t contain explicit language or adult content.
+    """
+
+    season_number: PositiveInt | None = element(tag="season", ns=Namespace.ITUNES, default=None)
+    """The chronological number associated with a podcast episode's season."""
+
+    episode_number: PositiveInt | None = element(tag="episode", ns=Namespace.ITUNES, default=None)
+    """
+    The chronological number that is associated with a podcast episode.
+    
+    This is required for serial podcasts.
+    """
+
+    type: EpisodeType | None = element(tag="episodeType", ns=Namespace.ITUNES, default=None)
+    """Defines the type of content for a specific podcast episode."""
+
+    block: YesBool[bool | None] = element(ns=Namespace.ITUNES, default=None)
+    """Prevents a specific episode from appearing in podcast listening applications."""
+
+    # Fields from podcast namespace
+
+    transcripts: list[Transcript] | None = element(default=None)
+    """A link to a transcript or closed captions file. Multiple tags can be present for multiple formats."""
+
+    # Fields from podlove namespace
+
+    chapters: list[Chapter] | None = Field(exclude=True, default=None)
+
+    @computed_element
+    def _chapters(self) -> Chapters | None:
+        return Chapters(chapters=self.chapters) if self.chapters else None

podryk-0.1.0/src/podryk/models/field_types.py

@@ -0,0 +1,156 @@
+from datetime import datetime, timedelta
+from email.utils import format_datetime
+from typing import Annotated, TypeVar
+from uuid import UUID
+
+import content_types
+from lxml.etree import CDATA
+from pydantic import (
+    AfterValidator,
+    AwareDatetime,
+    BeforeValidator,
+    HttpUrl,
+    PlainSerializer,
+    StringConstraints,
+)
+from pydantic_xml import BaseXmlModel, XmlFieldSerializer
+from pydantic_xml.element import XmlElementWriter
+
+
+def _bool_to_yes_no(value: bool | None) -> str:
+    return "yes" if value else "no"
+
+
+def _bool_to_yes(value: bool | None) -> str | None:
+    return "yes" if value else None
+
+
+def _bool_to_true_false(value: bool | None) -> str:
+    return "true" if value else "false"
+
+
+def _timedelta_to_seconds(value: timedelta | None) -> str | None:
+    return None if value is None else round(value.total_seconds())
+
+
+def _convert_timedelta(value: timedelta | int | None) -> timedelta | None:
+    if isinstance(value, timedelta):
+        return value
+    elif isinstance(value, int):
+        return timedelta(seconds=value)
+    else:
+        return value
+
+
+def _convert_uuid(value: UUID | str | None) -> UUID | None:
+    if isinstance(value, UUID):
+        return value
+    elif isinstance(value, str):
+        return UUID(value)
+    else:
+        return value
+
+
+def _timedelta_to_npt(value: timedelta | None) -> str | None:
+    """Format a timedelta as a Normal Play Time (HH:MM:SS.mmm)."""
+    if value is None:
+        return None
+
+    total_seconds = int(value.total_seconds())
+
+    hours, remainder = divmod(total_seconds, 3_600)
+    minutes, seconds = divmod(remainder, 60)
+    milliseconds = value.microseconds // 1_000
+
+    return f"{hours:02}:{minutes:02}:{seconds:02}.{milliseconds:03}"
+
+
+def _datetime_to_rfc2822_string(value: datetime | None) -> str | None:
+    return None if value is None else format_datetime(value)
+
+
+def _validate_media_type(media_type: str | None) -> str:
+    if (
+        media_type
+        and media_type not in content_types.EXTENSION_TO_CONTENT_TYPE.values()
+    ):
+        raise ValueError(f"{media_type} not a recognized media type")
+    return media_type
+
+
+def _string_to_cdata(
+    _: BaseXmlModel, element: XmlElementWriter, value: str | None, field_name: str
+) -> None:
+    if value:
+        sub_element = element.make_element(tag=field_name, nsmap=None)
+        # noinspection PyTypeChecker
+        sub_element.set_text(CDATA(value))
+        element.append_element(sub_element)
+
+
+def _check_byte_size(max_size: int):
+    def wrapper(value: str | None) -> str | None:
+        actual_size = len(value.encode()) if value else 0
+        if actual_size > max_size:
+            raise ValueError(
+                f"String size of {actual_size} bytes exceeds maximum of {max_size} bytes"
+            )
+        return value
+
+    return wrapper
+
+
+def _check_check_positive_timedelta(value: timedelta | None) -> timedelta | None:
+    if value is not None and value < timedelta():
+        raise ValueError(f"Duration must be positive: {value}")
+    return value
+
+
+def _check_uuid_v5(value: UUID | None):
+    if value is not None and value.version != 5:
+        raise ValueError(
+            f"UUID version 5 expected [version={value.version}, value={value}]"
+        )
+    return value
+
+
+_BoolType = TypeVar("_BoolType", bool, bool | None, default=bool)
+_StringType = TypeVar("_StringType", str, str | None, default=str)
+_DurationType = TypeVar(
+    "_DurationType", timedelta | int, timedelta | int | None, default=timedelta | int
+)
+_UUIDv5Type = TypeVar("_UUIDv5Type", UUID | str, UUID | str, default=UUID | str)
+
+URL = Annotated[str, HttpUrl]
+YesNoBool = Annotated[_BoolType, PlainSerializer(_bool_to_yes_no)]
+YesBool = Annotated[_BoolType, PlainSerializer(_bool_to_yes)]
+MediaType = Annotated[_StringType, AfterValidator(_validate_media_type)]
+CData = Annotated[
+    _StringType,
+    XmlFieldSerializer(_string_to_cdata),
+    AfterValidator(_check_byte_size(max_size=4000)),
+]
+DurationInSeconds = Annotated[
+    _DurationType,
+    BeforeValidator(_convert_timedelta),
+    AfterValidator(_check_check_positive_timedelta),
+    PlainSerializer(_timedelta_to_seconds),
+]
+DateTime = Annotated[
+    datetime, AwareDatetime, PlainSerializer(_datetime_to_rfc2822_string)
+]
+Duration = Annotated[
+    _DurationType,
+    BeforeValidator(_convert_timedelta),
+    AfterValidator(_check_check_positive_timedelta),
+    PlainSerializer(_timedelta_to_npt),
+]
+Language = Annotated[
+    _StringType, StringConstraints(pattern=r"^[a-z]{2,3}(?:-[a-z]{2})?$", to_lower=True)
+]
+UUIDv5 = Annotated[
+    _UUIDv5Type,
+    BeforeValidator(_convert_uuid),
+    # can't use pydantic.types.UuidVersion(5) because it doesn't support nullable types
+    AfterValidator(_check_uuid_v5),
+]

podryk-0.1.0/src/podryk/models/namespaces.py

@@ -0,0 +1,25 @@
+# noinspection HttpUrlsUsage
+class Namespace(object):
+    ITUNES = "itunes"
+    PODCAST = "podcast"
+    ATOM = "atom"
+    CONTENT = "content"
+    """Vocabulary for handling encoded content."""
+
+    MEDIA = "media"
+    DC_TERMS = "dcterms"
+    """Dublin Core metadata terms to describe discovery/availability."""
+
+    CHAPTERS = "psc"
+    """Podlove's Simple Chapter for episode chapters."""
+
+
+NAMESPACES = {
+    Namespace.ITUNES: "http://www.itunes.com/dtds/podcast-1.0.dtd",
+    Namespace.PODCAST: "https://podcastindex.org/namespace/1.0",
+    Namespace.ATOM: "http://www.w3.org/2005/Atom",
+    Namespace.CONTENT: "http://purl.org/rss/1.0/modules/content/",
+    Namespace.MEDIA: "http://search.yahoo.com/mrss/",
+    Namespace.DC_TERMS: "http://purl.org/dc/terms/",
+    Namespace.CHAPTERS: "http://podlove.org/simple-chapters",
+}

podryk-0.1.0/src/podryk/models/podcast.py

@@ -0,0 +1,159 @@
+from typing import List
+from uuid import UUID
+
+from pydantic import Field
+from pydantic_xml import BaseXmlModel, attr, computed_element, element, wrapped
+
+from podryk.models.enum import PodcastCategory, PodcastType
+from podryk.models.episode import Episode
+from podryk.models.field_types import URL, CData, Language, UUIDv5, YesBool, YesNoBool
+from podryk.models.namespaces import NAMESPACES, Namespace
+from podryk.models.sub_types import AtomLink, Category, TextRecord
+from podryk.models.xml_model import XmlModel
+
+
+class Podcast(XmlModel, tag="channel", nsmap=NAMESPACES):
+    canonical_link: URL = Field(exclude=True)
+    """The declared canonical feed URL for the podcast."""
+
+    title: str = element()
+    """
+    The podcast title. A string containing the name of a podcast and nothing else.
+    
+    Including keywords in an attempt to improve a podcast's search ranking,
+    may result in being blocked from certain directories.
+    """
+
+    description: CData = element()
+    """Text that describes a podcast to potential listeners."""
+
+    link: URL = element()
+    """The website or web page associated with a podcast."""
+
+    language: Language = element()
+    """The language that is spoken on the podcast, specified in the ISO 639 format."""
+
+    episodes: List[Episode] = element(min_length=1)
+    """Episodes in the podcast."""
+
+    copyright: str | None = element(default=None)
+    """
+    The copyright details for a podcast.
+    
+    Should not include the word "Copyright", the © symbol, and/or a year.
+    """
+
+    # Fields from itunes namespace
+
+    categories: List[PodcastCategory] = element(exclude=True, default_factory=list)
+    """
+    The category that best fits a podcast, selected from the list of Apple Podcasts categories:
+    https://podcasters.apple.com/support/1691-apple-podcasts-categories
+    """
+
+    explicit: bool = element(ns=Namespace.ITUNES)
+    """The parental advisory information for a podcast."""
+
+    image: URL | None = wrapped(
+        "image",
+        ns=Namespace.ITUNES,
+        entity=attr(name="href", default=None),
+    )
+    """
+    The artwork for the podcast, specified by providing a URL linking to it.
+    
+    Verify the web server hosting your image allows HTTP head requests.
+
+    Image must be a minimum size of 1400 x 1400 pixels and a maximum size of 3000 x 3000 pixels,
+    in JPEG or PNG format, 72 dpi, with appropriate file extensions (.jpg, .png), and in the RGB colorspace.
+    File type extension must match the actual file type of the image file.
+    """
+
+    author: str | None = element(ns=Namespace.ITUNES, default=None)
+    """The group, person, or people responsible for creating the podcast."""
+
+    type: PodcastType | None = element(ns=Namespace.ITUNES, default=None)
+    """
+    Specifies the podcast as either episodic or serial.
+    
+    Episodic is the default and assumed if this element is not present. This element is required for serial podcasts.
+    """
+
+    complete: YesBool[bool | None] = element(ns=Namespace.ITUNES, default=None)
+    """Specifies that a podcast is complete and will not post any more episodes in the future."""
+
+    # Fields from podcast namespace
+
+    locked: YesNoBool[bool | None] = element(ns=Namespace.PODCAST, default=None)
+    """Tells podcast hosting platforms whether they are allowed to import this feed."""
+
+    guid: UUIDv5[UUID | str] | None = element(
+        ns=Namespace.PODCAST, default=None
+    )
+    """
+    The globally unique identifier (GUID) for a podcast.
+    
+    The value is a UUIDv5, and generated from the RSS feed URL,
+    with the protocol scheme and trailing slashes stripped off,
+    combined with a unique "podcast" namespace which has a UUID of ead4c236-bf58-58c6-a2c6-a6b28d128cb6.
+    
+    A podcast should be assigned a <podcast:guid> once in its lifetime,
+    using its current feed URL at the time of assignment as the seed value.
+    That GUID is then meant to follow the podcast from then on, for the duration of its existence,
+    even if the feed URL changes. This means that when a podcast moves from one hosting platform to another,
+    its <podcast:guid> should be discovered by the new host and imported into the new platform for inclusion
+    into the feed.
+
+    Using this pattern, podcasts can maintain a consistent identity across the open podcasting ecosystem without
+    the need for a central authority.
+    """
+
+    text_records: list[TextRecord] | None = element(default=None)
+    """
+    A free-form text field to present a string in a podcast feed.
+    
+    One use case of this is to verify ownership. For example, a show owner may be asked 
+    to add a unique text field to prove that they control the feed (and therefore the show).
+    """
+
+    @computed_element
+    def _canonical_link(self) -> AtomLink:
+        if isinstance(self.canonical_link, AtomLink):
+            return self.canonical_link
+        else:
+            return AtomLink(href=self.canonical_link)
+
+    @computed_element
+    def _categories(self) -> list[Category] | None:
+        results: dict[str, Category] = {}
+        for category in self.categories:
+            category_name, sub_category_name = category.category, category.sub_category
+
+            # Add parent category
+            if category_name not in results:
+                results[category.category] = Category(text=category_name)
+
+            parent = results[category.category]
+
+            # Add sub category
+            if sub_category_name and all(
+                sub_category.text != sub_category
+                for sub_category in parent.sub_categories
+            ):
+                parent.sub_categories.append(Category(text=sub_category_name))
+
+        return list(results.values())
+
+    def to_feed(self) -> bytes:
+        return _PodcastFeed(channel=self).to_xml(
+            xml_declaration=True,
+            pretty_print=True,
+            encoding="UTF-8",
+            exclude_none=True,
+            skip_empty=True,
+        )
+
+
+class _PodcastFeed(BaseXmlModel, tag="rss", nsmap=NAMESPACES):
+    version: str = attr(default="2.0")
+    channel: Podcast = element()

podryk-0.1.0/src/podryk/models/sub_types.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import uuid
+
+from pydantic import (
+    HttpUrl,
+    TypeAdapter,
+    ValidationError,
+    model_validator,
+)
+from pydantic_xml import attr, element
+
+from podryk.models.enum import AtomLinkRel
+from podryk.models.field_types import URL, Duration, MediaType
+from podryk.models.namespaces import NAMESPACES, Namespace
+from podryk.models.xml_model import XmlModel
+
+
+class Guid(XmlModel, tag="guid"):
+    """Globally unique identifier for an episode."""
+
+    is_permalink: bool | None = attr(name="isPermaLink")
+    guid: str | URL | uuid.UUID
+
+    @model_validator(mode="before")
+    @classmethod
+    def set_permalink_default(cls, data: dict) -> dict:
+        guid = data.get("guid")
+        is_permalink = data.get("is_permalink")
+
+        if is_permalink is None:
+            try:
+                TypeAdapter(HttpUrl).validate_python(guid)
+                data["is_permalink"] = None
+            except ValidationError:
+                data["is_permalink"] = False
+
+        return data
+
+
+class Enclosure(XmlModel, tag="enclosure"):
+    """The audio/video episode content, file size, and file type information."""
+
+    url: URL = attr()
+    """Location of the media file."""
+
+    length: int = attr()
+    """The length of the file in bytes."""
+
+    type: MediaType = attr()
+    """MIME type of the media file."""
+
+
+class Transcript(XmlModel, tag="transcript", ns=Namespace.PODCAST):
+    url: URL = attr()
+    type: MediaType = attr()
+    language: str | None = attr(default=None)
+
+
+class Chapter(XmlModel, tag="chapter", ns=Namespace.CHAPTERS):
+    start: Duration = attr()
+    """Refers to a point in time relative to the start of the media file."""
+    title: str = attr()
+    """Title of the chapter."""
+    href: URL | None = attr(default=None)
+    """External link that provides related information to the chapter."""
+
+    image: URL | None = attr(default=None)
+    """External link to an image associated with the chapter. The image should have a 1:1 aspect ratio."""
+
+
+class Chapters(XmlModel, tag="chapters", ns=Namespace.CHAPTERS):
+    version: str = attr(default="1.2")
+    chapters: list[Chapter] = element()
+
+
+class AtomLink(XmlModel, tag="link", ns=Namespace.ATOM):
+    href: URL = attr()
+    rel: AtomLinkRel = attr(default=AtomLinkRel.SELF)
+    type: MediaType = attr(default="application/rss+xml")
+
+
+class TextRecord(XmlModel, tag="txt", ns=Namespace.PODCAST):
+    """
+    A free-form text field to present a string in a podcast feed.
+
+    One use case of this is to verify ownership. For example, a show owner may be asked
+    to add a unique text field to prove that they control the feed (and therefore the show).
+    """
+
+    purpose: str | None = attr(default=None)
+    """A service specific string to denote the purpose for the field."""
+
+    content: str
+
+
+class Category(XmlModel, tag="category", ns=Namespace.ITUNES, nsmap=NAMESPACES):
+    text: str = attr()
+    sub_categories: list[Category] = element(default_factory=list)

podryk-0.1.0/src/podryk/models/xml_model.py

@@ -0,0 +1,11 @@
+from abc import ABC
+
+from pydantic import ConfigDict
+from pydantic_xml import BaseXmlModel
+
+
+class XmlModel(BaseXmlModel, ABC):
+    model_config = ConfigDict(
+        use_attribute_docstrings=True,
+        extra="forbid",
+    )