diff --git a/docs/index.rst b/docs/index.rst index ea975fc..ff2f9b3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,15 @@ This library aims to make creating a SQLite database from a collection of data a It is not intended to be a full ORM: the focus is utility helpers to make creating the initial database and populating it with data as productive as possible. -In lieu of detailed documentation (coming soon), enjoy an example instead: +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + table + +While the documentation is being constructed, enjoy an example instead: .. code-block:: python diff --git a/docs/table.rst b/docs/table.rst new file mode 100644 index 0000000..54ae523 --- /dev/null +++ b/docs/table.rst @@ -0,0 +1,37 @@ +======= + Table +======= + +Tables are accessed using the indexing operator, like so: + +.. code-block:: python + + from sqlite_utils.db import Database + import sqlite3 + + database = Database(sqlite3.connect("my_database.db")) + table = database["my_table"] + +If the table does not yet exist, it will be created the first time you attempt to insert or upsert data into it. + +Introspection +============= + +If you have loaded an existing table, you can use introspection to find out more about it:: + + >>> db["PlantType"] + + >>> db["PlantType"].count + 3 + >>> db["PlantType"].columns + [Column(cid=0, name='id', type='INTEGER', notnull=0, default_value=None, is_pk=1), + Column(cid=1, name='value', type='TEXT', notnull=0, default_value=None, is_pk=0)] + >>> db["Street_Tree_List"].count + 189144 + >>> db["Street_Tree_List"].foreign_keys + [ForeignKey(table='Street_Tree_List', column='qLegalStatus', other_table='qLegalStatus', other_column='id'), + ForeignKey(table='Street_Tree_List', column='qCareAssistant', other_table='qCareAssistant', other_column='id'), + ForeignKey(table='Street_Tree_List', column='qSiteInfo', other_table='qSiteInfo', other_column='id'), + ForeignKey(table='Street_Tree_List', column='qSpecies', other_table='qSpecies', other_column='id'), + ForeignKey(table='Street_Tree_List', column='qCaretaker', other_table='qCaretaker', other_column='id'), + ForeignKey(table='Street_Tree_List', column='PlantType', other_table='PlantType', other_column='id')] diff --git a/sqlite_utils/db.py b/sqlite_utils/db.py index 4e7fbf1..e3e83a7 100644 --- a/sqlite_utils/db.py +++ b/sqlite_utils/db.py @@ -71,6 +71,12 @@ class Table: self.name = name self.exists = self.name in self.db.tables + @property + def count(self): + return self.db.conn.execute( + "select count(*) from [{}]".format(self.name) + ).fetchone()[0] + @property def columns(self): if not self.exists: diff --git a/tests/test_introspect.py b/tests/test_introspect.py new file mode 100644 index 0000000..6ad178a --- /dev/null +++ b/tests/test_introspect.py @@ -0,0 +1,28 @@ +from sqlite_utils import db +import sqlite3 +import pytest + + +@pytest.fixture +def existing_db(): + database = db.Database(sqlite3.connect(":memory:")) + database.conn.executescript( + """ + CREATE TABLE foo (text TEXT); + INSERT INTO foo (text) values ("one"); + INSERT INTO foo (text) values ("two"); + INSERT INTO foo (text) values ("three"); + """ + ) + return database + + +def test_count(existing_db): + assert 3 == existing_db["foo"].count + + +def test_columns(existing_db): + table = existing_db["foo"] + assert [{"name": "text", "type": "TEXT"}] == [ + {"name": col.name, "type": col.type} for col in table.columns + ]