Added datasette.get_database() method

Refs #576

datasette/app.py

@@ -281,6 +281,11 @@ def __init__(
 
         self.register_renderers()
 
+    def get_database(self, name=None):
+        if name is None:
+            return next(iter(self.databases.values()))
+        return self.databases[name]
+
     def add_database(self, name, db):
         self.databases[name] = db
 

docs/internals.rst

@@ -44,6 +44,16 @@ This method lets you read plugin configuration values that were set in ``metadat
 
 Renders a `Jinja template <https://jinja.palletsprojects.com/en/2.11.x/>`__ using Datasette's preconfigured instance of Jinja and returns the resulting string. The template will have access to Datasette's default template functions and any functions that have been made available by other plugins.
 
+.. _datasette_get_database:
+
+.get_database(name)
+-------------------
+
+``name`` - string, optional
+    The name of the database - optional.
+
+Returns the specified database object. Raises a ``KeyError`` if the database does not exist. Call this method without an argument to return the first connected database.
+
 .. _datasette_add_database:
 
 .add_database(name, db)

docs/plugins.rst

@@ -811,7 +811,7 @@ Here is a more complex example:
 .. code-block:: python
 
     async def render_demo(datasette, columns, rows):
-        db = next(iter(datasette.databases.values()))
+        db = datasette.get_database()
         result = await db.execute("select sqlite_version()")
         first_row = " | ".join(columns)
         lines = [first_row]

tests/test_database.py

@@ -1,3 +1,6 @@
+"""
+Tests for the datasette.database.Database class
+"""
 from datasette.database import Results, MultipleValues
 from datasette.utils import sqlite3
 from .fixtures import app_client

tests/test_internals_datasette.py

@@ -0,0 +1,23 @@
+"""
+Tests for the datasette.app.Datasette class
+"""
+from .fixtures import app_client
+import pytest
+
+
+@pytest.fixture
+def datasette(app_client):
+    return app_client.ds
+
+
+def test_get_database(datasette):
+    db = datasette.get_database("fixtures")
+    assert "fixtures" == db.name
+    with pytest.raises(KeyError):
+        datasette.get_database("missing")
+
+
+def test_get_database_no_argument(datasette):
+    # Returns the first available database:
+    db = datasette.get_database()
+    assert "fixtures" == db.name