Add SpatiaLite helpers to CLI (#407)

* Add SpatiaLite CLI helpers
* Add docs for spaitalite helpers
* Fix flake8 issues and add more detail on spatial types
* Run cog and add some help text.
* Use SpatiaLite when calculating coverage, refs #407

Co-authored-by: Simon Willison <swillison@gmail.com>

docs/cli-reference.rst

@@ -772,8 +772,10 @@ See :ref:`cli_create_database`.
           sqlite-utils create-database trees.db
 
     Options:
-      --enable-wal  Enable WAL mode on the created database
-      -h, --help    Show this message and exit.
+      --enable-wal           Enable WAL mode on the created database
+      --init-spatialite      Enable SpatiaLite on the created database
+      --load-extension TEXT  SQLite extensions to load
+      -h, --help             Show this message and exit.
 
 
 create-table
@@ -1226,4 +1228,49 @@ See :ref:`cli_drop_view`.
       -h, --help             Show this message and exit.
 
 
+add-geometry-column
+===================
+
+::
+
+    Usage: sqlite-utils add-geometry-column [OPTIONS] DB_PATH TABLE COLUMN_NAME
+
+      Add a SpatiaLite geometry column to an existing table. Requires SpatiaLite
+      extension.
+
+      By default, this command will try to load the SpatiaLite extension from usual
+      paths. To load it from a specific path, use --load-extension.
+
+    Options:
+      -t, --type [POINT|LINESTRING|POLYGON|MULTIPOINT|MULTILINESTRING|MULTIPOLYGON|GEOMETRYCOLLECTION|GEOMETRY]
+                                      Specify a geometry type for this column.
+                                      [default: GEOMETRY]
+      --srid INTEGER                  Spatial Reference ID. See
+                                      https://spatialreference.org for details on
+                                      specific projections.  [default: 4326]
+      --dimensions TEXT               Coordinate dimensions. Use XYZ for three-
+                                      dimensional geometries.
+      --not-null                      Add a NOT NULL constraint.
+      --load-extension TEXT           SQLite extensions to load
+      -h, --help                      Show this message and exit.
+
+
+create-spatial-index
+====================
+
+::
+
+    Usage: sqlite-utils create-spatial-index [OPTIONS] DB_PATH TABLE COLUMN_NAME
+
+      Create a spatial index on a SpatiaLite geometry column. The table and geometry
+      column must already exist before trying to add a spatial index.
+
+      By default, this command will try to load the SpatiaLite extension from usual
+      paths. To load it from a specific path, use --load-extension.
+
+    Options:
+      --load-extension TEXT  SQLite extensions to load
+      -h, --help             Show this message and exit.
+
+
 .. [[[end]]]

docs/cli.rst

@@ -724,6 +724,14 @@ To enable :ref:`cli_wal` on the newly created database add the ``--enable-wal``
 
     $ sqlite-utils create-database empty.db --enable-wal
 
+To enable SpatiaLite metadata on a newly created database, add the ``--init-spatialite`` flag::
+
+    $ sqlite-utils create-database empty.db --init-spatialite
+
+That will look for SpatiaLite in a set of predictable locations. To load it from somewhere else, use the ``--load-extension`` option::
+
+    $ sqlite-utils create-database empty.db --init-spatialite --load-extension /path/to/spatialite.so
+
 .. _cli_inserting_data:
 
 Inserting JSON data
@@ -1975,3 +1983,34 @@ Since `SpatiaLite <https://www.gaia-gis.it/fossil/libspatialite/index>`__ is com
 
     $ sqlite-utils memory "select spatialite_version()" --load-extension=spatialite
     [{"spatialite_version()": "4.3.0a"}]
+
+
+SpatiaLite helpers
+==================
+
+`SpatiaLite <https://www.gaia-gis.it/fossil/libspatialite/home>`_ adds geographic capability to SQLite (similar to how PostGIS builds on PostgreSQL). The `SpatiaLite cookbook <http://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/index.html>`_ is a good resource for learning what's possible with it.
+
+You can convert an existing table to a geographic table by adding a geometry column, use the `sqlite-utils add-geometry-column` command::
+
+    $ sqlite-utils add-geometry-column spatial.db locations geometry --type POLYGON --srid 4326
+
+The table (``locations`` in the example above) must already exist before adding a geometry column. Use ``sqlite-utils create-table`` first, then ``add-geometry-column``.
+
+Use the ``--type`` option to specify a geometry type. By default, ``add-geometry-column`` uses a generic ``GEOMETRY``, which will work with any type, though it may not be supported by some desktop GIS applications. 
+
+Eight (case-insensitive) types are allowed:
+
+ * POINT
+ * LINESTRING
+ * POLYGON
+ * MULTIPOINT
+ * MULTILINESTRING
+ * MULTIPOLYGON
+ * GEOMETRYCOLLECTION
+ * GEOMETRY
+
+Once you have a geometry column, you can speed up bounding box queries by adding a spatial index::
+
+    $ sqlite-utils create-spatial-index spatial.db locations geometry
+
+See the `SpatiaLite Cookbook <http://www.gaia-gis.it/gaia-sins/spatialite-cookbook-5/cookbook_topics.03.html#topic_Wonderful_RTree_Spatial_Index>`_ for examples of how to use a spatial index.