### Complete Podcast Feed Configuration

Source: https://context7.com/tobinus/python-podgen/llms.txt

Provides a comprehensive example of setting up a podcast with metadata, authors, categories, and media attachments. It illustrates the workflow for creating a professional-grade RSS feed.

```python
from podgen import (
    Podcast, Episode, Media, Person, Category, htmlencode,
    EPISODE_TYPE_FULL, EPISODE_TYPE_TRAILER
)
import datetime
import pytz

podcast = Podcast(
    name="The Developer's Journey",
    website="https://devjourney.example.com",
    description="Weekly interviews with software developers sharing their career stories",
    explicit=False,
    language="en",
    copyright="Copyright 2024 DevJourney Media",
    subtitle="Real stories from real developers"
)

podcast.authors = [Person("Sarah Chen", "sarah@devjourney.example.com")]
podcast.owner = Person("DevJourney Media", "podcast@devjourney.example.com")
podcast.category = Category("Technology")
podcast.image = "https://devjourney.example.com/cover-art.jpg"
podcast.feed_url = "https://devjourney.example.com/feed.rss"
podcast.is_serial = False

trailer = podcast.add_episode()
trailer.title = "Coming Soon: The Developer's Journey"
trailer.episode_type = EPISODE_TYPE_TRAILER
trailer.summary = htmlencode("Get ready for inspiring developer stories!")
trailer.publication_date = datetime.datetime(2024, 1, 1, 8, 0, 0, tzinfo=pytz.utc)
trailer.media = Media(
    url="https://devjourney.example.com/episodes/trailer.mp3",
    size="5 MB",
    duration=datetime.timedelta(minutes=2, seconds=30)
)
```

--------------------------------

### Initialize a new Podcast instance in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Demonstrates how to create a blank Podcast object using the constructor without any arguments. This is the starting point for building a podcast feed.

```python
from podgen import Podcast
p = Podcast()
```

--------------------------------

### Install PodGen via pip

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/installation.rst

Standard command to install the PodGen package from PyPI. It is recommended to run this command within an isolated virtual environment.

```bash
pip install podgen
```

--------------------------------

### Install compatible lxml for Python 3.4

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/installation.rst

Command to install a version of lxml compatible with Python 3.4, as newer versions of lxml dropped support. This may require local build tools to compile the package.

```bash
pip install 'lxml<4.4.0'
```

--------------------------------

### URL Encoding for Media Files in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Provides an example of how to correctly encode special characters in media file URLs to ensure they are accessible. It demonstrates using `urllib.parse.quote` for Python 3.

```python
import urllib.parse

# Example with a filename containing a hash symbol
original_url = "http://podcast.example.org/episodes/library-pod-#023-future.mp3"
encoded_url = urllib.parse.quote(original_url)

# The correct URL would be:
# "http://podcast.example.org/episodes/library-pod-%23023-future.mp3"
```

--------------------------------

### Initialize Media from Server Response

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Creates a Media object by querying the hosting server for metadata. It automatically populates size and type from headers if not provided.

```python
from datetime import timedelta
from podgen import Media

my_episode.media = Media.create_from_server_response(
    "http://example.com/podcast/s01e10.mp3",
    duration=timedelta(hours=1, minutes=2, seconds=36)
)
```

--------------------------------

### Initialize Podcast Object with Keyword Arguments (Python)

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Demonstrates a shortcut for creating and populating a podgen.Podcast object in a single statement. By using attribute names as keyword arguments to the constructor, you can define the podcast's properties more concisely, which is useful within list comprehensions or dictionaries.

```Python
import podgen
p = podgen.Podcast(
    <attribute name>=<attribute value>,
    <attribute name>=<attribute value>,
    ...
)
```

--------------------------------

### Podcast Creation and Mandatory Attributes

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Demonstrates how to create a new Podcast instance and set its mandatory attributes required for podcast directories.

```APIDOC
## Creating a new Podcast Instance

### Description
Instantiate a blank podcast using the `Podcast` constructor.

### Method
```python
from podgen import Podcast
p = Podcast()
```

## Mandatory Attributes

### Description
Set the essential attributes for a podcast. These are required by podcast directories like Apple Podcasts.

### Method
```python
p.name = "My Example Podcast"
p.description = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
p.website = "https://example.org"
p.explicit = False
```

### Parameters

#### Request Body
- **name** (string) - Required - The name of the podcast.
- **description** (string) - Required - A description of the podcast.
- **website** (string) - Required - The URL of the podcast's website.
- **explicit** (boolean) - Required - Indicates if the podcast contains explicit content.
```

--------------------------------

### Podcast Class: Create and Configure Podcast Feeds (Python)

Source: https://context7.com/tobinus/python-podgen/llms.txt

Demonstrates how to create a Podcast object, set essential metadata like name, website, and description, and configure optional fields such as language, copyright, owner, and categories. It also shows how to generate the RSS output as a string or save it to a file.

```Python
from podgen import Podcast, Person, Category
import datetime
import pytz

# Create a new podcast with required fields
p = Podcast(
    name="My Tech Podcast",
    website="https://example.com/podcast",
    description="Weekly discussions about technology and programming",
    explicit=False
)

# Add optional metadata
p.language = "en"
p.copyright = "Copyright 2024 Example Inc."
p.subtitle = "Tech insights for developers"
p.image = "https://example.com/podcast-cover.jpg"
p.feed_url = "https://example.com/feeds/podcast.rss"

# Set podcast owner (for iTunes correspondence)
p.owner = Person("John Smith", "john@example.com")

# Add authors (displayed on iTunes)
p.authors = [Person("John Smith", "john@example.com")]

# Set iTunes category with optional subcategory
p.category = Category("Technology")
# Or with subcategory:
# p.category = Category("Leisure", "Video Games")

# Mark podcast as complete (no more episodes)
p.complete = False

# For serial podcasts (episodes should be consumed in order)
p.is_serial = True

# Generate RSS output
rss_string = p.rss_str()
print(rss_string)

# Or write directly to file
p.rss_file("podcast.rss")
```

--------------------------------

### Configure Podcast Media Objects

Source: https://context7.com/tobinus/python-podgen/llms.txt

Demonstrates how to define media for episodes using the Media class. It covers setting URLs, sizes, MIME types, durations, and automatic fetching from local or remote sources.

```python
from podgen import Media
import datetime

ep.media = Media(url="https://example.com/episodes/ep1.mp3", size=45678901, duration=datetime.timedelta(hours=1, minutes=23, seconds=45))
ep.media = Media(url="https://example.com/episodes/ep1.mp3", size=45678901, type="audio/mpeg", duration=datetime.timedelta(minutes=45, seconds=30))
ep.media = Media(url="https://example.com/episodes/ep1.mp3", size="45 MB")
ep.media = Media.create_from_server_response(url="https://example.com/episodes/ep1.mp3")
ep.media = Media("https://example.com/ep1.mp3", size=45678901)
ep.media.populate_duration_from("/path/to/local/ep1.mp3")
ep.media.fetch_duration()
print(ep.media.duration_str)
```

--------------------------------

### Podcast Class - Create and Configure Podcast Feeds

Source: https://context7.com/tobinus/python-podgen/llms.txt

Demonstrates how to create and configure a podcast feed using the Podcast class, including setting metadata, owner, authors, categories, and generating the RSS output.

```APIDOC
## Podcast Class - Create and Configure Podcast Feeds

### Description
The `Podcast` class is the main entry point for creating podcast feeds. It manages all podcast-level metadata including name, description, author information, categories, and artwork. Required attributes are `name`, `website`, `description`, and `explicit`.

### Method
Instantiation and attribute assignment

### Endpoint
N/A (Class usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Class instantiation)

### Request Example
```python
from podgen import Podcast, Person, Category
import datetime
import pytz

# Create a new podcast with required fields
p = Podcast(
    name="My Tech Podcast",
    website="https://example.com/podcast",
    description="Weekly discussions about technology and programming",
    explicit=False
)

# Add optional metadata
p.language = "en"
p.copyright = "Copyright 2024 Example Inc."
p.subtitle = "Tech insights for developers"
p.image = "https://example.com/podcast-cover.jpg"
p.feed_url = "https://example.com/feeds/podcast.rss"

# Set podcast owner (for iTunes correspondence)
p.owner = Person("John Smith", "john@example.com")

# Add authors (displayed on iTunes)
p.authors = [Person("John Smith", "john@example.com")]

# Set iTunes category with optional subcategory
p.category = Category("Technology")
# Or with subcategory:
# p.category = Category("Leisure", "Video Games")

# Mark podcast as complete (no more episodes)
p.complete = False

# For serial podcasts (episodes should be consumed in order)
p.is_serial = True

# Generate RSS output
rss_string = p.rss_str()
print(rss_string)

# Or write directly to file
p.rss_file("podcast.rss")
```

### Response
#### Success Response (200)
Returns the podcast RSS feed as a string or writes to a file.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>My Tech Podcast</title>
    <link>https://example.com/podcast</link>
    <description>Weekly discussions about technology and programming</description>
    <language>en</language>
    <copyright>Copyright 2024 Example Inc.</copyright>
    <itunes:subtitle>Tech insights for developers</itunes:subtitle>
    <itunes:author>John Smith</itunes:author>
    <itunes:owner>
      <itunes:name>John Smith</itunes:name>
      <itunes:email>john@example.com</itunes:email>
    </itunes:owner>
    <itunes:category text="Technology">
    </itunes:category>
    <itunes:explicit>no</itunes:explicit>
    <itunes:complete>no</itunes:complete>
    <itunes:type>serial</itunes:type>
    <image>
      <url>https://example.com/podcast-cover.jpg</url>
      <title>My Tech Podcast</title>
      <link>https://example.com/podcast</link>
    </image>
    <atom:link href="https://example.com/feeds/podcast.rss" rel="self" type="application/rss+xml"/>
  </channel>
</rss>
```
```

--------------------------------

### Media Object Creation and Population

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Demonstrates how to create a Media object, populate its fields from server responses, and handle missing information.

```APIDOC
## Media.create_from_server_response

### Description
Creates a Media object, potentially gathering missing information like size and type from server headers.

### Method
`Media.create_from_server_response(url, duration=None)`

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from podgen import Media
from datetime import timedelta

my_episode.media = Media.create_from_server_response(
    "http://example.com/podcast/s01e10.mp3",
    duration=timedelta(hours=1, minutes=2, seconds=36)
)
```

### Response
#### Success Response (200)
N/A (Returns a Media object)

#### Response Example
N/A
```

```APIDOC
## Media Attribute Population

### Description
Explains how attributes like `size`, `type`, and `duration` are populated for a Media object.

### Method
N/A (Attribute behavior)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

### Notes
- `url`: Mandatory.
- `size`: Populated using the `Content-Length` header.
- `type`: Populated using the `Content-Type` header.
- `duration`: Not populated from server; remains `None` unless explicitly fetched.
```

--------------------------------

### Podcast Image Configuration

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Explains how to set the podcast's image, which is crucial for visibility.

```APIDOC
## Podcast Image

### Description
Set the URL for the podcast's image. While technically optional, it's highly recommended for discoverability.

### Method
```python
p.image = "https://example.com/static/example_podcast.png"
```

### Parameters

#### Request Body
- **image** (string) - Required - The URL of the podcast's image.
```

--------------------------------

### Episode Constructor Shortcut

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Demonstrates using the Episode constructor to set multiple attributes at once.

```APIDOC
## Episode Constructor Shortcut

### Description
Instantiate an `Episode` object and set multiple attributes simultaneously using keyword arguments in the constructor, similar to the `Podcast` constructor.

### Method
Constructor

### Endpoint
N/A (Object instantiation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from podgen import Episode

my_episode = Episode(
    title="Example Episode",
    season=1,
    episode_number=1,
    publication_date=datetime.datetime(2023, 1, 1, tzinfo=pytz.utc),
    link="http://example.com/episode/1"
)
```

### Response
#### Success Response (200)
N/A (Object instantiation)

#### Response Example
N/A
```

--------------------------------

### Implementing and Using a Podcast Mixin

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/advanced/extending.rst

Demonstrates how to define a mixin class and integrate it into a Podcast subclass. Proper inheritance order is crucial to ensure that the base Podcast class is processed last in the method resolution order.

```python
class TtlMixin(object):
    # ...

class PodcastWithTtl(TtlMixin, Podcast):
    def __init__(*args, **kwargs):
        super().__init__(*args, **kwargs)

myPodcast = PodcastWithTtl(name="Test", website="http://example.org", explicit=False, description="Testing ttl")
myPodcast.ttl = 90
print(myPodcast)
```

--------------------------------

### Create Bonus or Trailer Episodes

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Demonstrates how to add bonus or trailer content to a podcast by setting the episode_type attribute.

```python
from podgen import Podcast, EPISODE_TYPE_BONUS
my_podcast = Podcast()
my_episode = my_podcast.add_episode()
my_episode.title = "The history of Acme Industries"
my_episode.season = 1
my_episode.episode_number = 9
my_bonus = my_podcast.add_episode()
my_bonus.title = "Full interview with John Doe about Acme Industries"
my_bonus.episode_type = EPISODE_TYPE_BONUS
my_bonus.season = 1
my_bonus.episode_number = 9
```

--------------------------------

### Setting Publication Date and Link

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Demonstrates how to set the publication date and a relevant link for a podcast episode.

```APIDOC
## Setting Publication Date and Link

### Description
Set the publication date and a link to an associated article or resource for a podcast episode.

### Method
Attribute Assignment

### Endpoint
N/A (Object attribute assignment)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import datetime
import pytz

# Assuming my_episode is an instance of podgen.Episode
my_episode.publication_date = datetime.datetime(2016, 5, 18, 10, 0, tzinfo=pytz.utc)
my_episode.link = "http://example.com/article/2016/05/18/Best-example"
```

### Response
#### Success Response (200)
N/A (Attribute assignment)

#### Response Example
N/A
```

--------------------------------

### Populate Episode Details in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Shows how to set the title, subtitle, summary, and long summary for a podcast episode. It highlights the requirement that an episode must have at least a title or a summary.

```python
my_episode.title = "S01E10: The Best Example of them All"
my_episode.subtitle = "We found the greatest example!"
my_episode.summary = "In this week's episode, we have found the " + \
                     "<i>greatest</i> example of them all."
my_episode.long_summary = "In this week's episode, we went out on a " + \
    "search to find the <i>greatest</i> example of them " + \
    "all. <br/>Today's intro music: " + \
    "<a href='https://www.youtube.com/watch?v=dQw4w9WgXcQ'>Example Song</a>"
```

--------------------------------

### Execute Main Function in Podgen

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/example.rst

This snippet demonstrates the main entry point function for the podgen package. It is designed to be executed as a script and is used primarily for testing and package validation.

```python
def main():
    from podgen import Podcast, Episode, Media
    import datetime

    p = Podcast()
    p.name = "Test Podcast"
    p.description = "A test podcast"
    p.website = "http://example.com"
    p.language = "en"

    e = Episode()
    e.title = "Test Episode"
    e.media = Media("http://example.com/test.mp3", 1000, "audio/mpeg")
    e.publication_date = datetime.datetime.now()
    p.add_episode(e)

    print(p.rss_str())
```

--------------------------------

### Attach Media to Podcast Episode in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Illustrates how to attach media files to a podcast episode using the `Media` class. It includes setting the URL, size, MIME type, and duration of the media.

```python
from datetime import timedelta
from podgen import Media

my_episode.media = Media("http://example.com/podcast/s01e10.mp3",
                         size=17475653,
                         type="audio/mpeg",
                         duration=timedelta(hours=1, minutes=2, seconds=36)
                        )
```

--------------------------------

### Configure a serial Podcast in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Explains how to mark a podcast as 'serial', meaning episodes should be consumed in order. This requires setting the `is_serial` attribute to True and is recommended to also set episode numbers and seasons.

```python
p.is_serial = True
```

--------------------------------

### Set common optional Podcast attributes in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Demonstrates setting commonly used optional attributes for a Podcast, such as copyright information, language, author details, feed URL, category, owner, and XSLT stylesheet.

```python
p.copyright = "2016 Example Radio"
p.language = "en-US"
p.authors = [Person("John Doe", "editor@example.org")]
p.feed_url = "https://example.com/feeds/podcast.rss"
p.category = Category("Music", "Music History")
p.owner = p.authors[0]
p.xslt = "https://example.com/feed/stylesheet.xsl"
```

--------------------------------

### Set mandatory Podcast attributes in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Shows how to set the essential attributes required by podcast directories like Apple's. These include the podcast's name, description, website URL, and explicit content flag.

```python
p.name = "My Example Podcast"
p.description = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
p.website = "https://example.org"
p.explicit = False
```

--------------------------------

### Episode Class: Define Individual Podcast Episodes (Python)

Source: https://context7.com/tobinus/python-podgen/llms.txt

Illustrates how to create and configure an Episode object, including setting its title, summary, publication date, and linking to media. It covers advanced options like long summaries, author information, artwork, season/episode numbers, episode types, and custom ordering.

```Python
from podgen import Podcast, Episode, Media, Person, htmlencode
import datetime
import pytz

p = Podcast(
    name="Developer Stories",
    website="https://example.com",
    description="Interviews with developers",
    explicit=False
)

# Create episode using add_episode() shortcut
ep = p.add_episode()
ep.title = "Episode 1: Getting Started with Python"
ep.summary = htmlencode("In this episode, we discuss Python basics and best practices.")
ep.long_summary = htmlencode("""
    <p>Join us for an in-depth discussion about Python programming.</p>
    <p>Topics covered:</p>
    <ul>
        <li>Setting up your development environment</li>
        <li>Python syntax fundamentals</li>
        <li>Best practices for beginners</li>
    </ul>
""")
ep.link = "https://example.com/episodes/1"
ep.publication_date = datetime.datetime(2024, 1, 15, 10, 0, 0, tzinfo=pytz.utc)

# Set episode-specific authors (optional, defaults to podcast authors)
ep.authors = [Person("Jane Doe", "jane@example.com")]

# Episode-specific explicit setting (overrides podcast default)
ep.explicit = False

# Episode-specific artwork
ep.image = "https://example.com/episodes/ep1-cover.jpg"

# For serial podcasts: season and episode numbers
ep.season = 1
ep.episode_number = 1

# Episode type: full, trailer, or bonus
from podgen import EPISODE_TYPE_FULL, EPISODE_TYPE_TRAILER, EPISODE_TYPE_BONUS
ep.episode_type = EPISODE_TYPE_FULL

# Custom episode ordering on iTunes
ep.position = 1

# Block episode from iTunes (but still public in RSS)
ep.withhold_from_itunes = False

# Video episodes with closed captioning
ep.is_closed_captioned = False

print(p.rss_str())
```

--------------------------------

### Add Episode to Podcast using Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Demonstrates how to create a new podcast episode and add it to a podcast object. It shows both direct appending to the episodes list and using the `add_episode` convenience method.

```python
from podgen import Podcast, Episode

p = Podcast()
my_episode = Episode()
p.episodes.append(my_episode)
```

```python
from podgen import Podcast

p = Podcast()
my_episode = p.add_episode()
```

```python
from podgen import Podcast, Episode

p = Podcast()
my_episode = p.add_episode(Episode())
```

--------------------------------

### Combining Multiple Podcast Mixins

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/advanced/extending.rst

Shows how to create specialized podcast classes by composing multiple mixins. This approach allows for modular feature sets without duplicating code or creating rigid inheritance hierarchies.

```python
class PodcastWithTtlAndTextInput(TtlMixin, TextInputMixin, Podcast):
    def __init__(*args, **kwargs):
        super().__init__(*args, **kwargs)

class PodcastWithTextInputAndComments(TextInputMixin, CommentsMixin, Podcast):
    def __init__(*args, **kwargs):
        super().__init__(*args, **kwargs)
```

--------------------------------

### Creating Bonuses and Trailers

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Details on how to create bonus episodes or trailers by setting the episode_type attribute.

```APIDOC
## Creating Bonuses and Trailers

### Description
Create bonus episodes or trailers by setting the `episode_type` attribute. This attribute, combined with season and episode numbers, indicates the relationship to a regular episode, season, or the podcast itself.

### Method
Attribute Assignment

### Endpoint
N/A (Object attribute assignment)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from podgen import Podcast, EPISODE_TYPE_BONUS

my_podcast = Podcast()
# ... fill podcast details ...

# Create a regular episode
my_episode = my_podcast.add_episode()
my_episode.title = "The history of Acme Industries"
my_episode.season = 1
my_episode.episode_number = 9

# Create a bonus episode for the regular episode
my_bonus = my_podcast.add_episode()
my_bonus.title = "Full interview with John Doe about Acme Industries"
my_bonus.episode_type = EPISODE_TYPE_BONUS
my_bonus.season = 1
my_bonus.episode_number = 9
```

### Response
#### Success Response (200)
N/A (Attribute assignment)

#### Response Example
N/A
```

--------------------------------

### POST /episodes

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Create and add a new episode to a podcast feed.

```APIDOC
## POST /episodes

### Description
Creates a new episode instance and appends it to the podcast's episode list.

### Method
POST

### Endpoint
/episodes

### Parameters
#### Request Body
- **title** (string) - Optional - The title of the episode.
- **summary** (string) - Optional - A brief summary of the episode.
- **subtitle** (string) - Optional - A short subtitle for the episode.
- **long_summary** (string) - Optional - A detailed description of the episode content.

### Request Example
{
  "title": "S01E10: The Best Example",
  "summary": "In this week's episode, we discuss examples."
}

### Response
#### Success Response (200)
- **episode** (object) - The created episode object.

#### Response Example
{
  "status": "success",
  "episode_id": "123"
}
```

--------------------------------

### Episode Class - Define Individual Podcast Episodes

Source: https://context7.com/tobinus/python-podgen/llms.txt

Illustrates how to create and configure individual podcast episodes using the Episode class, including setting titles, summaries, publication dates, authors, media attachments, and episode-specific metadata.

```APIDOC
## Episode Class - Define Individual Podcast Episodes

### Description
The `Episode` class represents a single podcast episode. Episodes must have either a `title` or `summary` set. Episodes are added to a podcast via the `add_episode()` method or by appending to the `episodes` list.

### Method
Instantiation and attribute assignment

### Endpoint
N/A (Class usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Class instantiation)

### Request Example
```python
from podgen import Podcast, Episode, Media, Person, htmlencode
import datetime
import pytz

p = Podcast(
    name="Developer Stories",
    website="https://example.com",
    description="Interviews with developers",
    explicit=False
)

# Create episode using add_episode() shortcut
ep = p.add_episode()
ep.title = "Episode 1: Getting Started with Python"
ep.summary = htmlencode("In this episode, we discuss Python basics and best practices.")
ep.long_summary = htmlencode(
    "<p>Join us for an in-depth discussion about Python programming.</p>"
    "<p>Topics covered:</p>"
    "<ul>"
        "<li>Setting up your development environment</li>"
        "<li>Python syntax fundamentals</li>"
        "<li>Best practices for beginners</li>"
    "</ul>"
)
ep.link = "https://example.com/episodes/1"
ep.publication_date = datetime.datetime(2024, 1, 15, 10, 0, 0, tzinfo=pytz.utc)

# Set episode-specific authors (optional, defaults to podcast authors)
ep.authors = [Person("Jane Doe", "jane@example.com")]

# Episode-specific explicit setting (overrides podcast default)
ep.explicit = False

# Episode-specific artwork
ep.image = "https://example.com/episodes/ep1-cover.jpg"

# For serial podcasts: season and episode numbers
ep.season = 1
ep.episode_number = 1

# Episode type: full, trailer, or bonus
from podgen import EPISODE_TYPE_FULL, EPISODE_TYPE_TRAILER, EPISODE_TYPE_BONUS
ep.episode_type = EPISODE_TYPE_FULL

# Custom episode ordering on iTunes
ep.position = 1

# Block episode from iTunes (but still public in RSS)
ep.withhold_from_itunes = False

# Video episodes with closed captioning
ep.is_closed_captioned = False

print(p.rss_str())
```

### Response
#### Success Response (200)
Returns the podcast RSS feed with the episode included as a string.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>Developer Stories</title>
    <link>https://example.com</link>
    <description>Interviews with developers</description>
    <language>en</language>
    <itunes:explicit>no</itunes:explicit>
    <image>
      <url>https://example.com/podcast-cover.jpg</url>
      <title>Developer Stories</title>
      <link>https://example.com</link>
    </image>
    <item>
      <title>Episode 1: Getting Started with Python</title>
      <link>https://example.com/episodes/1</link>
      <description>In this episode, we discuss Python basics and best practices.</description>
      <pubDate>Mon, 15 Jan 2024 10:00:00 +0000</pubDate>
      <itunes:author>Jane Doe</itunes:author>
      <itunes:explicit>no</itunes:explicit>
      <itunes:episodeType>full</itunes:episodeType>
      <itunes:season>1</itunes:season>
      <itunes:episode>1</itunes:episode>
      <itunes:order>1</itunes:order>
      <content:encoded><![CDATA[<p>Join us for an in-depth discussion about Python programming.</p><p>Topics covered:</p><ul><li>Setting up your development environment</li><li>Python syntax fundamentals</li><li>Best practices for beginners</li></ul>]]></content:encoded>
    </item>
  </channel>
</rss>
```
```

--------------------------------

### Media Class - Attach Audio/Video Files to Episodes

Source: https://context7.com/tobinus/python-podgen/llms.txt

Shows how to use the Media class to attach audio or video files to episodes, including specifying the URL and file size.

```APIDOC
## Media Class - Attach Audio/Video Files to Episodes

### Description
The `Media` class represents the media file (audio, video, or document) attached to an episode. It handles file size, MIME type detection, and duration formatting. Supported formats include MP3, M4A, MP4, MOV, M4V, PDF, and EPUB.

### Method
Instantiation and attribute assignment

### Endpoint
N/A (Class usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Class instantiation)

### Request Example
```python
from podgen import Podcast, Episode, Media
import datetime
import pytz

p = Podcast(
    name="Audio Podcast",
    website="https://example.com",
    description="A podcast with media",
    explicit=False
)

ep = p.add_episode()
ep.title = "Episode with Media"

# Basic media attachment with URL and file size in bytes
ep.media = Media(
    url="https://example.com/episodes/ep1.mp3",
    size=45678901
)

print(p.rss_str())
```

### Response
#### Success Response (200)
Returns the podcast RSS feed with the media enclosure information included.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>Audio Podcast</title>
    <link>https://example.com</link>
    <description>A podcast with media</description>
    <language>en</language>
    <itunes:explicit>no</itunes:explicit>
    <image>
      <url>https://example.com/podcast-cover.jpg</url>
      <title>Audio Podcast</title>
      <link>https://example.com</link>
    </image>
    <item>
      <title>Episode with Media</title>
      <description></description>
      <enclosure url="https://example.com/episodes/ep1.mp3" length="45678901" type="audio/mpeg"/>
    </item>
  </channel>
</rss>
```
```

--------------------------------

### Generate Podcast RSS Feed with Python PodGen

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/index.rst

This snippet demonstrates how to use the PodGen library to create a podcast object, add episodes with media information and summaries, and finally generate the RSS feed as a string. It requires importing the Podcast, Episode, and Media classes from the podgen library.

```python
from podgen import Podcast, Episode, Media

# Create the Podcast
p = Podcast(
   name="Animals Alphabetically",
   description="Every Tuesday, biologist John Doe and wildlife "
               "photographer Foo Bar introduce you to a new animal.",
   website="http://example.org/animals-alphabetically",
   explicit=False,
)

# Add some episodes
p.episodes += [
   Episode(
     title="Aardvark",
     media=Media("http://example.org/files/aardvark.mp3", 11932295),
     summary="With an English name adapted directly from Afrikaans "
             'literally meaning "earth pig" -- this fascinating '
             "animal has both circular teeth and a knack for "
             "digging.",
   ),
   Episode(
      title="Alpaca",
      media=Media("http://example.org/files/alpaca.mp3", 15363464),
      summary="Thousands of years ago, alpacas were already "
              "domesticated and bred to produce the best fibers. "
              "Case in point: we have found clothing made from "
              "alpaca fiber that is 2000 years old. How is this "
              "possible, and what makes it different from llamas?",
   ),
]

# Generate the RSS feed
rss = p.rss_str()
```

--------------------------------

### Write RSS Feed to File

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/rss.rst

Demonstrates how to save the generated RSS feed directly to a file on disk. The minimize parameter can be used to produce a compact XML output.

```python
p.rss_file('rss.xml', minimize=True)
```

--------------------------------

### Control Episode Display Order in PodGen

Source: https://context7.com/tobinus/python-podgen/llms.txt

Demonstrates how to manually set episode positions or automatically apply order based on list sequence. This is useful for overriding default publication date sorting in podcast directories.

```python
from podgen import Podcast, Episode
import datetime
import pytz

p = Podcast(
    name="Ordered Podcast",
    website="https://example.com",
    description="Episodes with custom ordering",
    explicit=False
)

ep1 = p.add_episode()
ep1.title = "Introduction"
ep1.publication_date = datetime.datetime(2024, 1, 1, tzinfo=pytz.utc)

ep2 = p.add_episode()
ep2.title = "Chapter 1"
ep2.publication_date = datetime.datetime(2024, 1, 8, tzinfo=pytz.utc)

ep3 = p.add_episode()
ep3.title = "Chapter 2"
ep3.publication_date = datetime.datetime(2024, 1, 15, tzinfo=pytz.utc)

ep1.position = 1
ep2.position = 2
ep3.position = 3

p.apply_episode_order()
p.clear_episode_order()
print(p.rss_str())
```

--------------------------------

### Set iTunes Categories

Source: https://context7.com/tobinus/python-podgen/llms.txt

Shows how to use the Category class to assign valid iTunes categories and subcategories. The class handles case-insensitivity and proper formatting automatically.

```python
from podgen import Podcast, Category
p = Podcast(name="My Podcast", website="https://example.com", description="Podcast description", explicit=False)
p.category = Category("Technology")
p.category = Category("News", "Tech News")
p.category = Category("health & fitness", "mental health")
p.category = Category("Arts", "Fashion &amp; Beauty")
```

--------------------------------

### Podcast Type: Episodic vs. Serial

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Details the difference between episodic and serial podcasts and how to configure a serial podcast.

```APIDOC
## Podcast Types

### Description
Distinguishes between 'Episodic' (any order consumption) and 'Serial' (sequential consumption) podcasts. By default, podcasts are episodic. To set a podcast as serial, use the `is_serial` attribute.

### Method
```python
# For serial podcasts
p.is_serial = True
```

### Note
When `is_serial` is `True`, all full episodes must have an `episode_number`, and associating episodes with seasons is recommended.

### Parameters

#### Request Body
- **is_serial** (boolean) - Optional - Set to `True` if the podcast is serial. Defaults to `False`.
```

--------------------------------

### Populate Media Duration

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Methods to set the duration of a media file. Use fetch_duration for remote files or populate_duration_from for local files.

```python
# For remote files
my_episode.media.fetch_duration()

# For local files
filename = "/home/example/Music/podcast/s01e10.mp3"
my_episode.media.populate_duration_from(filename)
```

--------------------------------

### Configure Podcast Feed and Hub URLs

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/advanced/pubsubhubbub.rst

Sets the required feed_url and pubsubhubbub attributes on a Podcast object to enable protocol support.

```python
p.feed_url = "https://example.com/feeds/examplefeed.rss"
p.pubsubhubbub = "https://pubsubhubbub.example.com/"
```

--------------------------------

### PUT /episodes/{id}/media

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Attach media files to an existing podcast episode.

```APIDOC
## PUT /episodes/{id}/media

### Description
Attaches a media object to an episode, defining the URL, size, type, and duration of the audio file.

### Method
PUT

### Endpoint
/episodes/{id}/media

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the episode.

#### Request Body
- **url** (string) - Required - The URL where the media file is hosted.
- **size** (integer) - Optional - Size of the file in bytes.
- **type** (string) - Optional - MIME type of the media (e.g., audio/mpeg).
- **duration** (string) - Optional - Duration of the media in ISO 8601 format.

### Request Example
{
  "url": "http://example.com/podcast/s01e10.mp3",
  "size": 17475653,
  "type": "audio/mpeg",
  "duration": "01:02:36"
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation of media attachment.
```

--------------------------------

### Set less commonly used Podcast attributes in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Shows how to configure less frequently used attributes for a Podcast, including RSS Cloud settings, last updated timestamp, publication date, and feed refresh days.

```python
p.cloud = ("server.example.com", 80, "/rpc", "cloud.notify", "xml-rpc")

import datetime
import pytz
p.last_updated = datetime.datetime(2016, 5, 18, 0, 0, tzinfo=pytz.utc))
p.publication_date = datetime.datetime(2016, 5, 17, 15, 32,tzinfo=pytz.utc))

# Set of days on which podcatchers won't need to refresh the feed.
# Not implemented widely.
```

--------------------------------

### Set Podcast image URL in Python

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Illustrates how to assign an image URL to a Podcast object. While technically optional, a podcast image is crucial for discoverability and listener engagement.

```python
p.image = "https://example.com/static/example_podcast.png"
```

--------------------------------

### Optional Podcast Attributes

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Lists and explains various optional attributes that can be set for a Podcast object.

```APIDOC
## Optional Attributes

### Description
Configures additional attributes for the podcast, enhancing its metadata and feed information.

### Commonly Used Attributes

#### Method
```python
p.copyright = "2016 Example Radio"
p.language = "en-US"
p.authors = [Person("John Doe", "editor@example.org")]
p.feed_url = "https://example.com/feeds/podcast.rss"
p.category = Category("Music", "Music History")
p.owner = p.authors[0]
p.xslt = "https://example.com/feed/stylesheet.xsl"
```

### Parameters

#### Request Body
- **copyright** (string) - Optional - Copyright information for the podcast.
- **language** (string) - Optional - The primary language of the podcast (e.g., 'en-US').
- **authors** (list of Person objects) - Optional - A list of authors for the podcast.
- **feed_url** (string) - Optional - The URL of the podcast's RSS feed.
- **category** (Category object) - Optional - The category and subcategory of the podcast.
- **owner** (Person object) - Optional - The owner of the podcast, typically an author.
- **xslt** (string) - Optional - URL of an XSLT stylesheet for the feed.

### Less Commonly Used Attributes

#### Method
```python
# RSS Cloud configuration
p.cloud = ("server.example.com", 80, "/rpc", "cloud.notify", "xml-rpc")

import datetime
import pytz

# Last updated timestamp
p.last_updated = datetime.datetime(2016, 5, 18, 0, 0, tzinfo=pytz.utc)

# Publication date
p.publication_date = datetime.datetime(2016, 5, 17, 15, 32, tzinfo=pytz.utc)

# Days to skip refreshing
# p.skip_days = [...] # Not widely implemented
```

### Parameters

#### Request Body
- **cloud** (tuple) - Optional - RSS Cloud configuration for notifications.
- **last_updated** (datetime) - Optional - The date and time the feed was last refreshed. Defaults to the current time.
- **publication_date** (datetime) - Optional - The date and time the feed content was last published. Defaults to the most recent episode's date.
- **skip_days** (list of strings) - Optional - Days on which podcatchers should not refresh the feed (limited support).
```

--------------------------------

### Manage Podcast Authors and Contacts

Source: https://context7.com/tobinus/python-podgen/llms.txt

Explains the Person class for defining podcast owners, authors, and contributors. It highlights requirements for name and email fields and how to assign them to podcast or episode objects.

```python
from podgen import Podcast, Person
p = Podcast(name="My Podcast", website="https://example.com", description="A great podcast", explicit=False)
author = Person("John Doe", "john@example.com")
host = Person("Jane Smith")
contact = Person(email="contact@example.com")
p.authors = [author, host]
p.authors.append(Person("Guest Speaker"))
p.owner = Person("Admin User", "admin@example.com")
p.web_master = Person("Tech Support", "tech@example.com")
ep = p.add_episode()
ep.authors = [Person("Special Guest", "guest@example.com")]
```

--------------------------------

### Setting Episode Authors

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Explains how to set authors for a podcast episode, overriding the podcast-level authors if necessary.

```APIDOC
## Setting Episode Authors

### Description
Set the authors for a specific podcast episode. This can override the authors defined at the podcast level.

### Method
Attribute Assignment

### Endpoint
N/A (Object attribute assignment)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from podgen import Person

# Assuming my_episode is an instance of podgen.Episode
# Single author
my_episode.authors = [Person("Joe Bob")]

# Multiple authors
my_episode.authors = [Person("Joe Bob"), Person("Alice Bob")]
```

### Response
#### Success Response (200)
N/A (Attribute assignment)

#### Response Example
N/A
```

--------------------------------

### Configure iTunes Specific Feed Directives (Python)

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/podcasts.rst

Sets directives for iTunes, such as informing it about a new feed URL, indicating that the feed will no longer be updated, or requesting that the feed not be displayed on iTunes. Use these attributes with caution as they affect feed visibility and discoverability.

```Python
# Tell iTunes that this feed has moved somewhere else.
p.new_feed_url = "https://podcast.example.com/example"

# Tell iTunes that this feed will never be updated again.
p.complete = True

# Tell iTunes that you'd rather not have this feed appear on iTunes.
p.withhold_from_itunes = True
```

--------------------------------

### Configure iTunes Episode Attributes

Source: https://github.com/tobinus/python-podgen/blob/develop/doc/usage_guide/episodes.rst

Sets various iTunes-specific episode attributes such as image, explicit content flags, closed captioning, and store position.

```python
my_episode.image = "http://example.com/static/best-example.png"
my_episode.explicit = False
my_episode.is_closed_captioned = False
my_episode.position = 1
my_episode.withhold_from_itunes = True
```