Skip to main content

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

Project details

Download files

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

Files for butterdb, version 0.1.5
Filename, size File type Python version Upload date Hashes
Filename, size butterdb-0.1.5.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page