-
Notifications
You must be signed in to change notification settings - Fork 125
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Just updating a few minor bits of the documentation.
- Loading branch information
Showing
2 changed files
with
65 additions
and
53 deletions.
There are no files selected for viewing
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -21,9 +21,9 @@ at license.bsd and license.lgpl. | |
|
||
More details about the project: | ||
|
||
- Repository: https://github.com/lkiesow/python-feedgen | ||
- Documentation: https://lkiesow.github.io/python-feedgen/ | ||
- Python Package Index: https://pypi.python.org/pypi/feedgen/ | ||
- `Repository <https://github.com/lkiesow/python-feedgen>`_ | ||
- `Documentation <https://lkiesow.github.io/python-feedgen/>`_ | ||
- `Python Package Index <https://pypi.python.org/pypi/feedgen/>`_ | ||
|
||
|
||
------------ | ||
|
@@ -50,18 +50,20 @@ Create a Feed | |
------------- | ||
|
||
To create a feed simply instantiate the FeedGenerator class and insert some | ||
data:: | ||
|
||
>>> from feedgen.feed import FeedGenerator | ||
>>> fg = FeedGenerator() | ||
>>> fg.id('http://lernfunk.de/media/654321') | ||
>>> fg.title('Some Testfeed') | ||
>>> fg.author( {'name':'John Doe','email':'[email protected]'} ) | ||
>>> fg.link( href='http://example.com', rel='alternate' ) | ||
>>> fg.logo('http://ex.com/logo.jpg') | ||
>>> fg.subtitle('This is a cool feed!') | ||
>>> fg.link( href='http://larskiesow.de/test.atom', rel='self' ) | ||
>>> fg.language('en') | ||
data: | ||
|
||
.. code-block:: python | ||
from feedgen.feed import FeedGenerator | ||
fg = FeedGenerator() | ||
fg.id('http://lernfunk.de/media/654321') | ||
fg.title('Some Testfeed') | ||
fg.author( {'name':'John Doe','email':'[email protected]'} ) | ||
fg.link( href='http://example.com', rel='alternate' ) | ||
fg.logo('http://ex.com/logo.jpg') | ||
fg.subtitle('This is a cool feed!') | ||
fg.link( href='http://larskiesow.de/test.atom', rel='self' ) | ||
fg.language('en') | ||
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: | ||
|
@@ -70,22 +72,26 @@ feed you can use all of the following ways to provide data: | |
- Provide the data for that element as dictionary | ||
- Provide a list of dictionaries with the data for several elements | ||
|
||
Example:: | ||
Example: | ||
|
||
>>> fg.contributor( name='John Doe', email='[email protected]' ) | ||
>>> fg.contributor({'name':'John Doe', 'email':'[email protected]'}) | ||
>>> fg.contributor([{'name':'John Doe', 'email':'[email protected]'}, ...]) | ||
.. code-block:: python | ||
fg.contributor( name='John Doe', email='[email protected]' ) | ||
fg.contributor({'name':'John Doe', 'email':'[email protected]'}) | ||
fg.contributor([{'name':'John Doe', 'email':'[email protected]'}, ...]) | ||
----------------- | ||
Generate the Feed | ||
----------------- | ||
|
||
After that you can generate both RSS or ATOM by calling the respective method:: | ||
After that you can generate both RSS or ATOM by calling the respective method: | ||
|
||
.. code-block:: python | ||
>>> atomfeed = fg.atom_str(pretty=True) # Get the ATOM feed as string | ||
>>> rssfeed = fg.rss_str(pretty=True) # Get the RSS feed as string | ||
>>> fg.atom_file('atom.xml') # Write the ATOM feed to a file | ||
>>> fg.rss_file('rss.xml') # Write the RSS feed to a file | ||
atomfeed = fg.atom_str(pretty=True) # Get the ATOM feed as string | ||
rssfeed = fg.rss_str(pretty=True) # Get the RSS feed as string | ||
fg.atom_file('atom.xml') # Write the ATOM feed to a file | ||
fg.rss_file('rss.xml') # Write the RSS feed to a file | ||
---------------- | ||
|
@@ -95,62 +101,68 @@ Add Feed Entries | |
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:: | ||
FeedEntry object: | ||
|
||
>>> fe = fg.add_entry() | ||
>>> fe.id('http://lernfunk.de/media/654321/1') | ||
>>> fe.title('The First Episode') | ||
>>> fe.link(href="http://lernfunk.de/feed") | ||
.. code-block:: python | ||
The FeedGenerators method `add_entry(...)` without argument provides will | ||
automatically generate a new FeedEntry object, append it to the feeds internal | ||
list of entries and return it, so that additional data can be added. | ||
fe = fg.add_entry() | ||
fe.id('http://lernfunk.de/media/654321/1') | ||
fe.title('The First Episode') | ||
fe.link(href="http://lernfunk.de/feed") | ||
The FeedGenerator's method `add_entry(...)` 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. | ||
|
||
---------- | ||
Extensions | ||
---------- | ||
|
||
The FeedGenerator supports extension to include additional data into the XML | ||
structure of the feeds. Extensions can be loaded like this:: | ||
The FeedGenerator supports extensions to include additional data into the XML | ||
structure of the feeds. Extensions can be loaded like this: | ||
|
||
.. code-block:: python | ||
>>> fg.load_extension('someext', atom=True, rss=True) | ||
fg.load_extension('someext', atom=True, rss=True) | ||
This will try to load the extension “someext” from the file `ext/someext.py`. | ||
It is required that `someext.py` contains a class named “SomextExtension” which | ||
is required to have at least the two methods `extend_rss(...)` and | ||
`extend_atom(...)`. Although not required, it is strongly suggested to use | ||
`BaseExtension` from `ext/base.py` as superclass. | ||
This example would try to load the extension “someext” from the file | ||
`ext/someext.py`. It is required that `someext.py` contains a class named | ||
“SomextExtension” which is required to have at least the two methods | ||
`extend_rss(...)` and `extend_atom(...)`. Although not required, it is strongly | ||
suggested to use `BaseExtension` from `ext/base.py` as superclass. | ||
|
||
`load_extension('someext', ...)` 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 `ext/someext_entry.py` which | ||
is suggested especially for large extensions. | ||
|
||
The parameters `atom` and `rss` control if the extension is used for ATOM and | ||
RSS feeds, respectively. The default value for both parameters is `true` | ||
RSS feeds respectively. The default value for both parameters is `True`, | ||
meaning the extension is used for both kinds of feeds. | ||
|
||
**Example: Producing a Podcast** | ||
|
||
One extension already provided is the podcast extension. A podcast is an RSS | ||
feed with some additional elements for ITunes. | ||
|
||
To produce a podcast simply load the `podcast` extension:: | ||
To produce a podcast simply load the `podcast` extension: | ||
|
||
.. code-block:: python | ||
>>> from feedgen.feed import FeedGenerator | ||
>>> fg = FeedGenerator() | ||
>>> fg.load_extension('podcast') | ||
from feedgen.feed import FeedGenerator | ||
fg = FeedGenerator() | ||
fg.load_extension('podcast') | ||
... | ||
>>> fg.podcast.itunes_category('Technology', 'Podcasting') | ||
fg.podcast.itunes_category('Technology', 'Podcasting') | ||
... | ||
>>> fe = fg.add_entry() | ||
>>> fe.id('http://lernfunk.de/media/654321/1/file.mp3') | ||
>>> fe.title('The First Episode') | ||
>>> fe.description('Enjoy our first episode.') | ||
>>> fe.enclosure('http://lernfunk.de/media/654321/1/file.mp3', 0, 'audio/mpeg') | ||
fe = fg.add_entry() | ||
fe.id('http://lernfunk.de/media/654321/1/file.mp3') | ||
fe.title('The First Episode') | ||
fe.description('Enjoy our first episode.') | ||
fe.enclosure('http://lernfunk.de/media/654321/1/file.mp3', 0, 'audio/mpeg') | ||
... | ||
>>> fg.rss_str(pretty=True) | ||
>>> fg.rss_file('podcast.xml') | ||
fg.rss_str(pretty=True) | ||
fg.rss_file('podcast.xml') | ||
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 | ||
|