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

Project details

Download files

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

Source Distribution

butterdb-0.1.4.tar.gz (5.2 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page