mirror of
https://github.com/simonw/datasette.git
synced 2026-06-12 03:57:00 +02:00
Document table JSON extras from metadata
This commit is contained in:
Simon Willison
parent
17bbe6855c
commit
111eeaf370
3 changed files with 133 additions and 0 deletions
|
|
@ -55,6 +55,7 @@ class TableExtraContext:
|
|||
|
||||
|
||||
class CountSqlExtra(Extra):
|
||||
description = "SQL query used to calculate the total count"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -151,6 +152,7 @@ class FacetResultsExtra(Extra):
|
|||
|
||||
|
||||
class FacetsTimedOutExtra(Extra):
|
||||
description = "Facet calculations that timed out"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context, facet_results):
|
||||
|
|
@ -231,6 +233,7 @@ class PrimaryKeysExtra(Extra):
|
|||
|
||||
|
||||
class ActionsExtra(Extra):
|
||||
description = "Table or view actions made available by plugin hooks"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -258,6 +261,7 @@ class ActionsExtra(Extra):
|
|||
|
||||
|
||||
class IsViewExtra(Extra):
|
||||
description = "Whether this resource is a view instead of a table"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -313,6 +317,7 @@ class DisplayColumnsAndRowsProvider(Provider):
|
|||
|
||||
|
||||
class DisplayColumnsExtra(Extra):
|
||||
description = "Column metadata used by the HTML table display"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context, display_columns_and_rows):
|
||||
|
|
@ -320,6 +325,7 @@ class DisplayColumnsExtra(Extra):
|
|||
|
||||
|
||||
class DisplayRowsExtra(Extra):
|
||||
description = "Row data formatted for the HTML table display"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context, display_columns_and_rows):
|
||||
|
|
@ -482,6 +488,7 @@ class MetadataExtra(Extra):
|
|||
|
||||
|
||||
class DatabaseExtra(Extra):
|
||||
description = "Database name"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -489,6 +496,7 @@ class DatabaseExtra(Extra):
|
|||
|
||||
|
||||
class TableExtra(Extra):
|
||||
description = "Table name"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -496,6 +504,7 @@ class TableExtra(Extra):
|
|||
|
||||
|
||||
class DatabaseColorExtra(Extra):
|
||||
description = "Color assigned to the database"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -503,6 +512,7 @@ class DatabaseColorExtra(Extra):
|
|||
|
||||
|
||||
class FormHiddenArgsExtra(Extra):
|
||||
description = "Hidden form arguments used by the HTML table interface"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -519,6 +529,7 @@ class FormHiddenArgsExtra(Extra):
|
|||
|
||||
|
||||
class FiltersExtra(Extra):
|
||||
description = "Filters object used by the HTML table interface"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -526,6 +537,7 @@ class FiltersExtra(Extra):
|
|||
|
||||
|
||||
class CustomTableTemplatesExtra(Extra):
|
||||
description = "Custom template names considered for this table"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -537,6 +549,7 @@ class CustomTableTemplatesExtra(Extra):
|
|||
|
||||
|
||||
class SortedFacetResultsExtra(Extra):
|
||||
description = "Facet results sorted for display"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context, facet_results):
|
||||
|
|
@ -571,6 +584,7 @@ class SortedFacetResultsExtra(Extra):
|
|||
|
||||
|
||||
class TableDefinitionExtra(Extra):
|
||||
description = "SQL definition for this table"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -578,6 +592,7 @@ class TableDefinitionExtra(Extra):
|
|||
|
||||
|
||||
class ViewDefinitionExtra(Extra):
|
||||
description = "SQL definition for this view"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -585,6 +600,7 @@ class ViewDefinitionExtra(Extra):
|
|||
|
||||
|
||||
class RenderersExtra(Extra):
|
||||
description = "Alternative output renderers available for this table"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context, expandable_columns, query):
|
||||
|
|
@ -619,6 +635,7 @@ class RenderersExtra(Extra):
|
|||
|
||||
|
||||
class PrivateExtra(Extra):
|
||||
description = "Whether this table is private to the current actor"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
@ -626,6 +643,7 @@ class PrivateExtra(Extra):
|
|||
|
||||
|
||||
class ExpandableColumnsExtra(Extra):
|
||||
description = "Foreign key columns that can be expanded with labels"
|
||||
scopes = frozenset({ExtraScope.TABLE})
|
||||
|
||||
async def resolve(self, context):
|
||||
|
|
|
|||
|
|
@ -235,6 +235,101 @@ query string arguments:
|
|||
|
||||
Only available if the :ref:`setting_trace_debug` setting is enabled.
|
||||
|
||||
.. _json_api_extra:
|
||||
|
||||
Expanding table JSON responses
|
||||
------------------------------
|
||||
|
||||
Table JSON responses can be expanded with one or more ``?_extra=`` parameters.
|
||||
These can be repeated or comma-separated:
|
||||
|
||||
::
|
||||
|
||||
?_extra=columns&_extra=count,next_url
|
||||
|
||||
The available table extras are listed below.
|
||||
|
||||
.. [[[cog
|
||||
from json_api_doc import table_extras
|
||||
table_extras(cog)
|
||||
.. ]]]
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Extra
|
||||
- Description
|
||||
* - ``count``
|
||||
- Total count of rows matching these filters (May execute additional queries.)
|
||||
* - ``count_sql``
|
||||
- SQL query used to calculate the total count
|
||||
* - ``facet_results``
|
||||
- Results of facets calculated against this data (May execute additional queries.)
|
||||
* - ``facets_timed_out``
|
||||
- Facet calculations that timed out
|
||||
* - ``suggested_facets``
|
||||
- Suggestions for facets that might return interesting results (May execute additional queries.)
|
||||
* - ``human_description_en``
|
||||
- Human-readable description of the filters
|
||||
* - ``next_url``
|
||||
- Full URL for the next page of results
|
||||
* - ``columns``
|
||||
- Column names returned by this query
|
||||
* - ``all_columns``
|
||||
- All columns in the table, regardless of _col/_nocol filtering
|
||||
* - ``primary_keys``
|
||||
- Primary keys for this table
|
||||
* - ``display_columns``
|
||||
- Column metadata used by the HTML table display
|
||||
* - ``display_rows``
|
||||
- Row data formatted for the HTML table display
|
||||
* - ``render_cell``
|
||||
- Rendered HTML for each cell using the render_cell plugin hook
|
||||
* - ``debug``
|
||||
- Extra debug information
|
||||
* - ``request``
|
||||
- Full information about the request
|
||||
* - ``query``
|
||||
- Details of the underlying SQL query
|
||||
* - ``column_types``
|
||||
- Column type assignments for this table
|
||||
* - ``set_column_type_ui``
|
||||
- Column type UI metadata for this table
|
||||
* - ``metadata``
|
||||
- Metadata about the table and database
|
||||
* - ``extras``
|
||||
- Available ?_extra= blocks
|
||||
* - ``database``
|
||||
- Database name
|
||||
* - ``table``
|
||||
- Table name
|
||||
* - ``database_color``
|
||||
- Color assigned to the database
|
||||
* - ``actions``
|
||||
- Table or view actions made available by plugin hooks
|
||||
* - ``filters``
|
||||
- Filters object used by the HTML table interface
|
||||
* - ``renderers``
|
||||
- Alternative output renderers available for this table
|
||||
* - ``custom_table_templates``
|
||||
- Custom template names considered for this table
|
||||
* - ``sorted_facet_results``
|
||||
- Facet results sorted for display
|
||||
* - ``table_definition``
|
||||
- SQL definition for this table
|
||||
* - ``view_definition``
|
||||
- SQL definition for this view
|
||||
* - ``is_view``
|
||||
- Whether this resource is a view instead of a table
|
||||
* - ``private``
|
||||
- Whether this table is private to the current actor
|
||||
* - ``expandable_columns``
|
||||
- Foreign key columns that can be expanded with labels
|
||||
* - ``form_hidden_args``
|
||||
- Hidden form arguments used by the HTML table interface
|
||||
|
||||
.. [[[end]]]
|
||||
|
||||
.. _table_arguments:
|
||||
|
||||
Table arguments
|
||||
|
|
|
|||
20
docs/json_api_doc.py
Normal file
20
docs/json_api_doc.py
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
def table_extras(cog):
|
||||
from datasette.extras import ExtraScope
|
||||
from datasette.views.table_extras import table_extra_registry
|
||||
|
||||
cog.out("\n.. list-table::\n")
|
||||
cog.out(" :header-rows: 1\n\n")
|
||||
cog.out(" * - Extra\n")
|
||||
cog.out(" - Description\n")
|
||||
for cls in table_extra_registry.public_classes_for_scope(ExtraScope.TABLE):
|
||||
description = cls.description or ""
|
||||
notes = []
|
||||
if cls.expensive:
|
||||
notes.append("May execute additional queries.")
|
||||
if cls.docs_note:
|
||||
notes.append(cls.docs_note)
|
||||
if notes:
|
||||
description = "{} ({})".format(description, " ".join(notes)).strip()
|
||||
cog.out(" * - ``{}``\n".format(cls.key()))
|
||||
cog.out(" - {}\n".format(description))
|
||||
cog.out("\n")
|
||||
Loading…
Add table
Add a link
Reference in a new issue