skip to navigation
skip to content

Not Logged In

butterdb 0.1.4

butterdb is a Python ORM for Google Drive Spreadsheets.

Latest Version: 0.1.5


| 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  
File Type Py Version Uploaded on Size
butterdb-0.1.4.tar.gz (md5) Source 2014-04-07 5KB
  • Downloads (All Versions):
  • 13 downloads in the last day
  • 56 downloads in the last week
  • 288 downloads in the last month