table.count property, plus made a start on table documentation

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
 

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"]
+    <sqlite_utils.db.Table at 0x10f5960b8>
+    >>> 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')]

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:

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
+    ]