diff --git a/dataset/persistence/table.py b/dataset/persistence/table.py index d7c0901..6de7de1 100644 --- a/dataset/persistence/table.py +++ b/dataset/persistence/table.py @@ -152,18 +152,19 @@ class Table(object): else: return self.table.c[order_by].asc() - def find(self, _limit=None, _step=5000, _offset=0, + def find(self, _limit=None, _offset=0, _step=5000, order_by='id', **filter): - """Performs a simple search on the table. + """Performs a simple search on the table. Simply pass keyword arguments as ``filter``. :: results = table.find(country='France') - # combining multiple conditions (AND) results = table.find(country='France', year=1980) + + Using # just return the first 10 rows results = table.find(country='France', _limit=10) - You can sort the results by single or multiple columns. For descending order - please append a minus sign to the column name:: + 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) diff --git a/docs/_themes/kr/autotoc.html b/docs/_themes/kr/autotoc.html new file mode 100644 index 0000000..3e1ab00 --- /dev/null +++ b/docs/_themes/kr/autotoc.html @@ -0,0 +1,25 @@ +

{{ _('Table Of Contents') }}

+ + + + + + diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html index c7b9264..d0e435c 100755 --- a/docs/_themes/kr/layout.html +++ b/docs/_themes/kr/layout.html @@ -8,9 +8,6 @@ {% endblock %} -{% block sidebarlogo %} - -{% endblock %} {% block sidebar2 %} {{ sidebar() }} @@ -27,6 +24,4 @@ Fork me on GitHub - - {%- endblock %} diff --git a/docs/_themes/kr/sidebarlogo.html b/docs/_themes/kr/sidebarlogo.html new file mode 100644 index 0000000..e8f615d --- /dev/null +++ b/docs/_themes/kr/sidebarlogo.html @@ -0,0 +1,3 @@ +
+ + \ No newline at end of file diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t index 40b6da6..c53de79 100755 --- a/docs/_themes/kr/static/flasky.css_t +++ b/docs/_themes/kr/static/flasky.css_t @@ -103,7 +103,7 @@ div.sphinxsidebar h4 { color: #000; font-size: 24px; font-weight: normal; - margin: 0 0 5px 0; + margin: 30px 0 5px 0; padding: 0; } @@ -128,7 +128,7 @@ div.sphinxsidebar p { } div.sphinxsidebar ul { - margin: 10px 0 30px; + margin: 10px 0px; padding: 0; color: #000; } diff --git a/docs/api.rst b/docs/api.rst index 56d428e..01dd01e 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -2,15 +2,8 @@ API documentation ================= - -.. toctree:: - :maxdepth: 2 - - - .. autofunction:: dataset.connect - Database -------- @@ -18,13 +11,9 @@ 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: diff --git a/docs/conf.py b/docs/conf.py index c299880..77e5223 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,7 +100,7 @@ html_theme = 'kr' # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { -# 'codebgcolor': '' +# 'stickysidebar': "true" # } # Add any paths that contain custom themes here, relative to this directory. @@ -136,7 +136,11 @@ html_static_path = ['_static'] #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + 'index': ['sidebarlogo.html', 'sourcelink.html', 'searchbox.html'], + 'api': ['sidebarlogo.html', 'autotoc.html', 'sourcelink.html', 'searchbox.html'], + '**': ['sidebarlogo.html', 'localtoc.html', 'sourcelink.html', 'searchbox.html'] +} # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/docs/index.rst b/docs/index.rst index 478b0d7..ed29ca7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,22 +3,37 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -dataset: databases for busy nerds -================================= +dataset: databases for lazy people +================================== -Getting the databases out of your data's way:: +.. toctree:: + :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? + +Because **good programmers are lazy**, and thus they tend to prefer the easiest solution they find. And managing data in a databases simply wasn't the simplest solution to store a bunch of structured data. This is where ``dataset`` steps in! + +Dataset is here to **take the pain out of databases**. It makes reading and writing data in databases as simple as reading and writing JSON files. + +In short, :: import dataset - db = dataset.connect('sqlite:///weather.db') - db['temperature'].find() + db = dataset.connect('sqlite:///database.db') + db['sometable'].insert(dict(name='John Doe', age=37)) + db['sometable'].insert(dict(name='Jane Doe', age=34, gender='female')) + + +Now look at `similar code, without dataset `_. + Features -------- -* **Automatic schema**. If a table or column is written that does not +* **Automatic schema**: If a table or column is written that does not exist in the database, it will be created automatically. -* **Upserts**. Records are either created or updated, depdending on +* **Upserts**: Records are either created or updated, depdending on whether an existing version can be found. * **Query helpers** for simple queries such as all rows in a table or all distinct values across a set of columns. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index c9aba63..ba9879e 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -5,36 +5,34 @@ Quickstart Hi, welcome to the five-minute quick-start tutorial. +Connecting to a database +------------------------ + At first you need to import the dataset 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:: +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:: # connecting to a SQLite database - db = dataset.connect('sqlite:///factbook.db') + db = dataset.connect('sqlite:///mydatabase.db') - # connecting to a MySQL database + # connecting to a MySQL database with user and password 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:: +To store some data you need to get a reference to a table. 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:: +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))