removed sphinx warnings

Browse Source
This commit is contained in:
Gregor Aisch 2013-04-03 00:51:33 +02:00
parent d240a45e77
commit e0b66510ab
6 changed files with 69 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
dataset/__init__.py
View File

@ -8,9 +8,11 @@ from dataset.persistence.table import Table
def connect(url):
""" Opens a new connection to a database. *url* can be any valid `SQLAlchemy engine URL`_. Returns
"""
Opens a new connection to a database. *url* can be any valid `SQLAlchemy engine URL`_. Returns
an instance of :py:class:`Database <dataset.Database>`.
::
db = dataset.connect('sqlite:///factbook.db')
.. _SQLAlchemy Engine URL: http://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine

30
dataset/persistence/database.py
View File

@ -36,12 +36,13 @@ class Database(object):
return set(self.metadata.tables.keys() + self._tables.keys())
def create_table(self, table_name):
""" Creates a new table. The new table will automatically have
an `id` column, which is set to be an auto-incrementing integer
as the primary key of the table.
"""
Creates a new table. The new table will automatically have an `id` column, which is
set to be an auto-incrementing integer as the primary key of the table.
Returns a :py:class:`Table <dataset.Table>` instance.
::
table = db.create_table('population')
"""
with self.lock:
@ -54,14 +55,17 @@ class Database(object):
return Table(self, table)
def load_table(self, table_name):
""" Loads a table. This will fail if the tables does not already
"""
Loads a table. This will fail if the tables does not already
exist in the database. If the table exists, its columns will be
reflected and are available on the :py:class:`Table <dataset.Table>`
object.
Returns a :py:class:`Table <dataset.Table>` instance.
::
table = db.load_table('population')"""
table = db.load_table('population')
"""
with self.lock:
log.debug("Loading table: %s on %r" % (table_name, self))
table = SQLATable(table_name, self.metadata, autoload=True)
@ -69,11 +73,13 @@ class Database(object):
return Table(self, table)
def get_table(self, table_name):
""" Smart wrapper around *load_table* and *create_table*. Either loads a table
"""
Smart wrapper around *load_table* and *create_table*. Either loads a table
or creates it if it doesn't exist yet.
Returns a :py:class:`Table <dataset.Table>` instance.
::
table = db.get_table('population')
# you can also use the short-hand syntax:
table = db['population']
@ -90,14 +96,16 @@ class Database(object):
return self.get_table(table_name)
def query(self, query):
""" Run a statement on the database directly, allowing for the
"""
Run a statement on the database directly, allowing for the
execution of arbitrary read/write queries. A query can either be
a plain text string, or a SQLAlchemy expression. The returned
a plain text string, or a `SQLAlchemy expression <http://docs.sqlalchemy.org/ru/latest/core/tutorial.html#selecting>`_. The returned
iterator will yield each result sequentially.
::
result = db.query('SELECT * FROM population WHERE population > 10000000')
for row in result:
print row
res = db.query('SELECT user, COUNT(*) c FROM photos GROUP BY user')
for row in res:
print row['user'], row['c']
"""
return resultiter(self.engine.execute(query))

47
dataset/persistence/table.py
View File

@ -17,20 +17,28 @@ class Table(object):
self.database = database
self.table = table
@property
def columns(self):
""" Get a listing of all columns that exist in the table. """
return set(self.table.columns.keys())
def drop(self):
""" Drop the table from the database, deleting both the schema
"""
Drop the table from the database, deleting both the schema
and all the contents within it.
Note: the object will be in an unusable state after using this
command and should not be used again. If you want to re-create
the table, make sure to get a fresh instance from the
:py:class:`Database <dataset.Database>`. """
:py:class:`Database <dataset.Database>`.
"""
with self.database.lock:
self.database.tables.pop(self.table.name, None)
self.table.drop(engine)
def insert(self, row, ensure=True, types={}):
""" Add a row (type: dict) by inserting it into the table.
"""
Add a row (type: dict) by inserting it into the table.
If ``ensure`` is set, any of the keys of the row are not
table columns, they will be created automatically.
@ -40,6 +48,7 @@ class Table(object):
guessed from the row's value, defaulting to a simple unicode
field.
::
data = dict(id=10, title='I am a banana!')
table.insert(data, ['id'])
"""
@ -48,11 +57,13 @@ class Table(object):
self.database.engine.execute(self.table.insert(row))
def update(self, row, keys, ensure=True, types={}):
""" Update a row in the table. The update is managed via
"""
Update a row in the table. The update is managed via
the set of column names stated in ``keys``: they will be
used as filters for the data to be updated, using the values
in ``row``.
::
# update all entries with id matching 10, setting their title columns
data = dict(id=10, title='I am a banana!')
table.update(data, ['id'])
@ -75,9 +86,11 @@ class Table(object):
return False
def upsert(self, row, keys, ensure=True, types={}):
"""An UPSERT is a smart combination of insert and update. If rows with matching ``keys`` exist
"""
An UPSERT is a smart combination of insert and update. If rows with matching ``keys`` exist
they will be updated, otherwise a new row is inserted in the table.
::
data = dict(id=10, title='I am a banana!')
table.upsert(data, ['id'])
"""
@ -88,8 +101,10 @@ class Table(object):
self.insert(row, ensure=ensure, types=types)
def delete(self, **filter):
"""Delete rows matching the ``filter`` arguments.
"""
Delete rows matching the ``filter`` arguments.
::
table.delete(year=2010)
"""
q = self._args_to_clause(filter)
@ -137,8 +152,10 @@ class Table(object):
return idx
def find_one(self, **filter):
"""Works just like :py:meth:`find() <dataset.Table.find>` but returns only one result.
"""
Works just like :py:meth:`find() <dataset.Table.find>` but returns only one result.
::
row = table.find_one(country='United States')
"""
res = list(self.find(_limit=1, **filter))
@ -154,17 +171,21 @@ class Table(object):
def find(self, _limit=None, _offset=0, _step=5000,
order_by='id', **filter):
"""Performs a simple search on the table. Simply pass keyword arguments as ``filter``.
"""
Performs a simple search on the table. Simply pass keyword arguments as ``filter``.
::
results = table.find(country='France')
results = table.find(country='France', year=1980)
Using
Using ``_limit``::
# just return the first 10 rows
results = table.find(country='France', _limit=10)
You can sort the results by single or multiple columns. Append a minus sign
to the column name for descending order::
# sort results by a column 'year'
results = table.find(country='France', order_by='year')
# return all rows sorted by multiple columns (by year in descending order)
@ -197,9 +218,11 @@ class Table(object):
return d.values().pop()
def distinct(self, *columns, **filter):
"""Returns all rows of a table, but removes rows in with duplicate values in ``columns`.
"""
Returns all rows of a table, but removes rows in with duplicate values in ``columns``.
Interally this creates a `DISTINCT statement <http://www.w3schools.com/sql/sql_distinct.asp>`_.
::
# returns only one row per year, ignoring the rest
table.distinct('year')
# works with multiple columns, too
@ -221,8 +244,10 @@ class Table(object):
return self.database.query(q)
def all(self):
"""Returns all rows of the table as simple dictionaries. This is simply a shortcut
"""
Returns all rows of the table as simple dictionaries. This is simply a shortcut
to *find()* called with no arguments.
::
rows = table.all()"""
return self.find()

6
docs/_themes/README.rst → docs/_themes/README.md vendored
View File

@ -6,14 +6,14 @@ his projects. It is a derivative of Mitsuhiko's themes for Flask and Flask relat
projects. To use this style in your Sphinx documentation, follow
this guide:
1. put this folder as _themes into your docs folder. Alternatively
1. put this folder as _themes into your docs folder. Alternatively
you can also use git submodules to check out the contents there.
2. add this to your conf.py: ::
2. add this to your conf.py:
sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'flask'
html_theme = 'kr'
The following themes exist:

9
docs/api.rst
View File

@ -8,12 +8,13 @@ Database
--------
.. autoclass:: dataset.Database
:members: get_table, create_table, load_table, query
:undoc-members:
:members: get_table, create_table, load_table, query, tables
:special-members:
Table
-----
.. autoclass:: dataset.Table
:members:
:undoc-members:
:members: columns, drop, insert, update, upsert, find, find_one, distinct, create_column, create_index, all
:special-members:

6
docs/quickstart.rst
View File

@ -74,9 +74,9 @@ 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 using dataset::
result = db.query('SELECT country, COUNT(*) cnt FROM population GROUP BY year')
for row in res:
print row.country, row.cnt
result = db.query('SELECT user, COUNT(*) c FROM photos GROUP BY user ORDER BY c DESC')
for row in result:
print row['user'], row['c']
Freezing your data
------------------