lukasschwab / jsonfeed

Python package for parsing and generating JSON feeds.

jsonfeed

jsonfeed is a Python package for parsing and constructing JSON Feeds. It explicitly supports JSON Feed Version 1.1.

Usage

This package's constructor arguments and class variables exactly match the field names defined in the JSON feed spec. I hope that the code is clear enough that the spec can be its granular documentation.

Installation

Install this package with pip:

$ pip install jsonfeed-util

In your Python code, include the line

import jsonfeed

Parsing a JSON feed

import jsonfeed as jf
import requests

# Requesting a valid JSON feed!
r = requests.get('https://arxiv-feeds.appspot.com/json/test')
# Parse from raw text...
feed_from_text = jf.Feed.parse_string(r.text)
# ...or parse JSON separately.
r_json = r.json()
feed_from_json = jf.Feed.parse(r_json)

Constructing a JSON feed

import jsonfeed as jf

me = jf.Author(
  name="Lukas Schwab",
  url="https://github.com/lukasschwab"
)
feed = jf.Feed("My Feed Title", authors=[me])
item = jf.Item("some_item_id")
feed.items.append(item)

print(feed.toJSON())

jsonfeed exposes constructors for five classes of JSON feed objects:

• Feed
• Author
• Hub
• Item
• Attachment

Note, jsonfeed is designed to be minimally restrictive. It does not require fields that are not required in the JSON Feed spec. This means it's possible to construct nonmeaningful JSON feeds (e.g. with this valid Author object: {}).

Examples

• arxiv-feeds: converts Atom to JSON feeds.
• jsonfeed-wrapper: converts scraped HTML to JSON feeds.
• pandoc-blog: generates a JSON feed for a static site.

Deprecations

See the spec for an overview of deprecated JSON Feed fields. This project (especially the converters and the parsing functions) will stay backwards-compatible when possible, but using deprecated fields when constructing feeds is discouraged.

JSON Feed 1.1

• Feed.author is deprecated. Use Feed.authors.
• Item.author is deprecated. Use Item.authors.

Notes

• Dictionaries maintain insertion order as of Python 3.6. jsonfeed takes advantage of this to retain the order suggested in the JSON Feed spec (namely, that version appear at the top of the JSON object). This order may not be enforced in earlier versions of Python, but out-of-order JSON Feeds are not invalid.

• I made a conscious decision to shoot for code that's readable––vis à vis the JSON Feed spec––rather than code that's minimal or performant. Additionally, I opted to avoid dependencies outside of the standard library. Hopefully this makes for easy maintenance.

jsonfeed's Issues

Introduce date format validation

Dates in output feeds must be in RFC 3339 form for the feed to be valid.

Either validate the dates or receive datetimes in lieu of strings in constructors.

Add unit tests

Following #1. Optionally, add coverage checks.

Add docstrings

Should make the documentation added in #1 significantly more useful.

Improve on `if x in y` construct

The v = w if x in y else z have high cyclomatic complexity and aren't particularly readable. Refactor to use get.

Any chance to see it published on Pypi?

Hello @lukasschwab,

Looking both jsonfeed and your profile, I did not find this package published on Pypi.

Any reason to not to?
Any chance to see it published?