buttercms-python - 2.1.1

Python Library for ButterCMS API.

[!IMPORTANT] We officially support Python versions 3.8 to 3.12. While compatibility with other Python 3.x versions is possible, as we currently do not utilize any version-specific features, it is not guaranteed.

Documentation

For a comprehensive list of examples, check out the API documentation.

Jump to:

• Pages
• Collections
• Posts
• Authors
• Categories
• Feeds

Installation

Install from PyPi using pip, a package manager for Python.

pip install buttercms-python

Usage

Getting started with the ButterCMS API couldn't be easier. Use your authorization token to create a ButterCMS client.

from butter_cms import ButterCMS

auth_token = "XXXXXXXXXXXXXXXXXXX"
client = ButterCMS(auth_token)

All methods return dictionaries. The data can be navigated using keys and indexes like the example below.

response = client.posts.all()

posts = response['data'] 
# posts now contains a list of post dictionaries

my_post = posts[0]
# my_post contains the first returned post

print(my_post)
# {
#   "url": "http://www.example.com/blog/this-is-a-blog-post",
#   "created": "2015-06-12T13:59:32.441289Z",
#   "published": "2015-06-12T00:00:00Z",
#   ...
# }

Pages

The Page's .all(), .get() and .search() methods accept an optional params to add additional data to the response.

client.pages.all('news')

# Optional params
client.pages.all('news', {'foo': 'bar'})

client.pages.get('news', 'hello-world')

# Optional params
client.pages.get('news', 'hello-world', {'foo': 'bar'})

client.pages.search('enter search query', {'page': 1, 'page_size': 10})

To Top

Collections

For a list of params see the API documentation

.get() method accepts an optional params dict to add additional data to the response.

client.content_fields.get(['collection_key'], {'locale': 'en'})

To Top

Blog Engine

Posts

client.posts.all({'page_size': 3, 'page': 1, 'exclude_body': 'true'})

client.posts.get('hello-world')

client.posts.search('query', {'page': 1, 'page_size': 10})

Authors

The Author's .all() and .get() methods accept an optional params to add additional data to the response.

• {'include':'recent_posts'}: Adds each author's posts under the recent_posts key in that author's returned dictionary

client.authors.all()
client.authors.all({'include':'recent_posts'})

client.authors.get('jennifer-smith')
client.authors.get('jennifer-smith', {'include':'recent_posts'})

To Top

Categories

The Category's .all() and .get() methods accept an optional params to add additional data to the response.

• {'include':'recent_posts'}: Adds posts tagged with that category under the recent_posts key in that category's returned dictionary

client.categories.all()
client.categories.all({'include':'recent_posts'})

client.categories.get('product-updates')
client.categories.get('product-updates', {'include':'recent_posts'})

To Top

Tags

The Tag's .all() and .get() methods accept an optional params to add additional data to the response.

• {'include':'recent_posts'}: Adds posts tagged with that tag under the recent_posts key in that tag's returned dictionary

client.tags.all()
client.tags.all({'include':'recent_posts'})

client.tags.get('product-updates')
client.tags.get('product-updates', {'include':'recent_posts'})

To Top

Feeds

client.feeds.get('rss')

client.feeds.get('atom')

client.feeds.get('sitemap')

To Top

Other

View Python Blog engine and Full CMS for other examples of using ButterCMS with Python.

Tests

To run tests:

python -m unittest butter_cms/unit_tests.py