0
# Feed Metadata Management
1

2
Methods for setting and retrieving feed-level metadata including titles, descriptions, authors, links, categories and other feed properties for both ATOM and RSS formats.
3

4
## Capabilities
5

6
### Required Feed Metadata
7

8
Essential metadata required for valid ATOM and RSS feeds.
9

10
```python { .api }
11
def title(self, title=None):
12
    """
13
    Set or get feed title.
14
    
15
    Args:
16
        title (str, optional): Feed title
17
        
18
    Returns:
19
        str or None: Current title if no argument provided
20
    """
21

22
def id(self, id=None):
23
    """
24
    Set or get feed ID/URL.
25
    
26
    Args:
27
        id (str, optional): Unique feed identifier URL
28
        
29
    Returns:
30
        str or None: Current ID if no argument provided
31
    """
32

33
def description(self, description=None):
34
    """
35
    Set or get feed description (RSS) / subtitle (ATOM).
36
    
37
    Args:
38
        description (str, optional): Feed description
39
        
40
    Returns:
41
        str or None: Current description if no argument provided
42
    """
43

44
def subtitle(self, subtitle=None):
45
    """
46
    Set or get feed subtitle (ATOM) / description (RSS).
47
    
48
    Args:
49
        subtitle (str, optional): Feed subtitle
50
        
51
    Returns:
52
        str or None: Current subtitle if no argument provided
53
    """
54
```
55

56
### Author and Contributor Information
57

58
Manage feed authors and contributors with structured data.
59

60
```python { .api }
61
def author(self, author=None, replace=False, **kwargs):
62
    """
63
    Set or get feed author(s).
64
    
65
    Args:
66
        author (dict or list, optional): Author information
67
        replace (bool): Replace existing authors instead of appending
68
        **kwargs: Author fields as keyword arguments
69
        
70
    Returns:
71
        list: Current authors if no argument provided
72
    """
73

74
def contributor(self, contributor=None, replace=False, **kwargs):
75
    """
76
    Set or get feed contributor(s).
77
    
78
    Args:
79
        contributor (dict or list, optional): Contributor information
80
        replace (bool): Replace existing contributors instead of appending
81
        **kwargs: Contributor fields as keyword arguments
82
        
83
    Returns:
84
        list: Current contributors if no argument provided
85
    """
86
```
87

88
### Links and Relationships
89

90
Manage feed links including alternate URLs, self-references, and related resources.
91

92
```python { .api }
93
def link(self, link=None, replace=False, **kwargs):
94
    """
95
    Set or get feed link(s).
96
    
97
    Args:
98
        link (dict or list, optional): Link information
99
        replace (bool): Replace existing links instead of appending
100
        **kwargs: Link fields as keyword arguments
101
        
102
    Returns:
103
        list: Current links if no argument provided
104
    """
105
```
106

107
### Categories and Classification
108

109
Organize feeds with categories and taxonomy information.
110

111
```python { .api }
112
def category(self, category=None, replace=False, **kwargs):
113
    """
114
    Set or get feed categories.
115
    
116
    Args:
117
        category (dict or list, optional): Category information
118
        replace (bool): Replace existing categories instead of appending
119
        **kwargs: Category fields as keyword arguments
120
        
121
    Returns:
122
        list: Current categories if no argument provided
123
    """
124
```
125

126
### Visual Identity
127

128
Set logos, icons, and images for feed branding.
129

130
```python { .api }
131
def logo(self, logo=None):
132
    """
133
    Set or get feed logo URL.
134
    
135
    Args:
136
        logo (str, optional): Logo image URL
137
        
138
    Returns:
139
        str or None: Current logo URL if no argument provided
140
    """
141

142
def icon(self, icon=None):
143
    """
144
    Set or get feed icon URL.
145
    
146
    Args:
147
        icon (str, optional): Icon image URL
148
        
149
    Returns:
150
        str or None: Current icon URL if no argument provided
151
    """
152

153
def image(self, url=None, title=None, link=None, width=None, height=None, description=None):
154
    """
155
    Set or get RSS feed image.
156
    
157
    Args:
158
        url (str, optional): Image URL
159
        title (str, optional): Image title
160
        link (str, optional): Image link URL
161
        width (int, optional): Image width in pixels
162
        height (int, optional): Image height in pixels
163
        description (str, optional): Image description
164
        
165
    Returns:
166
        dict or None: Current image info if no arguments provided
167
    """
168
```
169

170
### Language and Locale
171

172
Set language and localization information.
173

174
```python { .api }
175
def language(self, language=None):
176
    """
177
    Set or get feed language.
178
    
179
    Args:
180
        language (str, optional): Language code (e.g., 'en', 'en-US')
181
        
182
    Returns:
183
        str or None: Current language if no argument provided
184
    """
185
```
186

187
### Timestamps
188

189
Manage feed update and publication timestamps.
190

191
```python { .api }
192
def updated(self, updated=None):
193
    """
194
    Set or get feed updated timestamp (ATOM).
195
    
196
    Args:
197
        updated (datetime or str, optional): Last updated timestamp
198
        
199
    Returns:
200
        datetime or None: Current updated timestamp if no argument provided
201
    """
202

203
def lastBuildDate(self, lastBuildDate=None):
204
    """
205
    Set or get RSS lastBuildDate.
206
    
207
    Args:
208
        lastBuildDate (datetime or str, optional): Last build timestamp
209
        
210
    Returns:
211
        datetime or None: Current lastBuildDate if no argument provided
212
    """
213

214
def pubDate(self, pubDate=None):
215
    """
216
    Set or get RSS publication date.
217
    
218
    Args:
219
        pubDate (datetime or str, optional): Publication timestamp
220
        
221
    Returns:
222
        datetime or None: Current pubDate if no argument provided
223
    """
224
```
225

226
### Rights and Legal
227

228
Manage copyright and rights information.
229

230
```python { .api }
231
def rights(self, rights=None):
232
    """
233
    Set or get feed rights/copyright (ATOM).
234
    
235
    Args:
236
        rights (str, optional): Rights/copyright statement
237
        
238
    Returns:
239
        str or None: Current rights if no argument provided
240
    """
241

242
def copyright(self, copyright=None):
243
    """
244
    Set or get RSS copyright (alias for rights).
245
    
246
    Args:
247
        copyright (str, optional): Copyright statement
248
        
249
    Returns:
250
        str or None: Current copyright if no argument provided
251
    """
252
```
253

254
### RSS-Specific Metadata
255

256
Additional metadata fields specific to RSS feeds.
257

258
```python { .api }
259
def managingEditor(self, managingEditor=None):
260
    """
261
    Set or get RSS managing editor email.
262
    
263
    Args:
264
        managingEditor (str, optional): Managing editor email
265
        
266
    Returns:
267
        str or None: Current managing editor if no argument provided
268
    """
269

270
def webMaster(self, webMaster=None):
271
    """
272
    Set or get RSS webmaster email.
273
    
274
    Args:
275
        webMaster (str, optional): Webmaster email
276
        
277
    Returns:
278
        str or None: Current webmaster if no argument provided
279
    """
280

281
def ttl(self, ttl=None):
282
    """
283
    Set or get RSS time-to-live in minutes.
284
    
285
    Args:
286
        ttl (int, optional): TTL in minutes
287
        
288
    Returns:
289
        int or None: Current TTL if no argument provided
290
    """
291

292
def docs(self, docs=None):
293
    """
294
    Set or get RSS documentation URL.
295
    
296
    Args:
297
        docs (str, optional): Documentation URL
298
        
299
    Returns:
300
        str or None: Current docs URL if no argument provided
301
    """
302

303
def rating(self, rating=None):
304
    """
305
    Set or get RSS PICS rating.
306
    
307
    Args:
308
        rating (str, optional): PICS rating
309
        
310
    Returns:
311
        str or None: Current rating if no argument provided
312
    """
313

314
def skipHours(self, hours=None, replace=False):
315
    """
316
    Set or get RSS skipHours (hours to skip updates).
317
    
318
    Args:
319
        hours (list, optional): List of hours (0-23) to skip
320
        replace (bool): Replace existing hours instead of appending
321
        
322
    Returns:
323
        list or None: Current skipHours if no argument provided
324
    """
325

326
def skipDays(self, days=None, replace=False):
327
    """
328
    Set or get RSS skipDays (days to skip updates).
329
    
330
    Args:
331
        days (list, optional): List of days to skip ('Monday', 'Tuesday', etc.)
332
        replace (bool): Replace existing days instead of appending
333
        
334
    Returns:
335
        list or None: Current skipDays if no argument provided
336
    """
337

338
def textInput(self, title=None, description=None, name=None, link=None):
339
    """
340
    Set or get RSS textInput element.
341
    
342
    Args:
343
        title (str, optional): Text input title
344
        description (str, optional): Text input description
345
        name (str, optional): Text input name
346
        link (str, optional): Text input processing URL
347
        
348
    Returns:
349
        dict or None: Current textInput info if no arguments provided
350
    """
351

352
def cloud(self, domain=None, port=None, path=None, registerProcedure=None, protocol=None):
353
    """
354
    Set or get RSS cloud element for real-time notifications.
355
    
356
    Args:
357
        domain (str, optional): Domain where the webservice can be found
358
        port (int, optional): Port the webservice listens to
359
        path (str, optional): Path of the webservice
360
        registerProcedure (str, optional): Procedure to call
361
        protocol (str, optional): Protocol - 'HTTP-POST', 'XML-RPC', or 'SOAP 1.1'
362
        
363
    Returns:
364
        dict or None: Current cloud info if no arguments provided
365
    """
366

367
def generator(self, generator=None, version=None, uri=None):
368
    """
369
    Set or get feed generator metadata.
370
    
371
    Args:
372
        generator (str, optional): Software used to create the feed
373
        version (str, optional): Version of the software (ATOM only)
374
        uri (str, optional): URI where software can be found (ATOM only)
375
        
376
    Returns:
377
        dict or None: Current generator info if no arguments provided
378
    """
379
```
380

381
## Usage Examples
382

383
### Basic Feed Setup
384

385
```python
386
from feedgen.feed import FeedGenerator
387

388
fg = FeedGenerator()
389

390
# Required metadata
391
fg.id('http://example.com/feed')
392
fg.title('My Technology Blog')
393
fg.description('Latest posts about web development and programming')
394

395
# Author information
396
fg.author({
397
    'name': 'John Doe',
398
    'email': 'john@example.com',
399
    'uri': 'http://johndoe.com'
400
})
401

402
# Multiple ways to set the same data
403
fg.author(name='Jane Smith', email='jane@example.com')  # kwargs
404
fg.author([{'name': 'Bob Wilson', 'email': 'bob@example.com'}])  # list
405
```
406

407
### Links and Categories
408

409
```python
410
# Add links
411
fg.link(href='http://example.com', rel='alternate')
412
fg.link(href='http://example.com/feed.atom', rel='self')
413

414
# Add categories
415
fg.category(term='technology', label='Technology')
416
fg.category([
417
    {'term': 'programming', 'label': 'Programming'},
418
    {'term': 'web-dev', 'label': 'Web Development'}
419
])
420
```
421

422
### Visual Identity and Branding
423

424
```python
425
# Set logo and icon
426
fg.logo('http://example.com/logo.png')
427
fg.icon('http://example.com/favicon.ico')
428

429
# RSS image
430
fg.image(
431
    url='http://example.com/banner.jpg',
432
    title='My Blog Banner',
433
    link='http://example.com',
434
    width=400,
435
    height=100
436
)
437
```
438

439
### Timestamps and Updates
440

441
```python
442
from datetime import datetime
443
import dateutil.tz
444

445
now = datetime.now(dateutil.tz.tzutc())
446

447
fg.updated(now)
448
fg.lastBuildDate(now)
449
fg.pubDate(now)
450

451
# String timestamps are also supported
452
fg.updated('2023-12-01T10:30:00Z')
453
```
454

455
### RSS-Specific Advanced Features
456

457
```python
458
# RSS cloud for real-time notifications  
459
fg.cloud(
460
    domain='example.com',
461
    port=80,
462
    path='/rsscloud',
463
    registerProcedure='notify',
464
    protocol='HTTP-POST'
465
)
466

467
# Generator metadata
468
fg.generator(
469
    generator='MyFeedApp',
470
    version='1.2.0',
471
    uri='https://example.com/myfeedapp'
472
)
473
```