From 75230128f2a3c1e52993f3bd342ff34aa3bf91ea Mon Sep 17 00:00:00 2001 From: Friedrich Lindenberg Date: Wed, 3 Apr 2013 22:47:28 +0200 Subject: [PATCH] Copy edit some of the docs. --- docs/index.rst | 9 +++---- docs/quickstart.rst | 58 +++++++++++++++++++++++++++++++++------------ 2 files changed, 48 insertions(+), 19 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 256db38..86c1c64 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,11 +10,12 @@ dataset: databases for lazy people :hidden: -Although managing data in relational database has plenty of benefits, we find them rarely being used in the typical day-to-day work with small to medium scale datasets. But why is that? Why do we see an awful lot of data stored in static files in CSV or JSON format? +Although managing data in relational database has plenty of benefits, they're rarely used in day-to-day work with small to medium scale datasets. But why is that? Why do we see an awful lot of data stored in static files in CSV or JSON format, even though they are hard +to query and update incrementally? -The answer is that **programmers are lazy**, and thus they tend to prefer the easiest solution they find. And in **Python**, a database wasn't the simplest solution for storing a bunch of structured data. This is what **dataset** is going to change! +The answer is that **programmers are lazy**, and thus they tend to prefer the easiest solution they find. And in **Python**, a database isn't the simplest solution for storing a bunch of structured data. This is what **dataset** is going to change! -In short, dataset combines the straightforwardness of NoSQL interfaces with the full power and flexibility of relational databases. It makes database management as simple as reading and writing JSON files. +In short, dataset combines the straightforwardness of JSON files or a NoSQL store with the full power and flexibility of relational databases. :: @@ -57,4 +58,4 @@ Contributors ``dataset`` is written and maintained by `Friedrich Lindenberg `_ and `Gregor Aisch `_. Its code is largely based on the preceding libraries `sqlaload `_ and `datafreeze `_. And of course, we're standing on the `shoulders of giants `_. -Our cute little `naked mole rat `_ was drawn by `Johannes Koch `_. \ No newline at end of file +Our cute little `naked mole rat `_ was drawn by `Johannes Koch `_. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 3087b6b..2ff99e0 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -12,7 +12,7 @@ At first you need to import the dataset package :) :: import dataset -To connect to a database you need to identify it by its `URL `_, which basically is a string of the form ``"dialect://user:password@host/dbname"``. Here are a few common examples:: +To connect to a database you need to identify it by its `URL `_, which basically is a string of the form ``"dialect://user:password@host/dbname"``. Here are a few examples for different database backends:: # connecting to a SQLite database db = dataset.connect('sqlite:///mydatabase.db') @@ -23,16 +23,25 @@ To connect to a database you need to identify it by its `URL >> print db.tables set([u'user', u'action']) @@ -74,12 +86,13 @@ Now let's get some real data out of the table:: users = db['user'].all() -If we simply want to iterate over all rows in a table, we can ommit :py:meth:`all() `:: +If we simply want to iterate over all rows in a table, we can omit :py:meth:`all() `:: for user in db['user']: print user['email'] -We can search for specific entries using :py:meth:`find() ` and :py:meth:`find_one() `:: +We can search for specific entries using :py:meth:`find() ` and +:py:meth:`find_one() `:: # All users from China users = table.find(country='China') @@ -87,7 +100,8 @@ We can search for specific entries using :py:meth:`find() ` # Get a specific user john = table.find_one(name='John Doe') -Using :py:meth:`distinct() ` we can grab a set of rows with unique values in one or more columns:: +Using :py:meth:`distinct() ` we can grab a set of rows +with unique values in one or more columns:: # Get one user per country db['user'].distinct('country') @@ -96,29 +110,43 @@ Using :py:meth:`distinct() ` we can grab a set of rows Running custom SQL queries -------------------------- -Of course the main reason you're using a database is that you want to use the full power of SQL queries. Here's how you run them with ``dataset``:: +Of course the main reason you're using a database is that you want to +use the full power of SQL queries. Here's how you run them with ``dataset``:: result = db.query('SELECT country, COUNT(*) c FROM user GROUP BY country') for row in result: print row['country'], row['c'] +The :py:meth:`query() ` method can also be used to +access the underlying SQLAlchemy core API, which allows for the +programmatic construction of more complex queries:: + + table = db['users'].table + statement = table.select(table.c.name.like('%Snoopy%')) + result = db.query(statement) + Exporting data -------------- -While playing around with our database in Python is a nice thing, sometimes we want to use the data –or parts of it– elsewhere, say in an interactive web application. Therefor ``dataset`` supports serializing rows of data into static files such as JSON using the :py:meth:`freeze() ` function:: +While playing around with our database in Python is a nice thing, they are +sometimes just a processing stage until we go on to use it in another +place, say in an interactive web application. To make this seamless, +``dataset`` supports serializing rows of data into static JSON and CSV files +such using the :py:meth:`freeze() ` function:: # export all users into a single JSON result = db['users'].all() - dataset.freeze(result, 'users.json') + dataset.freeze(result, 'users.json', format='json') You can create one file per row by setting ``mode`` to "item":: # export one JSON file per user - dataset.freeze(result, 'users/{{ id }}.json', mode='item') + dataset.freeze(result, 'users/{{ id }}.json', format='json', mode='item') -Since this is a common operation we made it available via command line utility ``datafreeze``. Read more about the `freezefile markup `_. +Since this is a common operation we made it available via command line +utility ``datafreeze``. Read more about the `freezefile markup `_. .. code-block:: bash