PodGen Documentation Release 1.1.0 Lars Kiesow and Thorben Dahl Mar 06, 2020 Contents 1 Contents 3 1.1 Background................................................3 1.1.1 Philosophy...........................................3 1.1.2 Scope..............................................4 1.1.3 Why the fork?..........................................4 1.1.4 Roadmap............................................6 1.1.5 License.............................................6 1.2 Usage Guide...............................................6 1.2.1 Installation...........................................6 1.2.2 Podcasts.............................................7 1.2.3 Episodes............................................. 10 1.2.4 RSS............................................... 15 1.2.5 Full example.......................................... 15 1.3 Advanced Topics............................................. 16 1.3.1 Using PubSubHubbub..................................... 16 1.3.2 Adding new tags........................................ 19 1.4 Contributing............................................... 22 1.4.1 Setting up............................................ 22 1.4.2 Testing............................................. 22 1.4.3 Values.............................................. 23 1.4.4 The Workflow.......................................... 23 1.5 API Documentation........................................... 23 1.5.1 podgen.Podcast......................................... 24 1.5.2 podgen.Episode......................................... 33 1.5.3 podgen.Person......................................... 37 1.5.4 podgen.Media.......................................... 38 1.5.5 podgen.Category........................................ 42 1.5.6 podgen.warnings........................................ 43 1.5.7 podgen.util........................................... 44 2 External Resources 45 Index 47 i ii PodGen Documentation, Release 1.1.0 (https://travis-ci.org/tobinus/python-podgen) (http://podgen.readthedocs.io/en/latest/?badge=latest) Are you looking for a clean and simple library which helps you generate podcast RSS feeds from your Python code? Here is how you do that with PodGen: 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() You don’t need to read the RSS specification, write XML by hand or wrap your head around ambiguous, undocumented APIs. PodGen incorporates the industry’s best practices and lets you focus on collecting the necessary metadata and publishing the podcast. PodGen is compatible with Python 2.7 and 3.4+. Warning: As of March 6th 2020 (v1.1.0), PodGen does not support the additions and changes made by Apple to their podcast standards since 2016, with the exception of the 2019 categories. This includes the ability to mark episodes with episode and season number, and the ability to mark the podcast as “serial”. It is a goal to implement those changes in a new release. Please refer to the Roadmap. Contents 1 PodGen Documentation, Release 1.1.0 2 Contents CHAPTER 1 Contents 1.1 Background Learn about the “why” and “how” of the PodGen project itself. 1.1.1 Philosophy This project is heavily inspired by the “for humans” approach of the Requests (https://requests.readthedocs.io) library, which features an API that is designed to give the developer a great user experience. This is done by finding a suitable scope and abstraction level, and designing the API so it supports the developer’s vocabulary and their mental model of how the domain works. For example, instead of using the names of XML tags like “itunes:image”, a more relevant name, here simply “image”, is used. Another example is the duration of a podcast episode. In XML terms, this is put into an “itunes:duration” tag which exists outside of the “enclosure” tag, which holds the filename and file size. In PodGen, the filename, file size, file type and audio duration are all placed together in a Media instance, since they are all related to the media itself. The goal has been to “hide” the messy details of the XML and provide an API on top which uses words that you recognize and use daily when working with podcasts. To be specific, PodGen aims to follow the same PEP 20 (https://www.python.org/dev/peps/pep-0020/) idioms as Re- quests (https://requests.readthedocs.io/en/master/user/intro/#philosophy): 1. Beautiful is better than ugly. 2. Explicit is better than implicit. 3. Simple is better than complex. 4. Complex is better than complicated. 5. Readability counts. To enable this, the project focuses on one task alone: making it easy to generate a podcast. 3 PodGen Documentation, Release 1.1.0 1.1.2 Scope This library does NOT help you publish a podcast, or manage the metadata of your podcasts. It’s just a tool that accepts information about your podcast and outputs an RSS feed which you can then publish however you want. Both the process of getting information about your podcast, and publishing it needs to be done by you. Even then, it will save you from hammering your head over confusing and undocumented APIs and conflicting views on how different RSS elements should be used. It also saves you from reading the RSS specification, the RSS Best Practices and the documentation for iTunes’ Podcast Connect. Here is an example of how PodGen fits into your code: 1. A request comes to your webserver (using e.g. Flask (https://palletsprojects.com/p/flask/)) 2. A podcast router starts to handle the request. 3. The database is queried for information about the requested podcast. 4. The data retrieved from the database is “translated” into the language of PodGen, using its Podcast, Episode, People and Media classes. 5. The RSS document is generated by PodGen and saved to a variable. 6. The generated RSS document is made into a response and sent to the client. PodGen is geared towards developers who aren’t super familiar with RSS and XML. If you know ex- actly how you want the XML to look, then you’re better off using a template engine like Jinja2 (even if friends don’t let friends touch XML bare-handed) or an XML processor like the built-in Python El- ementTree API (https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree). If you just want an easy way to create and manage your podcasts, check out systems like Podcast Generator (http://www.podcastgenerator.net/). 1.1.3 Why the fork? This project is a fork of python-feedgen (https://github.com/lkiesow/python-feedgen) which cuts away everything that doesn’t serve the goal of making it easy and simple to generate podcasts from a Python program. Thus, this project includes only a subset of the features of python-feedgen (https://github.com/lkiesow/python-feedgen). And I don’t think anyone in their right mind would accept a pull request which removes 70% of the features ;-) Among other things, support for ATOM and Dublin Core is removed, and the remaining code is almost entirely rewritten. A more detailed reasoning follows. Read it if you’re interested, but feel free to skip to the Usage Guide. Inspiration The python-feedgen (https://github.com/lkiesow/python-feedgen) project is alright for creating general RSS and ATOM feeds, especially in situations where you’d like to serve the same content in those two formats. However, I wanted to create podcasts, and found myself struggling with getting the library to do what I wanted to do, and I frequently found myself looking at the source to understand what was going on. Perhaps the biggest problem is the awkwardness that stems from enabling RSS and ATOM feeds through the same API. In case you don’t know, ATOM is a competitor to RSS, and has many more capabilities than RSS. However, it is not used for podcasting. The result of mixing both ATOM and RSS include methods that will map an ATOM value to its closest sibling in RSS, some in logical ways (like the ATOM method rights setting the value of the RSS property copyright) and some differ in subtle ways (like using (ATOM) logo versus (RSS) image). Other methods are more complex (see link). They’re all confusing, though, since changing one property automatically changes another implicitly. They also cause bugs, since it is so difficult to wrap your head around how one interact with another. This is the inspiration for forking python-feedgen (https://github.com/lkiesow/python-feedgen) and rewrite the API, without mixing the different standards. 4 Chapter 1. Contents PodGen Documentation, Release 1.1.0 Futhermore, python-feedgen (https://github.com/lkiesow/python-feedgen) gives you a one-to-one mapping to the re- sulting XML elements. This means that you must learn the RSS and podcast standards, which include many legacy elements you don’t really need. For example, the original RSS spec includes support for an image, but that image is required to be less than 144 pixels wide (88 pixels being the default) and 400 pixels high (remember, this was year 2000). Itunes can’t have any of that (understandably so), so they added their own itunes:image tag, which has its own set of requirements (images can be no smaller than 1400x1400px!). I believe the API should help guide the users by hiding the legacy image tag, and you as a user shouldn’t need to know all this. You just need to know that the image must be larger than 1400x1400 pixels, not the history behind everything.