Podcasts
--------

In PodGen, the term *podcast* refers to the show which listeners can subscribe to,
which consists of individual *episodes*. Therefore, the Podcast class will be the
first thing you start with.

Creating a new instance
~~~~~~~~~~~~~~~~~~~~~~~

You can start with a blank podcast by invoking the Podcast constructor with no
arguments, like this::

    from podgen import Podcast
    p = Podcast()

Mandatory attributes
~~~~~~~~~~~~~~~~~~~~

There are four attributes which must be set before you can generate your podcast.
They are mandatory because Apple's podcast directory will not accept podcasts without
this information. If you try to generate the podcast without setting all of the
mandatory attributes, you will get an error.

The mandatory attributes are::

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

They're mostly self explanatory, but you can read more about them if you'd like:

* :attr:`~podgen.Podcast.name`
* :attr:`~podgen.Podcast.description`
* :attr:`~podgen.Podcast.website`
* :attr:`~podgen.Podcast.explicit`

Image
~~~~~

A podcast's image is worth special attention::

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

.. autoattribute:: podgen.Podcast.image
   :noindex:

Even though the image *technically* is optional, you won't reach people without it.

Optional attributes
~~~~~~~~~~~~~~~~~~~

There are plenty of other attributes that can be used with
:class:`podgen.Podcast <podgen.Podcast>`:


Commonly used
^^^^^^^^^^^^^

::

    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"  # URL of this feed
    p.category = Category("Music", "Music History")
    p.owner = p.authors[0]
    p.xslt = "https://example.com/feed/stylesheet.xsl"  # URL of XSLT stylesheet

Read more:

* :attr:`~podgen.Podcast.copyright`
* :attr:`~podgen.Podcast.language`
* :attr:`~podgen.Podcast.authors`
* :attr:`~podgen.Podcast.feed_url`
* :attr:`~podgen.Podcast.category`
* :attr:`~podgen.Podcast.owner`
* :attr:`~podgen.Podcast.xslt`


Less commonly used
^^^^^^^^^^^^^^^^^^

Some of those are obscure while some of them are often times not needed. Others
again have very reasonable defaults.

::

    # RSS Cloud enables podcatchers to subscribe to notifications when there's
    # a new episode ready, however it's not used much.
    p.cloud = ("server.example.com", 80, "/rpc", "cloud.notify", "xml-rpc")

    import datetime
    # pytz is a dependency of this library, and makes it easy to deal with
    # timezones. Generally, all dates must be timezone aware.
    import pytz
    # last_updated is datetime when the feed was last refreshed. If you don't
    # set it, the current date and time will be used instead when the feed is
    # generated, which is generally what you want. Nevertheless, you can
    # set your own date:
    p.last_updated = datetime.datetime(2016, 5, 18, 0, 0, tzinfo=pytz.utc))

    # publication_date is when the contents of this feed last were published.
    # If you don't set it, the date of the most recent Episode is used. Again,
    # this is generally what you want, but you can override it:
    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.
    p.skip_days = {"Friday", "Saturday", "Sunday"}

    # Set of hours on which podcatchers won't need to refresh the feed.
    # Not implemented widely.
    p.skip_hours = set(range(8))
    p.skip_hours |= set(range(16, 24))

    # Person to contact regarding technical aspects of the feed.
    p.web_master = Person(None, "helpdesk@dallas.example.com")

    # Identify the software which generates the feed (defaults to python-podgen)
    p.set_generator("ExamplePodcastProgram", (1,0,0))
    # (you can also set the generator string directly)
    p.generator = "ExamplePodcastProgram v1.0.0 (with help from python-feedgen)"

    # !!! Be very careful about using the following attributes !!!

    # 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

Read more:

* :attr:`~podgen.Podcast.cloud`
* :attr:`~podgen.Podcast.last_updated`
* :attr:`~podgen.Podcast.publication_date`
* :attr:`~podgen.Podcast.skip_days`
* :attr:`~podgen.Podcast.skip_hours`
* :attr:`~podgen.Podcast.web_master`
* :meth:`~podgen.Podcast.set_generator`
* :attr:`~podgen.Podcast.new_feed_url`
* :attr:`~podgen.Podcast.complete`
* :attr:`~podgen.Podcast.withhold_from_itunes`

Shortcut for filling in data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Instead of creating a new :class:`.Podcast` object in one statement, and
populating it with data one statement at a time afterwards, you can create a
new :class:`.Podcast` object and fill it with data in one statement. Simply
use the attribute name as keyword arguments to the constructor::

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

Using this technique, you can define the Podcast as part of a list
comprehension, dictionaries and so on.
Take a look at the :doc:`API Documentation for Podcast </api.podcast>` for a
practical example.