butterdb is a Python object mapper for Google Drive Spreadsheets. Still in development, but usable.
Switch branches/tags
Nothing to show
Clone or download
Latest commit bf1793a Jun 12, 2015



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?


import butterdb
import json

# For getting OAuth Credential JSON file see http://gspread.readthedocs.org/en/latest/oauth2.html
# 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.name = 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 ncwjohnstone@gmail.com.


MIT License. See LICENSE file for full text.