| 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 |