From f33a0a63a7442f0b665320ac3e2eb55de315f1f7 Mon Sep 17 00:00:00 2001
From: Russ Garrett <russ@garrett.co.uk>
Date: Sun, 28 Apr 2019 12:46:48 +0100
Subject: [PATCH] Add inspect and prepare_sanic hooks

This adds two new plugin hooks:

The `inspect` hook allows plugins to add data to the inspect
dictionary.

The `prepare_sanic` hook allows plugins to hook into the web
router. I've attached a warning to this hook in the docs in light
of #272 but I want this hook now...

On quick inspection, I don't think it's worthwhile to try and make
this hook independent of the web framework (but it looks like Starlette
would make the hook implementation a bit nicer).

Ref #14
---
 datasette/app.py       |  3 +++
 datasette/hookspecs.py | 10 +++++++++
 docs/plugins.rst       | 51 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 64 insertions(+)

diff --git a/datasette/app.py b/datasette/app.py
index 793bc931eb..5b3494b47f 100644
--- a/datasette/app.py
+++ b/datasette/app.py
@@ -443,6 +443,8 @@ def inspect(self):
                             "views": inspect_views(conn),
                             "tables": inspect_tables(conn, (self.metadata("databases") or {}).get(name, {}))
                         }
+                        for result in pm.hook.inspect(database=name, conn=conn, datasette=self):
+                            self._inspect[name].update(result)
                 except sqlite3.OperationalError as e:
                     if (e.args[0] == 'no such module: VirtualSpatialIndex'):
                         raise click.UsageError(
@@ -716,6 +718,7 @@ async def handle_request(self, request, write_callback, stream_callback):
             RowView.as_view(self),
             r"/<db_name:[^/]+>/<table:[^/]+?>/<pk_path:[^/]+?><as_format:(\.jsono?)?$>",
         )
+        pm.hook.prepare_sanic(app=app, datasette=self)
         self.register_custom_units()
 
         # On 404 with a trailing slash redirect to path without that slash:
diff --git a/datasette/hookspecs.py b/datasette/hookspecs.py
index 6db9534457..886e3be1d8 100644
--- a/datasette/hookspecs.py
+++ b/datasette/hookspecs.py
@@ -30,6 +30,16 @@ def extra_body_script(template, database, table, datasette):
     "Extra JavaScript code to be included in <script> at bottom of body"
 
 
+@hookspec
+def inspect(database, conn):
+    "Inspect the database for plugin-specific information"
+
+
+@hookspec
+def prepare_sanic(app, datasette):
+    "Add additional web routes"
+
+
 @hookspec
 def publish_subcommand(publish):
     "Subcommands for 'datasette publish'"
diff --git a/docs/plugins.rst b/docs/plugins.rst
index 984e5c95fa..10036fd8f4 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -326,6 +326,27 @@ You can now use this filter in your custom templates like so::
 
     Table name: {{ table|uppercase }}
 
+.. _plugin_hook_prepare_sanic:
+
+prepare_sanic(app, datasette)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Called at startup to allow plugins to add additional HTTP endpoints to Sanic's web router.
+
+``app`` - Sanic app instance
+    The instance of the Sanic app.
+
+``datasette`` - Datasette instance
+    You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
+
+In this hook, you can add new routes using ``app.add_route``::
+
+        app.add_route(lambda x: text("Hello World"), r"/test/")
+
+**Warning**: This hook depends on Sanic - an implementation detail which `may change in a later version of Datasette <https://github.com/simonw/datasette/issues/272>`_.
+
+The return value is ignored.
+
 .. _plugin_hook_extra_css_urls:
 
 extra_css_urls(template, database, table, datasette)
@@ -551,3 +572,33 @@ The ``template``, ``database`` and ``table`` options can be used to return diffe
 The ``datasette`` instance is provided primarily so that you can consult any plugin configuration options that may have been set, using the ``datasette.plugin_config(plugin_name)`` method documented above.
 
 The string that you return from this function will be treated as "safe" for inclusion in a ``<script>`` block directly in the page, so it is up to you to apply any necessary escaping.
+
+.. _plugin_hook_inspect:
+
+inspect(database, conn, datasette)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Called at inspect time to allow the plugin to inspect the database and save the inspected data. 
+
+``database`` - string
+    The name of the database being inspected.
+
+``conn`` - Sqlite connection
+    A sqlite connection object for the database.
+
+``datasette`` - Datasette instance
+    You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
+
+This is useful if you need to cache any information about the database which might be expensive to collect on every page load.
+
+Return a dictionary which is merged into the inspected data. You should store inspected data within this using a plugin-specific key:: 
+
+        return {
+                "myplugin": {<data>}
+        }
+
+The inspected data dictionary can be retrieved later with::
+
+        my_data = datasette.inspect()["myplugin"]
+
+