From b9f52fb384203c1f6eb3518a85abe7661ee1389c Mon Sep 17 00:00:00 2001 From: Gregor Aisch Date: Mon, 1 Apr 2013 23:36:09 +0200 Subject: [PATCH] documentation! --- docs/api.rst | 14 +++------ docs/index.rst | 61 ++---------------------------------- docs/quickstart.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 67 deletions(-) create mode 100644 docs/quickstart.rst diff --git a/docs/api.rst b/docs/api.rst index 61e2d07..56d428e 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,5 +1,7 @@ -Contents: +API documentation +================= + .. toctree:: :maxdepth: 2 @@ -10,13 +12,7 @@ Contents: 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 @@ -25,7 +21,7 @@ A Database is a simple wrapper around SQLAlchemy engines. Most of the time you w Table -===== +----- Using the *Table* class you can easily store and retreive data from database tables. diff --git a/docs/index.rst b/docs/index.rst index 284d664..a73827f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,68 +6,13 @@ Welcome to dataset's documentation! =================================== -Contents: +Getting the databases out of your data's way. .. toctree:: :maxdepth: 2 - - -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']) - - - +* `Learn how to use dataset in five minutes `_ +* `Browse the complete API docs `_ diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..24a1e1d --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,75 @@ + +Quick-start +=========== + + +.. toctree:: + :maxdepth: 2 + +Hi, welcome to the five-minute quick-start tutorial. + +At first you need to import the package :).:: + + import dataset + +To connect to a database you need to identify it using what is called an engine url. Here are a few examples:: + + # connecting to a SQLite database + db = dataset.connect('sqlite:///factbook.db') + + # connecting to a MySQL database + db = dataset.connect('mysql://user:password@localhost/mydatabase') + + # connecting to a PostgreSQL database + db = dataset.connect('postgresql://scott:tiger@localhost:5432/mydatabase') + +If you want to learn more about how to connect to various databases, have a look at the `SQLAlchemy documentation`_. + +.. _SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#engine-creation-api + +Storing data +------------ + +At first you need to get a reference to the table in which you want to store your data. You don't +need to worry about whether the table already exists or not, since dataset will create it automatically:: + + # get a reference to the table 'person' + table = db['person'] + +Now storing data in a table is a matter of a single function call. Just pass a `dict`_ to *insert*. Note +that you don't need to create the columns *name* and *age* – dataset will do this automatically:: + + # Insert a new record. + table.insert(dict(name='John Doe', age=46)) + + # dataset will create "missing" columns any time you insert a dict with an unknown key + table.insert(dict(name='Jane Doe', age=37, gender='female')) + + # If you need to insert many items at once, you can speed up things by using insert_many: + table.insert_many(list_of_persons) + +.. _dict: http://docs.python.org/2/library/stdtypes.html#dict + +Updating existing entries is easy, too:: + + table.update(dict(name='John Doe', age=47), ['name']) + +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')