From 3ffb8f3b98252531d11897fd431711e9b8045ace Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Thu, 13 Feb 2020 17:25:27 -0800 Subject: [PATCH] .add_database() and .remove_database() methods, refs #671 Also made a start on the Datasette class documentation, refs #576 --- datasette/app.py | 8 +++++++- docs/datasette.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/plugins.rst | 14 +++++++++----- 4 files changed, 60 insertions(+), 6 deletions(-) create mode 100644 docs/datasette.rst diff --git a/datasette/app.py b/datasette/app.py index 4b09b7d17e..053646e61a 100644 --- a/datasette/app.py +++ b/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(): diff --git a/docs/datasette.rst b/docs/datasette.rst new file mode 100644 index 0000000000..eeaa4531de --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index c82f2ccd83..f977702d8b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,6 +34,7 @@ Contents introspection custom_templates plugins + datasette contributing changelog diff --git a/docs/plugins.rst b/docs/plugins.rst index 1ecc523852..3787150399 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -278,6 +278,8 @@ If you are publishing your data using the :ref:`datasette 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 ``