Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documented internals API for use in plugins #576

Closed
simonw opened this issue Sep 23, 2019 · 10 comments
Closed

Documented internals API for use in plugins #576

simonw opened this issue Sep 23, 2019 · 10 comments

Comments

@simonw
Copy link
Owner

@simonw simonw commented Sep 23, 2019

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
Copy link
Owner Author

@simonw simonw commented Jan 6, 2020

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

simonw added a commit that referenced this issue Feb 14, 2020
Also made a start on the Datasette class documentation, refs #576
@simonw
Copy link
Owner Author

@simonw simonw commented Feb 14, 2020

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 added a commit that referenced this issue Feb 14, 2020
Also improved parameter documentation for other methods, refs #576
@simonw
Copy link
Owner Author

@simonw simonw commented May 30, 2020

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
Copy link
Owner Author

@simonw simonw commented May 30, 2020

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

@simonw
Copy link
Owner Author

@simonw simonw commented May 30, 2020

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
Copy link
Owner Author

@simonw simonw commented May 30, 2020

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

Pydoc__module_datasette_app

@simonw
Copy link
Owner Author

@simonw simonw commented May 30, 2020

__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
Copy link
Owner Author

@simonw simonw commented May 30, 2020

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 simonw changed the title Datasette class should provide documented API for use in plugins Documented internals API for use in plugins Jun 2, 2020
simonw added a commit that referenced this issue Jun 12, 2020
@simonw
Copy link
Owner Author

@simonw simonw commented Jan 5, 2021

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

@simonw simonw closed this as completed Jan 5, 2021
@simonw
Copy link
Owner Author

@simonw simonw commented Jan 5, 2021

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant