Context base class to support documenting the context

[simonw]

This idea first came up here:

• Build HTML version of /content?sql=... #2112 (comment)

If datasette.render_template(...) takes an optional Context subclass as an alternative to a context dictionary, I could then use dataclasses to define the context made available to specific templates - which then gives me something I can use to help document what they are.

Also refs:

• Datasette 1.0 documented template context (maybe via API docs) #1510

[simonw]

This is pretty neat:

datasette/datasette/views/database.py

Lines 157 to 206 in 2f9038a

	@dataclass
	class QueryContext:
	database: str = field(metadata={"help": "The name of the database being queried"})
	query: dict = field(
	metadata={"help": "The SQL query object containing the `sql` string"}
	)
	canned_query: str = field(
	metadata={"help": "The name of the canned query if this is a canned query"}
	)
	private: bool = field(
	metadata={"help": "Boolean indicating if this is a private database"}
	)
	urls: dict = field(
	metadata={"help": "Object containing URL helpers like `database()`"}
	)
	canned_write: bool = field(
	metadata={"help": "Boolean indicating if this canned query allows writes"}
	)
	db_is_immutable: bool = field(
	metadata={"help": "Boolean indicating if this database is immutable"}
	)
	error: str = field(metadata={"help": "Any query error message"})
	hide_sql: bool = field(
	metadata={"help": "Boolean indicating if the SQL should be hidden"}
	)
	show_hide_link: str = field(
	metadata={"help": "The URL to toggle showing/hiding the SQL"}
	)
	show_hide_text: str = field(
	metadata={"help": "The text for the show/hide SQL link"}
	)
	editable: bool = field(
	metadata={"help": "Boolean indicating if the SQL can be edited"}
	)
	allow_execute_sql: bool = field(
	metadata={"help": "Boolean indicating if custom SQL can be executed"}
	)
	tables: list = field(metadata={"help": "List of table objects in the database"})
	named_parameter_values: dict = field(
	metadata={"help": "Dictionary of parameter names/values"}
	)
	csrftoken: callable = field(metadata={"help": "Function to generate a CSRF token"})
	edit_sql_url: str = field(
	metadata={"help": "URL to edit the SQL for a canned query"}
	)
	display_rows: list = field(metadata={"help": "List of result rows to display"})
	columns: list = field(metadata={"help": "List of column names"})
	renderers: dict = field(metadata={"help": "Dictionary of renderer name to URL"})
	url_csv: str = field(metadata={"help": "URL for CSV export"})
	metadata: dict = field(metadata={"help": "Metadata about the query/database"})

[simonw]

OK, I've landed the first example of this now. I'm cautiously optimistic about it, but I think I need to use it in a few more places AND add the actual code that uses it for documentation before I'm completely happy and close this issue.

[simonw]

Here's the prototype of adding documentation for these using Cog: #1510 (comment)