.add_database() and .remove_database() methods, refs #671

Also made a start on the Datasette class documentation, refs #576

datasette/app.py

@@ -180,7 +180,7 @@ def __init__(
             db = Database(self, path, is_mutable=is_mutable, is_memory=is_memory)
             if db.name in self.databases:
                 raise Exception("Multiple files with same stem: {}".format(db.name))
-            self.databases[db.name] = db
+            self.add_database(db.name, db)
         self.cache_headers = cache_headers
         self.cors = cors
         self._metadata = metadata or {}
@@ -210,6 +210,12 @@ def __init__(
                     # Plugin already registered
                     pass
 
+    def add_database(self, name, db):
+        self.databases[name] = db
+
+    def remove_database(self, name):
+        self.databases.pop(name)
+
     async def run_sanity_checks(self):
         # Only one check right now, for Spatialite
         for database_name, database in self.databases.items():

docs/datasette.rst

@@ -0,0 +1,43 @@
+.. _datasette:
+
+Datasette class
+===============
+
+Many of Datasette's :ref:`plugin_hooks` pass a ``datasette`` object to the plugin as an argument.
+
+This object is an instance of the ``Datasette`` class. That class currently has a large number of methods on it, but it should not be considered stable (at least until Datasette 1.0) with the exception of the methods that are documented on this page.
+
+.add_database(name, db)
+-----------------------
+
+The ``datasette.add_database(name, db)`` method lets you add a new database to the current Datasette instance. This database will then be served at URL path that matches the ``name`` parameter, e.g. ``/mynewdb/``.
+
+The ``db`` parameter should be an instance of the ``datasette.database.Database`` class. For example:
+
+.. code-block:: python
+
+    from datasette.database import Database
+
+    datasette.add_database("my-new-database", Database(
+        datasette,
+        path="path/to/my-new-database.db",
+        is_mutable=True
+    ))
+
+This will add a mutable database from the provided file path.
+
+The ``Database()`` constructor takes four arguments: the first is the ``datasette`` instance you are attaching to, the second is a ``path=``, then ``is_mutable`` and ``is_memory`` are both optional arguments.
+
+Use ``is_mutable`` if it is possible that updates will be made to that database - otherwise Datasette will open it in immutable mode and any changes could cause undesired behavior.
+
+Use ``is_memory`` if the connection is to an in-memory SQLite database.
+
+.remove_database(name)
+----------------------
+
+This removes a database that has been previously added. ``name=`` is the unique name of that database, also used in the URL for it.
+
+.plugin_config(plugin_name, database=None, table=None)
+------------------------------------------------------
+
+This method lets you read plugin configuration values that were set in ``metadata.json``. See :ref:`plugins_plugin_config` for full details.

docs/index.rst

@@ -34,6 +34,7 @@ Contents
    introspection
    custom_templates
    plugins
+   datasette
    contributing
    changelog
 

docs/plugins.rst

@@ -278,6 +278,8 @@ If you are publishing your data using the :ref:`datasette publish <cli_publish>`
         --plugin-secret datasette-auth-github client_id your_client_id \
         --plugin-secret datasette-auth-github client_secret your_client_secret
 
+.. _plugins_plugin_config:
+
 Writing plugins that accept configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -320,6 +322,8 @@ The plugin configuration could also be set at the top level of ``metadata.json``
 
 Now that ``datasette-cluster-map`` plugin configuration will apply to every table in every database.
 
+.. _plugin_hooks:
+
 Plugin hooks
 ------------
 
@@ -399,7 +403,7 @@ extra_css_urls(template, database, table, datasette)
 ``table`` - string or None
     The name of the table
 
-``datasette`` - Datasette instance
+``datasette`` - :ref:`datasette`
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
 
 Return a list of extra CSS URLs that should be included on the page. These can
@@ -535,7 +539,7 @@ Lets you customize the display of values within table cells in the HTML table vi
 ``database`` - string
     The name of the database
 
-``datasette`` - Datasette instance
+``datasette`` - :ref:`datasette`
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
 
 If your hook returns ``None``, it will be ignored. Use this to indicate that your hook is not able to custom render this particular value.
@@ -605,7 +609,7 @@ Extra JavaScript to be added to a ``<script>`` block at the end of the ``<body>`
 ``view_name`` - string
     The name of the view being displayed. (`index`, `database`, `table`, and `row` are the most important ones.)
 
-``datasette`` - Datasette instance
+``datasette`` - :ref:`datasette`
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
 
 The ``template``, ``database`` and ``table`` options can be used to return different code depending on which template is being rendered and which database or table are being processed.
@@ -637,7 +641,7 @@ Extra template variables that should be made available in the rendered template
 ``request`` - object
     The current HTTP request object. ``request.scope`` provides access to the ASGI scope.
 
-``datasette`` - Datasette instance
+``datasette`` - :ref:`datasette`
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
 
 This hook can return one of three different types:
@@ -682,7 +686,7 @@ You can then use the new function in a template like so::
 register_output_renderer(datasette)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``datasette`` - Datasette instance
+``datasette`` - :ref:`datasette`
     You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``
 
 Allows the plugin to register a new output renderer, to output data in a custom format. The hook function should return a dictionary, or a list of dictionaries, which contain the file extension you want to handle and a callback function: