Debian Codegraph @

django/utils/feedgenerator.py

raw
1 """
2 Syndication feed generation library -- used for generating RSS, etc.
3
4 Sample usage:
5
6 >>> from django.utils import feedgenerator
7 >>> feed = feedgenerator.Rss201rev2Feed(
8 ... title="Poynter E-Media Tidbits",
9 ... link="http://www.poynter.org/column.asp?id=31",
10 ... description="A group blog by the sharpest minds in online journalism.",
11 ... language="en",
12 ... )
13 >>> feed.add_item(
14 ... title="Hello",
15 ... link="http://www.holovaty.com/test/",
16 ... description="Testing."
17 ... )
18 >>> with open('test.rss', 'w') as fp:
19 ... feed.write(fp, 'utf-8')
20
21 For definitions of the different versions of RSS, see:
22 https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss
23 """
24
25 import datetime
26 import email
27 import mimetypes
28 from io import StringIO
29 from urllib.parse import urlparse
30
31 from django.forms.utils import flatatt
32 from django.utils.encoding import iri_to_uri
33 from django.utils.xmlutils import SimplerXMLGenerator
34
35
36 def rfc2822_date(date):
37 if not isinstance(date, datetime.datetime):
38 date = datetime.datetime.combine(date, datetime.time())
39 return email.utils.format_datetime(date)
40
41
42 def rfc3339_date(date):
43 if not isinstance(date, datetime.datetime):
44 date = datetime.datetime.combine(date, datetime.time())
45 return date.isoformat() + ("Z" if date.utcoffset() is None else "")
46
47
48 def get_tag_uri(url, date):
49 """
50 Create a TagURI.
51
52 See
53 https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
54 """
55 bits = urlparse(url)
56 d = ""
57 if date is not None:
58 d = ",%s" % date.strftime("%Y-%m-%d")
59 return "tag:%s%s:%s/%s" % (bits.hostname, d, bits.path, bits.fragment)
60
61
62 def _guess_stylesheet_mimetype(url):
63 """
64 Return the given stylesheet's mimetype tuple, using a slightly custom
65 version of Python's mimetypes.guess_type().
66 """
67 mimetypedb = mimetypes.MimeTypes()
68
69 # The official mimetype for XSLT files is technically `application/xslt+xml`
70 # but as of 2024 almost no browser supports that (they all expect text/xsl).
71 # On top of that, windows seems to assume that the type for xsl is text/xml.
72 mimetypedb.readfp(StringIO("text/xsl\txsl\ntext/xsl\txslt"))
73
74 return mimetypedb.guess_type(url)
75
76
77 class Stylesheet:
78 """An RSS stylesheet"""
79
80 def __init__(self, url, mimetype="", media="screen"):
81 self._url = url
82 self._mimetype = mimetype
83 self.media = media
84
85 # Using a property to delay the evaluation of self._url as late as possible
86 # in case of a lazy object (like reverse_lazy(...) for example).
87 @property
88 def url(self):
89 return iri_to_uri(self._url)
90
91 @property
92 def mimetype(self):
93 if self._mimetype == "":
94 return _guess_stylesheet_mimetype(self.url)[0]
95 return self._mimetype
96
97 def __str__(self):
98 attrs = {
99 "href": iri_to_uri(self._url),
100 "type": self.mimetype,
101 "media": self.media,
102 }
103 return flatatt(attrs).strip()
104
105 def __repr__(self):
106 return repr((self.url, self.mimetype, self.media))
107
108
109 class SyndicationFeed:
110 "Base class for all syndication feeds. Subclasses should provide write()"
111
112 def __init__(
113 self,
114 title,
115 link,
116 description,
117 language=None,
118 author_email=None,
119 author_name=None,
120 author_link=None,
121 subtitle=None,
122 categories=None,
123 feed_url=None,
124 feed_copyright=None,
125 feed_guid=None,
126 ttl=None,
127 stylesheets=None,
128 **kwargs,
129 ):
130 def to_str(s):
131 return str(s) if s is not None else s
132
133 def to_stylesheet(s):
134 return s if isinstance(s, Stylesheet) else Stylesheet(s)
135
136 categories = categories and [str(c) for c in categories]
137
138 if stylesheets is not None:
139 if isinstance(stylesheets, (Stylesheet, str)):
140 raise TypeError(
141 f"stylesheets should be a list, not {stylesheets.__class__}"
142 )
143 stylesheets = [to_stylesheet(s) for s in stylesheets]
144
145 self.feed = {
146 "title": to_str(title),
147 "link": iri_to_uri(link),
148 "description": to_str(description),
149 "language": to_str(language),
150 "author_email": to_str(author_email),
151 "author_name": to_str(author_name),
152 "author_link": iri_to_uri(author_link),
153 "subtitle": to_str(subtitle),
154 "categories": categories or (),
155 "feed_url": iri_to_uri(feed_url),
156 "feed_copyright": to_str(feed_copyright),
157 "id": feed_guid or link,
158 "ttl": to_str(ttl),
159 "stylesheets": stylesheets,
160 **kwargs,
161 }
162 self.items = []
163
164 def add_item(
165 self,
166 title,
167 link,
168 description,
169 author_email=None,
170 author_name=None,
171 author_link=None,
172 pubdate=None,
173 comments=None,
174 unique_id=None,
175 unique_id_is_permalink=None,
176 categories=(),
177 item_copyright=None,
178 ttl=None,
179 updateddate=None,
180 enclosures=None,
181 **kwargs,
182 ):
183 """
184 Add an item to the feed. All args are expected to be strings except
185 pubdate and updateddate, which are datetime.datetime objects, and
186 enclosures, which is an iterable of instances of the Enclosure class.
187 """
188
189 def to_str(s):
190 return str(s) if s is not None else s
191
192 categories = categories and [to_str(c) for c in categories]
193 self.items.append(
194 {
195 "title": to_str(title),
196 "link": iri_to_uri(link),
197 "description": to_str(description),
198 "author_email": to_str(author_email),
199 "author_name": to_str(author_name),
200 "author_link": iri_to_uri(author_link),
201 "pubdate": pubdate,
202 "updateddate": updateddate,
203 "comments": to_str(comments),
204 "unique_id": to_str(unique_id),
205 "unique_id_is_permalink": unique_id_is_permalink,
206 "enclosures": enclosures or (),
207 "categories": categories or (),
208 "item_copyright": to_str(item_copyright),
209 "ttl": to_str(ttl),
210 **kwargs,
211 }
212 )
213
214 def num_items(self):
215 return len(self.items)
216
217 def root_attributes(self):
218 """
219 Return extra attributes to place on the root (i.e. feed/channel) element.
220 Called from write().
221 """
222 return {}
223
224 def add_root_elements(self, handler):
225 """
226 Add elements in the root (i.e. feed/channel) element. Called
227 from write().
228 """
229 pass
230
231 def add_stylesheets(self, handler):
232 """
233 Add stylesheet(s) to the feed. Called from write().
234 """
235 pass
236
237 def item_attributes(self, item):
238 """
239 Return extra attributes to place on each item (i.e. item/entry) element.
240 """
241 return {}
242
243 def add_item_elements(self, handler, item):
244 """
245 Add elements on each item (i.e. item/entry) element.
246 """
247 pass
248
249 def write(self, outfile, encoding):
250 """
251 Output the feed in the given encoding to outfile, which is a file-like
252 object. Subclasses should override this.
253 """
254 raise NotImplementedError(
255 "subclasses of SyndicationFeed must provide a write() method"
256 )
257
258 def writeString(self, encoding):
259 """
260 Return the feed in the given encoding as a string.
261 """
262 s = StringIO()
263 self.write(s, encoding)
264 return s.getvalue()
265
266 def latest_post_date(self):
267 """
268 Return the latest item's pubdate or updateddate. If no items
269 have either of these attributes this return the current UTC date/time.
270 """
271 latest_date = None
272 date_keys = ("updateddate", "pubdate")
273
274 for item in self.items:
275 for date_key in date_keys:
276 item_date = item.get(date_key)
277 if item_date:
278 if latest_date is None or item_date > latest_date:
279 latest_date = item_date
280
281 return latest_date or datetime.datetime.now(tz=datetime.timezone.utc)
282
283
284 class Enclosure:
285 """An RSS enclosure"""
286
287 def __init__(self, url, length, mime_type):
288 "All args are expected to be strings"
289 self.length, self.mime_type = length, mime_type
290 self.url = iri_to_uri(url)
291
292
293 class RssFeed(SyndicationFeed):
294 content_type = "application/rss+xml; charset=utf-8"
295
296 def write(self, outfile, encoding):
297 handler = SimplerXMLGenerator(outfile, encoding, short_empty_elements=True)
298 handler.startDocument()
299 # Any stylesheet must come after the start of the document but before any tag.
300 # https://www.w3.org/Style/styling-XML.en.html
301 self.add_stylesheets(handler)
302 handler.startElement("rss", self.rss_attributes())
303 handler.startElement("channel", self.root_attributes())
304 self.add_root_elements(handler)
305 self.write_items(handler)
306 self.endChannelElement(handler)
307 handler.endElement("rss")
308
309 def rss_attributes(self):
310 return {
311 "version": self._version,
312 "xmlns:atom": "http://www.w3.org/2005/Atom",
313 }
314
315 def write_items(self, handler):
316 for item in self.items:
317 handler.startElement("item", self.item_attributes(item))
318 self.add_item_elements(handler, item)
319 handler.endElement("item")
320
321 def add_stylesheets(self, handler):
322 for stylesheet in self.feed["stylesheets"] or []:
323 handler.processingInstruction("xml-stylesheet", stylesheet)
324
325 def add_root_elements(self, handler):
326 handler.addQuickElement("title", self.feed["title"])
327 handler.addQuickElement("link", self.feed["link"])
328 handler.addQuickElement("description", self.feed["description"])
329 if self.feed["feed_url"] is not None:
330 handler.addQuickElement(
331 "atom:link", None, {"rel": "self", "href": self.feed["feed_url"]}
332 )
333 if self.feed["language"] is not None:
334 handler.addQuickElement("language", self.feed["language"])
335 for cat in self.feed["categories"]:
336 handler.addQuickElement("category", cat)
337 if self.feed["feed_copyright"] is not None:
338 handler.addQuickElement("copyright", self.feed["feed_copyright"])
339 handler.addQuickElement("lastBuildDate", rfc2822_date(self.latest_post_date()))
340 if self.feed["ttl"] is not None:
341 handler.addQuickElement("ttl", self.feed["ttl"])
342
343 def endChannelElement(self, handler):
344 handler.endElement("channel")
345
346
347 class RssUserland091Feed(RssFeed):
348 _version = "0.91"
349
350 def add_item_elements(self, handler, item):
351 handler.addQuickElement("title", item["title"])
352 handler.addQuickElement("link", item["link"])
353 if item["description"] is not None:
354 handler.addQuickElement("description", item["description"])
355
356
357 class Rss201rev2Feed(RssFeed):
358 # Spec: https://cyber.harvard.edu/rss/rss.html
359 _version = "2.0"
360
361 def add_item_elements(self, handler, item):
362 handler.addQuickElement("title", item["title"])
363 handler.addQuickElement("link", item["link"])
364 if item["description"] is not None:
365 handler.addQuickElement("description", item["description"])
366
367 # Author information.
368 if item["author_name"] and item["author_email"]:
369 handler.addQuickElement(
370 "author", "%s (%s)" % (item["author_email"], item["author_name"])
371 )
372 elif item["author_email"]:
373 handler.addQuickElement("author", item["author_email"])
374 elif item["author_name"]:
375 handler.addQuickElement(
376 "dc:creator",
377 item["author_name"],
378 {"xmlns:dc": "http://purl.org/dc/elements/1.1/"},
379 )
380
381 if item["pubdate"] is not None:
382 handler.addQuickElement("pubDate", rfc2822_date(item["pubdate"]))
383 if item["comments"] is not None:
384 handler.addQuickElement("comments", item["comments"])
385 if item["unique_id"] is not None:
386 guid_attrs = {}
387 if isinstance(item.get("unique_id_is_permalink"), bool):
388 guid_attrs["isPermaLink"] = str(item["unique_id_is_permalink"]).lower()
389 handler.addQuickElement("guid", item["unique_id"], guid_attrs)
390 if item["ttl"] is not None:
391 handler.addQuickElement("ttl", item["ttl"])
392
393 # Enclosure.
394 if item["enclosures"]:
395 enclosures = list(item["enclosures"])
396 if len(enclosures) > 1:
397 raise ValueError(
398 "RSS feed items may only have one enclosure, see "
399 "http://www.rssboard.org/rss-profile#element-channel-item-enclosure"
400 )
401 enclosure = enclosures[0]
402 handler.addQuickElement(
403 "enclosure",
404 "",
405 {
406 "url": enclosure.url,
407 "length": enclosure.length,
408 "type": enclosure.mime_type,
409 },
410 )
411
412 # Categories.
413 for cat in item["categories"]:
414 handler.addQuickElement("category", cat)
415
416
417 class Atom1Feed(SyndicationFeed):
418 # Spec: https://tools.ietf.org/html/rfc4287
419 content_type = "application/atom+xml; charset=utf-8"
420 ns = "http://www.w3.org/2005/Atom"
421
422 def write(self, outfile, encoding):
423 handler = SimplerXMLGenerator(outfile, encoding, short_empty_elements=True)
424 handler.startDocument()
425 handler.startElement("feed", self.root_attributes())
426 self.add_root_elements(handler)
427 self.write_items(handler)
428 handler.endElement("feed")
429
430 def root_attributes(self):
431 if self.feed["language"] is not None:
432 return {"xmlns": self.ns, "xml:lang": self.feed["language"]}
433 else:
434 return {"xmlns": self.ns}
435
436 def add_root_elements(self, handler):
437 handler.addQuickElement("title", self.feed["title"])
438 handler.addQuickElement(
439 "link", "", {"rel": "alternate", "href": self.feed["link"]}
440 )
441 if self.feed["feed_url"] is not None:
442 handler.addQuickElement(
443 "link", "", {"rel": "self", "href": self.feed["feed_url"]}
444 )
445 handler.addQuickElement("id", self.feed["id"])
446 handler.addQuickElement("updated", rfc3339_date(self.latest_post_date()))
447 if self.feed["author_name"] is not None:
448 handler.startElement("author", {})
449 handler.addQuickElement("name", self.feed["author_name"])
450 if self.feed["author_email"] is not None:
451 handler.addQuickElement("email", self.feed["author_email"])
452 if self.feed["author_link"] is not None:
453 handler.addQuickElement("uri", self.feed["author_link"])
454 handler.endElement("author")
455 if self.feed["subtitle"] is not None:
456 handler.addQuickElement("subtitle", self.feed["subtitle"])
457 for cat in self.feed["categories"]:
458 handler.addQuickElement("category", "", {"term": cat})
459 if self.feed["feed_copyright"] is not None:
460 handler.addQuickElement("rights", self.feed["feed_copyright"])
461
462 def write_items(self, handler):
463 for item in self.items:
464 handler.startElement("entry", self.item_attributes(item))
465 self.add_item_elements(handler, item)
466 handler.endElement("entry")
467
468 def add_item_elements(self, handler, item):
469 handler.addQuickElement("title", item["title"])
470 handler.addQuickElement("link", "", {"href": item["link"], "rel": "alternate"})
471
472 if item["pubdate"] is not None:
473 handler.addQuickElement("published", rfc3339_date(item["pubdate"]))
474
475 if item["updateddate"] is not None:
476 handler.addQuickElement("updated", rfc3339_date(item["updateddate"]))
477
478 # Author information.
479 if item["author_name"] is not None:
480 handler.startElement("author", {})
481 handler.addQuickElement("name", item["author_name"])
482 if item["author_email"] is not None:
483 handler.addQuickElement("email", item["author_email"])
484 if item["author_link"] is not None:
485 handler.addQuickElement("uri", item["author_link"])
486 handler.endElement("author")
487
488 # Unique ID.
489 if item["unique_id"] is not None:
490 unique_id = item["unique_id"]
491 else:
492 unique_id = get_tag_uri(item["link"], item["pubdate"])
493 handler.addQuickElement("id", unique_id)
494
495 # Summary.
496 if item["description"] is not None:
497 handler.addQuickElement("summary", item["description"], {"type": "html"})
498
499 # Enclosures.
500 for enclosure in item["enclosures"]:
501 handler.addQuickElement(
502 "link",
503 "",
504 {
505 "rel": "enclosure",
506 "href": enclosure.url,
507 "length": enclosure.length,
508 "type": enclosure.mime_type,
509 },
510 )
511
512 # Categories.
513 for cat in item["categories"]:
514 handler.addQuickElement("category", "", {"term": cat})
515
516 # Rights.
517 if item["item_copyright"] is not None:
518 handler.addQuickElement("rights", item["item_copyright"])
519
520
521 # This isolates the decision of what the system default is, so calling code can
522 # do "feedgenerator.DefaultFeed" instead of "feedgenerator.Rss201rev2Feed".
523 DefaultFeed = Rss201rev2Feed