Documented internals API for use in plugins

[simonw]

Quite a few of the plugin hooks make a datasette”instance of the Datasette class available to the plugins, so that they can look up configuration settings and execute database queries.

This means it should provide a documented, stable API so that plugin authors can rely on it.

[simonw]

I wrote about this a bit here: https://simonwillison.net/2020/Jan/6/sitemap-xml/

[simonw]

OK, I've made a start on this now in 3ffb8f3 - still plenty more methods to document. More importantly that class has a LOT of junk methods on that no-one should ever call from a plugin, so I need to decide what to do about those.

https://datasette.readthedocs.io/en/latest/internals.html

[simonw]

I need to document the .databases property - both how to get access to specific databases and how to access the first/only database.

Idea: datasette.get_database(name) method (consistent with existing .add_database() and .remove_database() methods) - but name parameter is optional, returns first database if you omit that.

[simonw]

Need to document datasette.metadata() - see #780

[simonw]

There's a bunch of methods on that class which I could add a _ prefix to and leave undocumented. datasette.register_renderers() should be datasette._register_renderers() for example.

[simonw]

Here's the current Datasette class as introspected using the webserver run by pydoc -p 8000:

[simonw]

__init__(self, files, immutables=None, cache_headers=True, cors=False, inspect_data=None, metadata=None, sqlite_extensions=None, template_dir=None, plugins_dir=None, static_mounts=None, memory=False, config=None, version_note=None, config_dir=None)

Initialize self. See help(type(self)) for accurate signature.

absolute_url(self, request, path)

add_database(self, name, db)

app(self)

Returns an ASGI app function that serves the whole of [Datasette](http://localhost:8066/datasette.app.html#Datasette)

app_css_hash(self)

config(self, key)

config_dict(self)

connected_databases(self)

execute(self, db_name, sql, params=None, truncate=False, custom_time_limit=None, page_size=None, log_sql_errors=True)

expand_foreign_keys(self, database, table, column, values)

Returns dict mapping (column, value) -> label

get_canned_queries(self, database_name)

get_canned_query(self, database_name, query_name)

metadata(self, key=None, database=None, table=None, fallback=True)

Looks up metadata, cascading backwards from specified level.\ Returns None if metadata value is not found.

plugin_config(self, plugin_name, database=None, table=None, fallback=True)

Return config for plugin, falling back from specified database/table

plugins(self, show_all=False)

prepare_connection(self, conn, database)

register_custom_units(self)

Register any custom units defined in the metadata.json with Pint

register_renderers(self)

Register output renderers which output data in custom formats.

remove_database(self, name)

render_template(self, templates, context=None, request=None, view_name=None)

table_metadata(self, database, table)

Fetch table-specific metadata.

threads(self)

update_with_inherited_metadata(self, metadata)

versions(self)

[simonw]

I should also think about the class properties (as opposed to methods) that are setup in the Datasette constructor. Many of these should be private, some should be documented.

• cache_headers
• cors
• databases
• executor
• files
• immutables
• inspect_data
• jinja_env
• max_returned_rows
• page_size
• plugins_dir
• renderers
• sql_time_limit_ms
• sqlite_extensions
• sqlite_functions
• static_mounts
• template_dir
• version_note

[simonw]

I'm happy with how this has evolved, so I'm closing the issue.

[simonw]

See https://docs.datasette.io/en/stable/internals.html