From e0b66510aba1fe5f59af4298387b572e99c067d4 Mon Sep 17 00:00:00 2001 From: Gregor Aisch Date: Wed, 3 Apr 2013 00:51:33 +0200 Subject: [PATCH] removed sphinx warnings --- dataset/__init__.py | 4 ++- dataset/persistence/database.py | 30 ++++++++++------ dataset/persistence/table.py | 47 ++++++++++++++++++++------ docs/_themes/{README.rst => README.md} | 6 ++-- docs/api.rst | 9 ++--- docs/quickstart.rst | 6 ++-- 6 files changed, 69 insertions(+), 33 deletions(-) rename docs/_themes/{README.rst => README.md} (83%) diff --git a/dataset/__init__.py b/dataset/__init__.py index 83b0b0c..74d6bc1 100644 --- a/dataset/__init__.py +++ b/dataset/__init__.py @@ -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 `. :: + db = dataset.connect('sqlite:///factbook.db') .. _SQLAlchemy Engine URL: http://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine diff --git a/dataset/persistence/database.py b/dataset/persistence/database.py index 8dbc242..8baa601 100644 --- a/dataset/persistence/database.py +++ b/dataset/persistence/database.py @@ -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 ` 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 ` object. Returns a :py:class:`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 ` 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 `_. 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)) diff --git a/dataset/persistence/table.py b/dataset/persistence/table.py index 6de7de1..5b5bb78 100644 --- a/dataset/persistence/table.py +++ b/dataset/persistence/table.py @@ -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 `. """ + :py:class:`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() ` but returns only one result. + """ + Works just like :py:meth:`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 `_. :: + # 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() diff --git a/docs/_themes/README.rst b/docs/_themes/README.md similarity index 83% rename from docs/_themes/README.rst rename to docs/_themes/README.md index dd8d7c0..91f0d6d 100755 --- a/docs/_themes/README.rst +++ b/docs/_themes/README.md @@ -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: diff --git a/docs/api.rst b/docs/api.rst index 01dd01e..bf4b64b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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: diff --git a/docs/quickstart.rst b/docs/quickstart.rst index c1ca514..1afd111 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -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 ------------------