Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

butterdb is a Python ORM for Google Drive Spreadsheets.

Project Description


| Master: |Build Status Master|
| Develop: |Build Status Develop|

`Documentation`_ | `butterdb on PyPi`_

butterdb is a library to help you work with Google Spreadsheet data. It lets you model your data as Python objects, to be easily manipulated or created.

How do I use it?
.. image::


import butterdb
import json

# For getting OAuth Credential JSON file see
# Ensure that the client_email has been granted privileges to any workbooks you wish to access.

with open('SomeGoogleProject-2a31d827b2a9.json') as credentials_file:
json_key = json.load(credentials_file)

client_email = json_key['client_email']
private_key = str(json_key['private_key']).encode('utf-8')

database = butterdb.Database(name="MyDatabaseSheet", client_email=client_email, private_key=private_key)

class User(butterdb.Model):
def __init__(self, name, password): = self.field(name)
self.password = self.field(password)

users = User.get_instances()

marianne = users[1]

print(marianne.password) # rainbow_trout

marianne.password = "hunter2"

How do I make instances?


bob = User("bob", "BestPassword!")

Where do I get it?

``pip install butterdb``

Simple as that?
Yep! butterdb is a simple interface around `gspread`_. Just .commit() your objects when you want to update the spreadsheet!

How do I run the tests?

What works?
* Store data in Google Spreadsheets (the cloud!!!)
* Models from classes
* Fields as attributes. decimals, ints and strings only (as far as I know)
* Commits
* Mocked unit tests, mock database
* Arbitrary cell execution with `=blah()` (free stored procedures?)
* Auto backup/bad patch control

What's missing?
* Spreadsheets must exist before connecting
* References
* Collections
* Customizable fields
* Customizable table size (arbitrarily hardcoded)

Comments, concerns, issues and pull requests welcomed. Reddit /u/Widdershiny or email me at


MIT License. See LICENSE file for full text.

.. _Documentation:
.. _butterdb on PyPi:
.. _gspread:

.. |Build Status Master| image::
.. |Build Status Develop| image::


0.1.0 7/3/14

* First release on PyPI.

0.1.1 7/3/14

* Converted readme to rst from md

0.1.2 7/3/14

* Included HISTORY.rst in package build

0.1.3 7/3/14

* Model.field no longer requires name to be specified. Attribute name will be used if none is provided.
* Model no longer needs to have id as a keyword argument, or call super in init
* Tests now use pep8 asserts

0.1.4 7/4/14

* Renamed project to butterdb

0.1.5 12/6/15

* Use OAuth instead of now deprecated simple login (thanks to @julierae!)
* Fix a bug in get_instance that broke modifying fields (thanks to @dequis!)

Release History

This version
History Node


History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(5.9 kB) Copy SHA256 Hash SHA256
Source None Jun 12, 2015

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers DreamHost DreamHost Log Hosting