quick start tutorial

Browse Source
This commit is contained in:
Gregor Aisch 2013-04-01 22:40:28 +02:00
parent 077b3f520f
commit a82a7d3cde
1 changed files with 58 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/index.rst
View File

@ -6,50 +6,6 @@
Welcome to dataset's documentation!
===================================
Simple API::
import dataset
# open a sqlite database (or create one if it doesn't exist yet)
db = dataset.connect('sqlite:///factbook.db')
# get a wrapper for the table 'population'
# this will create the table if it doesn't exist yet
table = db['population']
# insert a new row (and also create the columns if they don't exist yet)
table.insert(dict(country='China', year=2012, population=1354040000))
table.insert(dict(country='India', year=2011, population=1210193422))
# you can easily add new columns at any time
table.insert(dict(country='United States', year=2013, population=315591999, source='http://www.census.gov'))
.. autofunction:: dataset.connect
Database
========
A Database is a simple wrapper around SQLAlchemy engines. Most of the time you want to use it to get instances to tables using *get_table* or the short-hand dict syntax::
# both statements return the same table
table = db['population']
table = db.get_table('population')
.. autoclass:: dataset.Database
:members: get_table, create_table, load_table, query
:undoc-members:
Table
=====
Using the *Table* class you can easily store and retreive data from database tables.
.. autoclass:: dataset.Table
:members:
:undoc-members:
Contents:
.. toctree::
@ -57,6 +13,64 @@ Contents:
Quick-start
===========
At first you need to import the package :). To connect to a database you need to identify it using
what is called an engine url. Here are a few examples::
import dataset
# connecting to a SQLite database
db = dataset.connect('sqlite:///factbook.db')
# connecting to a MySQL database
db = dataset.connect('mysql:///')
Storing data
------------
Storing data in a table is as simple. **dataset** will automatically create the columns, if they don't exist yet::
table.insert(dict(country='China', year=2012, population=1354040000))
Reading data from tables
------------------------
Checking::
table = db['population']
# Let's grab a list of all items/rows/entries in the table:
table.all()
table.distinct()
Searching for specific entries::
# Returns the first item where the column country equals 'China'
table.find_one(country='China')
# Returns all items
table.find(country='China')
You can add additional columns at any time::
table.insert(dict(country='US', year=2013, population=315591999, source='http://www.census.gov'))
Updating existing entries::
table.update(dict(country='China', year=2012, population=1354040001), ['country', 'year'])
Indices and tables
==================