FastFeedParser

Install the core package using pip:

pip install fastfeedparser

Optional Extras

Depending on your needs, you can install additional dependencies:

• Brotli support (for Content-Encoding: br):

  pip install fastfeedparser[brotli]

- **Advanced date parsing fallback** (using `dateparser`):
  ```bash
pip install fastfeedparser[dateparser]

• Full installation (includes both Brotli and dateparser):

  pip install fastfeedparser[full]

The parse function returns a FastFeedParserDict. This is a specialized dictionary that allows you to access keys as attributes, making it behave similarly to an object. This is useful for navigating nested feed structures like feed.title or entry.link instead of using bracket notation feed['title'].

from fastfeedparser import parse

feed = parse("https://example.com/feed.xml")

# Accessing feed-level information as attributes
print(feed.feed.title)
print(feed.feed.link)

# Accessing entries
for entry in feed.entries:
    print(entry.title)
    print(entry.link)

The fastfeedparser.parse() function is the primary entry point. It accepts a URL or a raw XML/JSON string as the source argument.

Usage Examples

Parsing from a URL:

import fastfeedparser
myfeed = fastfeedparser.parse('https://example.com/feed.xml')

Parsing from a string:

import fastfeedparser
xml_content = '''<?xml version="1.0"?>
<rss version="2.0">
    <channel>
        <title>Example Feed</title>
    </channel>
</rss>'''
myfeed = fastfeedparser.parse(xml_content)

import fastfeedparser

# Parse from URL
myfeed = fastfeedparser.parse('https://example.com/feed.xml')

# Parse from string
xml_content = '''<?xml version="1.0"?>
<rss version="2.0">
    <channel>
        <title>Example Feed</title>
        ...
    </channel>
</rss>'''
myfeed = fastfeedparser.parse(xml_content)

The parse() function allows you to toggle specific field extractions to optimize parsing speed. Use these keyword arguments:

• include_content (bool): Whether to extract full content.
• include_tags (bool): Whether to extract tags.
• include_media (bool): Whether to extract media information.
• include_enclosures (bool): Whether to extract enclosures.

All arguments default to True to ensure complete parsing.

# Example of optimized parsing by disabling heavy fields
myfeed = fastfeedparser.parse('https://example.com/feed.xml', include_content=False, include_media=False)

To compare the performance of FastFeedParser against the standard feedparser library, run the included benchmark script:

python benchmark.py

The output will show the speedup factor for various feeds and a summary report including total wall-clock time, average parsing time per feed, and feeds processed per second.

The _normalize_iso_datetime_string function coerces flexible ISO-8601 inputs into a format compatible with Python's datetime.fromisoformat.

It performs several specific transformations:

• Converts Z or z suffixes to +00:00.
• Handles timezone offsets like +HH:MM or -HH:MM.
• Replaces common timezone suffixes like UTC, GMT, or Z with +00:00.
• Converts space-separated date/time (e.g., 2024-01-15 10:30:00) to the T separator format (2024-01-15T10:30:00).
• Fixes missing colons in timezone offsets (e.g., +0500 to +05:00).
• Normalizes sub-second fractions to a maximum of 6 digits.

# Example transformations:
# "2024-01-15T10:30:00Z" -> "2024-01-15T10:30:00+00:00"
# "2024-01-15 10:30:00" -> "2024-01-15T10:30:00"
# "2024-01-15T10:30:00 GMT" -> "2024-01-15T10:30:00+00:00"

FastFeedParser provides mechanisms to extract the main body content of a feed entry.

Content Extraction

When include_content is enabled, the parser looks for:

• RSS: <content:encoded> or <content> elements, falling back to the <description> text.
• Atom: The <content> element.

Content is returned as a list of dictionaries containing type (e.g., text/html, application/xhtml+xml), language, base, and the value (the actual content string).

Description Synthesis

If an entry has content but lacks a description, the parser can synthesize a description by:

1. Stripping HTML tags from the beginning of the content (up to 2048 characters).
2. Unescaping HTML entities.
3. Collapsing whitespace.
4. Truncating the result to 512 characters.

The parser supports extracting taxonomies (tags or categories) from RSS, Atom, and RDF feeds when include_tags is set to True.

• RSS: Extracts <category> elements and <dc:subject> elements. The term is the text content, and scheme is mapped from the domain attribute.
• Atom: Extracts <category> elements. Each tag includes term, scheme, and label attributes.
• RDF: Extracts <dc:subject> elements and <taxo:topic> elements. For taxo:topic, the term is derived from the element text or the rdf:resource attribute.

FastFeedParser can extract rich media information and file attachments (enclosures) from feed entries.

Media Content

If include_media is enabled, the parser extracts metadata for media elements, including:

• url: The media URL
• type: MIME type
• medium: The medium type (e.g., image, video)
• width / height: Dimensions (coerced to integers)
• title / text / description: Textual metadata
• credit / credit_scheme: Attribution information
• thumbnail_url: URL for a thumbnail

Enclosures

If include_enclosures is enabled, the parser extracts file attachments. Each enclosure contains:

• url: The file URL
• type: The MIME type
• length: The file size in bytes (coerced to an integer)

Note: These features depend on the presence of the appropriate namespaces (like media) in the feed.