259 lines
22 KiB
HTML
259 lines
22 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
|
||
|
||
<title>Feedgenerator — python-feedgen 1.0.0 documentation</title>
|
||
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/lernfunk.css" />
|
||
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/sphinx_highlight.js"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="API Documentation" href="api.html" />
|
||
</head><body>
|
||
<div class="header" role="banner"><h1 class="heading"><a href="#">
|
||
<span>python-feedgen 1.0.0 documentation</span></a></h1>
|
||
<h2 class="heading"><span>Feedgenerator</span></h2>
|
||
</div>
|
||
<div class="topnav" role="navigation" aria-label="top navigation">
|
||
|
||
<p>
|
||
<a class="uplink" href="#">Contents</a>
|
||
  ::  
|
||
<a href="api.html">API Documentation</a>  »
|
||
</p>
|
||
|
||
</div>
|
||
<div class="content" role="main">
|
||
|
||
|
||
<nav class="contents" id="table-of-contents" role="doc-toc">
|
||
<p class="topic-title">Table of Contents</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#feedgenerator" id="id1">Feedgenerator</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#installation" id="id2">Installation</a></p></li>
|
||
<li><p><a class="reference internal" href="#create-a-feed" id="id3">Create a Feed</a></p></li>
|
||
<li><p><a class="reference internal" href="#generate-the-feed" id="id4">Generate the Feed</a></p></li>
|
||
<li><p><a class="reference internal" href="#add-feed-entries" id="id5">Add Feed Entries</a></p></li>
|
||
<li><p><a class="reference internal" href="#extensions" id="id6">Extensions</a></p></li>
|
||
<li><p><a class="reference internal" href="#testing-the-generator" id="id7">Testing the Generator</a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#module-documentation" id="id8">Module documentation</a></p></li>
|
||
<li><p><a class="reference internal" href="#indices-and-tables" id="id9">Indices and tables</a></p></li>
|
||
</ul>
|
||
</nav>
|
||
<section id="feedgenerator">
|
||
<h1><a class="toc-backref" href="#id1" role="doc-backlink">Feedgenerator</a><a class="headerlink" href="#feedgenerator" title="Permalink to this heading">¶</a></h1>
|
||
<p>This module can be used to generate web feeds in both ATOM and RSS format. It
|
||
has support for extensions. Included is for example an extension to produce
|
||
Podcasts.</p>
|
||
<p>It is licensed under the terms of both, the FreeBSD license and the LGPLv3+.
|
||
Choose the one which is more convenient for you. For more details have a look
|
||
at license.bsd and license.lgpl.</p>
|
||
<p>More details about the project:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://github.com/lkiesow/python-feedgen">Repository</a></p></li>
|
||
<li><p><a class="reference external" href="https://lkiesow.github.io/python-feedgen/">Documentation</a></p></li>
|
||
<li><p><a class="reference external" href="https://pypi.python.org/pypi/feedgen/">Python Package Index</a></p></li>
|
||
</ul>
|
||
<section id="installation">
|
||
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Installation</a><a class="headerlink" href="#installation" title="Permalink to this heading">¶</a></h2>
|
||
<p><strong>Prebuild packages</strong></p>
|
||
<p>If your distribution includes this project as package, like Fedora Linux does,
|
||
you can simply use your package manager to install the package. For example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dnf install python3-feedgen
|
||
</pre></div>
|
||
</div>
|
||
<p><strong>Using pip</strong></p>
|
||
<p>You can also use pip to install the feedgen module. Simply run:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install feedgen
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="create-a-feed">
|
||
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Create a Feed</a><a class="headerlink" href="#create-a-feed" title="Permalink to this heading">¶</a></h2>
|
||
<p>To create a feed simply instantiate the FeedGenerator class and insert some
|
||
data:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">feedgen.feed</span> <span class="kn">import</span> <span class="n">FeedGenerator</span>
|
||
<span class="n">fg</span> <span class="o">=</span> <span class="n">FeedGenerator</span><span class="p">()</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">id</span><span class="p">(</span><span class="s1">'http://lernfunk.de/media/654321'</span><span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">title</span><span class="p">(</span><span class="s1">'Some Testfeed'</span><span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">author</span><span class="p">(</span> <span class="p">{</span><span class="s1">'name'</span><span class="p">:</span><span class="s1">'John Doe'</span><span class="p">,</span><span class="s1">'email'</span><span class="p">:</span><span class="s1">'john@example.de'</span><span class="p">}</span> <span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">link</span><span class="p">(</span> <span class="n">href</span><span class="o">=</span><span class="s1">'http://example.com'</span><span class="p">,</span> <span class="n">rel</span><span class="o">=</span><span class="s1">'alternate'</span> <span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">logo</span><span class="p">(</span><span class="s1">'http://ex.com/logo.jpg'</span><span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">subtitle</span><span class="p">(</span><span class="s1">'This is a cool feed!'</span><span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">link</span><span class="p">(</span> <span class="n">href</span><span class="o">=</span><span class="s1">'http://larskiesow.de/test.atom'</span><span class="p">,</span> <span class="n">rel</span><span class="o">=</span><span class="s1">'self'</span> <span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">language</span><span class="p">(</span><span class="s1">'en'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that for the methods which set fields that can occur more than once in a
|
||
feed you can use all of the following ways to provide data:</p>
|
||
<ul class="simple">
|
||
<li><p>Provide the data for that element as keyword arguments</p></li>
|
||
<li><p>Provide the data for that element as dictionary</p></li>
|
||
<li><p>Provide a list of dictionaries with the data for several elements</p></li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">fg</span><span class="o">.</span><span class="n">contributor</span><span class="p">(</span> <span class="n">name</span><span class="o">=</span><span class="s1">'John Doe'</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="s1">'jdoe@example.com'</span> <span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">contributor</span><span class="p">({</span><span class="s1">'name'</span><span class="p">:</span><span class="s1">'John Doe'</span><span class="p">,</span> <span class="s1">'email'</span><span class="p">:</span><span class="s1">'jdoe@example.com'</span><span class="p">})</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">contributor</span><span class="p">([{</span><span class="s1">'name'</span><span class="p">:</span><span class="s1">'John Doe'</span><span class="p">,</span> <span class="s1">'email'</span><span class="p">:</span><span class="s1">'jdoe@example.com'</span><span class="p">},</span> <span class="o">...</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="generate-the-feed">
|
||
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Generate the Feed</a><a class="headerlink" href="#generate-the-feed" title="Permalink to this heading">¶</a></h2>
|
||
<p>After that you can generate both RSS or ATOM by calling the respective method:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">atomfeed</span> <span class="o">=</span> <span class="n">fg</span><span class="o">.</span><span class="n">atom_str</span><span class="p">(</span><span class="n">pretty</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="c1"># Get the ATOM feed as string</span>
|
||
<span class="n">rssfeed</span> <span class="o">=</span> <span class="n">fg</span><span class="o">.</span><span class="n">rss_str</span><span class="p">(</span><span class="n">pretty</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="c1"># Get the RSS feed as string</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">atom_file</span><span class="p">(</span><span class="s1">'atom.xml'</span><span class="p">)</span> <span class="c1"># Write the ATOM feed to a file</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">rss_file</span><span class="p">(</span><span class="s1">'rss.xml'</span><span class="p">)</span> <span class="c1"># Write the RSS feed to a file</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="add-feed-entries">
|
||
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Add Feed Entries</a><a class="headerlink" href="#add-feed-entries" title="Permalink to this heading">¶</a></h2>
|
||
<p>To add entries (items) to a feed you need to create new FeedEntry objects and
|
||
append them to the list of entries in the FeedGenerator. The most convenient
|
||
way to go is to use the FeedGenerator itself for the instantiation of the
|
||
FeedEntry object:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">fe</span> <span class="o">=</span> <span class="n">fg</span><span class="o">.</span><span class="n">add_entry</span><span class="p">()</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">id</span><span class="p">(</span><span class="s1">'http://lernfunk.de/media/654321/1'</span><span class="p">)</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">title</span><span class="p">(</span><span class="s1">'The First Episode'</span><span class="p">)</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">link</span><span class="p">(</span><span class="n">href</span><span class="o">=</span><span class="s2">"http://lernfunk.de/feed"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The FeedGenerator’s method <cite>add_entry(…)</cite> will generate a new FeedEntry
|
||
object, automatically append it to the feeds internal list of entries and
|
||
return it, so that additional data can be added.</p>
|
||
</section>
|
||
<section id="extensions">
|
||
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Extensions</a><a class="headerlink" href="#extensions" title="Permalink to this heading">¶</a></h2>
|
||
<p>The FeedGenerator supports extensions to include additional data into the XML
|
||
structure of the feeds. Extensions can be loaded like this:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">fg</span><span class="o">.</span><span class="n">load_extension</span><span class="p">(</span><span class="s1">'someext'</span><span class="p">,</span> <span class="n">atom</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">rss</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This example would try to load the extension “someext” from the file
|
||
<cite>ext/someext.py</cite>. It is required that <cite>someext.py</cite> contains a class named
|
||
“SomextExtension” which is required to have at least the two methods
|
||
<cite>extend_rss(…)</cite> and <cite>extend_atom(…)</cite>. Although not required, it is strongly
|
||
suggested to use <cite>BaseExtension</cite> from <cite>ext/base.py</cite> as superclass.</p>
|
||
<p><cite>load_extension(‘someext’, …)</cite> will also try to load a class named
|
||
“SomextEntryExtension” for every entry of the feed. This class can be located
|
||
either in the same file as SomextExtension or in <cite>ext/someext_entry.py</cite> which
|
||
is suggested especially for large extensions.</p>
|
||
<p>The parameters <cite>atom</cite> and <cite>rss</cite> control if the extension is used for ATOM and
|
||
RSS feeds respectively. The default value for both parameters is <cite>True</cite>,
|
||
meaning the extension is used for both kinds of feeds.</p>
|
||
<p><strong>Example: Producing a Podcast</strong></p>
|
||
<p>One extension already provided is the podcast extension. A podcast is an RSS
|
||
feed with some additional elements for ITunes.</p>
|
||
<p>To produce a podcast simply load the <cite>podcast</cite> extension:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">feedgen.feed</span> <span class="kn">import</span> <span class="n">FeedGenerator</span>
|
||
<span class="n">fg</span> <span class="o">=</span> <span class="n">FeedGenerator</span><span class="p">()</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">load_extension</span><span class="p">(</span><span class="s1">'podcast'</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">podcast</span><span class="o">.</span><span class="n">itunes_category</span><span class="p">(</span><span class="s1">'Technology'</span><span class="p">,</span> <span class="s1">'Podcasting'</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">fe</span> <span class="o">=</span> <span class="n">fg</span><span class="o">.</span><span class="n">add_entry</span><span class="p">()</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">id</span><span class="p">(</span><span class="s1">'http://lernfunk.de/media/654321/1/file.mp3'</span><span class="p">)</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">title</span><span class="p">(</span><span class="s1">'The First Episode'</span><span class="p">)</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">description</span><span class="p">(</span><span class="s1">'Enjoy our first episode.'</span><span class="p">)</span>
|
||
<span class="n">fe</span><span class="o">.</span><span class="n">enclosure</span><span class="p">(</span><span class="s1">'http://lernfunk.de/media/654321/1/file.mp3'</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">'audio/mpeg'</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">rss_str</span><span class="p">(</span><span class="n">pretty</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="n">fg</span><span class="o">.</span><span class="n">rss_file</span><span class="p">(</span><span class="s1">'podcast.xml'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If the FeedGenerator class is used to load an extension, it is automatically
|
||
loaded for every feed entry as well. You can, however, load an extension for a
|
||
specific FeedEntry only by calling <cite>load_extension(…)</cite> on that entry.</p>
|
||
<p>Even if extensions are loaded, they can be temporarily disabled during the feed
|
||
generation by calling the generating method with the keyword argument
|
||
<cite>extensions</cite> set to <cite>False</cite>.</p>
|
||
<p><strong>Custom Extensions</strong></p>
|
||
<p>If you want to load custom extensions which are not part of the feedgen
|
||
package, you can use the method <cite>register_extension</cite> instead. You can directly
|
||
pass the classes for the feed and the entry extension to this method meaning
|
||
that you can define them everywhere.</p>
|
||
</section>
|
||
<section id="testing-the-generator">
|
||
<h2><a class="toc-backref" href="#id7" role="doc-backlink">Testing the Generator</a><a class="headerlink" href="#testing-the-generator" title="Permalink to this heading">¶</a></h2>
|
||
<p>You can test the module by simply executing:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python -m feedgen
|
||
</pre></div>
|
||
</div>
|
||
<p>If you want to have a look at the code for this test to have a working code
|
||
example for a whole feed generation process, you can find it in the
|
||
<a class="reference external" href="https://github.com/lkiesow/python-feedgen/blob/master/feedgen/__main__.py">__main__.py</a>.</p>
|
||
<hr /></section>
|
||
</section>
|
||
<section id="module-documentation">
|
||
<h1><a class="toc-backref" href="#id8" role="doc-backlink">Module documentation</a><a class="headerlink" href="#module-documentation" title="Permalink to this heading">¶</a></h1>
|
||
<div class="toctree-wrapper compound">
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="api.html">API Documentation</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.html#feedgen">feedgen</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.feed.html">feedgen.feed</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.feed.html#feedgen.feed.FeedGenerator"><code class="docutils literal notranslate"><span class="pre">FeedGenerator</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.entry.html">feedgen.entry</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.entry.html#feedgen.entry.FeedEntry"><code class="docutils literal notranslate"><span class="pre">FeedEntry</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.util.html">feedgen.util</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.util.html#feedgen.util.ensure_format"><code class="docutils literal notranslate"><span class="pre">ensure_format()</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api.util.html#feedgen.util.formatRFC2822"><code class="docutils literal notranslate"><span class="pre">formatRFC2822()</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.base.html">feedgen.ext.base</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.base.html#feedgen.ext.base.BaseEntryExtension"><code class="docutils literal notranslate"><span class="pre">BaseEntryExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.base.html#feedgen.ext.base.BaseExtension"><code class="docutils literal notranslate"><span class="pre">BaseExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.dc.html">feedgen.ext.dc</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.dc.html#feedgen.ext.dc.DcBaseExtension"><code class="docutils literal notranslate"><span class="pre">DcBaseExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.dc.html#feedgen.ext.dc.DcEntryExtension"><code class="docutils literal notranslate"><span class="pre">DcEntryExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.dc.html#feedgen.ext.dc.DcExtension"><code class="docutils literal notranslate"><span class="pre">DcExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.podcast.html">feedgen.ext.podcast</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.podcast.html#feedgen.ext.podcast.PodcastExtension"><code class="docutils literal notranslate"><span class="pre">PodcastExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.podcast_entry.html">feedgen.ext.podcast_entry</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.podcast_entry.html#feedgen.ext.podcast_entry.PodcastEntryExtension"><code class="docutils literal notranslate"><span class="pre">PodcastEntryExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.torrent.html">feedgen.ext.torrent</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.torrent.html#feedgen.ext.torrent.TorrentEntryExtension"><code class="docutils literal notranslate"><span class="pre">TorrentEntryExtension</span></code></a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="ext/api.ext.torrent.html#feedgen.ext.torrent.TorrentExtension"><code class="docutils literal notranslate"><span class="pre">TorrentExtension</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</section>
|
||
<section id="indices-and-tables">
|
||
<h1><a class="toc-backref" href="#id9" role="doc-backlink">Indices and tables</a><a class="headerlink" href="#indices-and-tables" title="Permalink to this heading">¶</a></h1>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
|
||
<li><p><a class="reference internal" href="py-modindex.html"><span class="std std-ref">Module Index</span></a></p></li>
|
||
<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
|
||
</ul>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
|
||
|
||
<p>
|
||
<a class="uplink" href="#">Contents</a>
|
||
  ::  
|
||
<a href="api.html">API Documentation</a>  »
|
||
</p>
|
||
|
||
</div>
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2013-2016, Lars Kiesow.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
|
||
</div>
|
||
</body>
|
||
</html> |