0
# feedgen
1

2
A comprehensive Python library for generating web feeds in both ATOM and RSS formats. feedgen provides a clean, object-oriented API for creating standards-compliant feeds with full extensibility support through a plugin system, making it suitable for web applications, content management systems, blog platforms, and any application requiring standardized feed output.
3

4
## Package Information
5

6
- **Package Name**: feedgen
7
- **Language**: Python  
8
- **Installation**: `pip install feedgen`
9
- **Dependencies**: `lxml`, `python-dateutil`
10

11
## Core Imports
12

13
```python
14
from feedgen.feed import FeedGenerator
15
from feedgen.entry import FeedEntry
16
```
17

18
## Basic Usage
19

20
```python
21
from feedgen.feed import FeedGenerator
22

23
# Create a feed generator
24
fg = FeedGenerator()
25

26
# Set required feed metadata
27
fg.id('http://example.com/feed')
28
fg.title('My Example Feed')
29
fg.author({'name': 'John Doe', 'email': 'john@example.com'})
30
fg.link(href='http://example.com', rel='alternate')
31
fg.description('This is an example feed')
32
fg.language('en')
33

34
# Add an entry
35
fe = fg.add_entry()
36
fe.id('http://example.com/entry/1')
37
fe.title('First Entry')
38
fe.description('This is the first entry in the feed')
39
fe.link(href='http://example.com/entry/1')
40

41
# Generate feeds
42
atom_feed = fg.atom_str(pretty=True)  # Get ATOM feed as string
43
rss_feed = fg.rss_str(pretty=True)    # Get RSS feed as string
44

45
# Write to files
46
fg.atom_file('feed.atom')
47
fg.rss_file('feed.rss')
48
```
49

50
## Architecture
51

52
feedgen uses an object-oriented design with two main classes:
53

54
- **FeedGenerator**: Manages feed-level metadata and configuration, generates ATOM/RSS output
55
- **FeedEntry**: Represents individual entries/items within a feed
56
- **Extension System**: Pluggable architecture for specialized feed formats (podcasts, GeoRSS, etc.)
57

58
The extension system allows loading specialized functionality for different feed types while maintaining compatibility with standard ATOM and RSS formats.
59

60
## Capabilities
61

62
### Feed Generation
63

64
Core functionality for creating and configuring web feeds, setting metadata, and generating ATOM/RSS output formats.
65

66
```python { .api }
67
class FeedGenerator:
68
    def __init__(self): ...
69
    def atom_str(self, pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True): ...
70
    def atom_file(self, filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True): ...
71
    def rss_str(self, pretty=False, extensions=True, encoding='UTF-8', xml_declaration=True): ...
72
    def rss_file(self, filename, extensions=True, pretty=False, encoding='UTF-8', xml_declaration=True): ...
73
```
74

75
[Feed Generation](./feed-generation.md)
76

77
### Feed Metadata Management
78

79
Methods for setting and retrieving feed-level metadata including titles, descriptions, authors, links, categories, and other feed properties.
80

81
```python { .api }
82
def title(self, title=None): ...
83
def id(self, id=None): ...
84
def author(self, author=None, replace=False, **kwargs): ...
85
def link(self, link=None, replace=False, **kwargs): ...
86
def description(self, description=None): ...
87
def subtitle(self, subtitle=None): ...
88
def language(self, language=None): ...
89
def cloud(self, domain=None, port=None, path=None, registerProcedure=None, protocol=None): ...
90
def generator(self, generator=None, version=None, uri=None): ...
91
```
92

93
[Feed Metadata](./feed-metadata.md)
94

95
### Entry Management
96

97
Functionality for creating, managing, and configuring individual feed entries with their metadata, content, and links.
98

99
```python { .api }
100
class FeedEntry:
101
    def title(self, title=None): ...
102
    def id(self, id=None): ...
103
    def content(self, content=None, src=None, type=None): ...
104
    def link(self, link=None, replace=False, **kwargs): ...
105
    def summary(self, summary=None, type=None): ...
106
    def published(self, published=None): ...
107
```
108

109
[Entry Management](./entry-management.md)
110

111
### Extensions System
112

113
Extensible plugin architecture supporting specialized feed formats including podcasts (iTunes), Dublin Core metadata, GeoRSS, media RSS, syndication, and BitTorrent feeds.
114

115
```python { .api }
116
def load_extension(self, name, atom=True, rss=True): ...
117
def register_extension(self, namespace, extension_class_feed=None, 
118
                      extension_class_entry=None, atom=True, rss=True): ...
119
```
120

121
Available built-in extensions: `podcast`, `dc`, `syndication`, `torrent`, `geo`, `media`
122

123
[Extensions](./extensions.md)
124

125
## Types
126

127
```python { .api }
128
# Author/Contributor structure
129
AuthorDict = {
130
    'name': str,       # Required: Author name
131
    'email': str,      # Optional: Email address  
132
    'uri': str         # Optional: Author URI/website
133
}
134

135
# Link structure
136
LinkDict = {
137
    'href': str,       # Required: Link URL
138
    'rel': str,        # Optional: Link relationship ('alternate', 'self', etc.)
139
    'type': str,       # Optional: MIME type
140
    'title': str,      # Optional: Link title
141
    'length': str      # Optional: Content length
142
}
143

144
# Category structure  
145
CategoryDict = {
146
    'term': str,       # Required: Category term
147
    'scheme': str,     # Optional: Category scheme/taxonomy URL
148
    'label': str       # Optional: Human-readable label
149
}
150

151
# Cloud structure (RSS only)
152
CloudDict = {
153
    'domain': str,              # Required: Domain where webservice is found
154
    'port': int,                # Optional: Port webservice listens to
155
    'path': str,                # Optional: Path of webservice
156
    'registerProcedure': str,   # Optional: Procedure to call
157
    'protocol': str             # Optional: 'HTTP-POST', 'XML-RPC', or 'SOAP 1.1'
158
}
159

160
# Generator structure
161
GeneratorDict = {
162
    'generator': str,   # Required: Software name
163
    'version': str,     # Optional: Software version (ATOM only)
164
    'uri': str          # Optional: Software URI (ATOM only)
165
}
166
```