datasette/docs/index.rst

Datasette
=========

|PyPI| |Changelog| |Python 3.x| |Tests| |License| |docker:
datasette| |discord|

.. |PyPI| image:: https://img.shields.io/pypi/v/datasette.svg
   :target: https://pypi.org/project/datasette/
.. |Changelog| image:: https://img.shields.io/github/v/release/simonw/datasette?label=changelog
   :target: https://docs.datasette.io/en/stable/changelog.html
.. |Python 3.x| image:: https://img.shields.io/pypi/pyversions/datasette.svg?logo=python&logoColor=white
   :target: https://pypi.org/project/datasette/
.. |Tests| image:: https://github.com/simonw/datasette/workflows/Test/badge.svg
   :target: https://github.com/simonw/datasette/actions?query=workflow%3ATest
.. |License| image:: https://img.shields.io/badge/license-Apache%202.0-blue.svg
   :target: https://github.com/simonw/datasette/blob/main/LICENSE
.. |docker: datasette| image:: https://img.shields.io/badge/docker-datasette-blue
   :target: https://hub.docker.com/r/datasetteproject/datasette
.. |discord| image:: https://img.shields.io/discord/823971286308356157?label=discord
   :target: https://datasette.io/discord

*An open source multi-tool for exploring and publishing data*

Datasette is a tool for exploring and publishing data. It helps people take data of any shape or size and publish that as an interactive, explorable website and accompanying API.

Datasette is aimed at data journalists, museum curators, archivists, local governments and anyone else who has data that they wish to share with the world. It is part of a :ref:`wider ecosystem of tools and plugins <ecosystem>` dedicated to making working with structured data as productive as possible.

`Explore a demo <https://fivethirtyeight.datasettes.com/fivethirtyeight>`__, watch `a presentation about the project <https://static.simonwillison.net/static/2018/pybay-datasette/>`__.

Interested in learning Datasette? Start with `the official tutorials <https://datasette.io/tutorials>`__.

Support questions, feedback? Join the `Datasette Discord <https://datasette.io/discord>`__.

Contents
--------

.. toctree::
   :maxdepth: 3

   getting_started
   installation
   configuration
   ecosystem
   cli-reference
   pages
   publish
   deploying
   json_api
   sql_queries
   authentication
   performance
   csv_export
   binary_data
   facets
   full_text_search
   spatialite
   metadata
   settings
   introspection
   custom_templates
   template_context
   plugins
   writing_plugins
   javascript_plugins
   plugin_hooks
   testing_plugins
   plugin_telemetry
   internals
   events
   upgrade_guide
   contributing
   changelog
Removed accidental R 2019-05-16 06:27:08 -07:00			`Datasette`
Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00			`=========`

Fixed undefined reference in index.rst 2020-08-19 10:22:33 -07:00			`\|PyPI\| \|Changelog\| \|Python 3.x\| \|Tests\| \|License\| \|docker:`
Fix missing Discord image Refs https://github.com/simonw/datasette.io/issues/112 2022-07-14 15:18:28 -07:00			`datasette\| \|discord\|`
Add badges to documentation index 2020-05-03 08:46:49 -07:00
			`.. \|PyPI\| image:: https://img.shields.io/pypi/v/datasette.svg`
			`:target: https://pypi.org/project/datasette/`
Don't show prereleases on changelog badge 2020-06-20 08:48:39 -07:00			`.. \|Changelog\| image:: https://img.shields.io/github/v/release/simonw/datasette?label=changelog`
Docs now live at docs.datasette.io (#937) 2020-08-15 16:57:05 -07:00			`:target: https://docs.datasette.io/en/stable/changelog.html`
Add badges to documentation index 2020-05-03 08:46:49 -07:00			`.. \|Python 3.x\| image:: https://img.shields.io/pypi/pyversions/datasette.svg?logo=python&logoColor=white`
			`:target: https://pypi.org/project/datasette/`
Run CI on GitHub Actions, not Travis * Run CI on GitHub Actions, not Travis - refs #940 * Update documentation refs to Travis * Release action now runs parallel tests, then pushes to PyPI, then Docker Hub 2020-08-17 22:09:34 -07:00			`.. \|Tests\| image:: https://github.com/simonw/datasette/workflows/Test/badge.svg`
			`:target: https://github.com/simonw/datasette/actions?query=workflow%3ATest`
Add badges to documentation index 2020-05-03 08:46:49 -07:00			`.. \|License\| image:: https://img.shields.io/badge/license-Apache%202.0-blue.svg`
Link to discussions forum 2020-08-10 19:49:22 -07:00			`:target: https://github.com/simonw/datasette/blob/main/LICENSE`
Add badges to documentation index 2020-05-03 08:46:49 -07:00			`.. \|docker: datasette\| image:: https://img.shields.io/badge/docker-datasette-blue`
			`:target: https://hub.docker.com/r/datasetteproject/datasette`
Make discord badge lowercase Refs https://github.com/simonw/datasette.io/issues/112 2022-07-14 15:04:38 -07:00			`.. \|discord\| image:: https://img.shields.io/discord/823971286308356157?label=discord`
Updated Discord link, refs #2196 This issue reminded me to use the datasette.io/discord redirect URL. 2023-10-12 14:57:04 -07:00			`:target: https://datasette.io/discord`
Add badges to documentation index 2020-05-03 08:46:49 -07:00
An open source multi-tool for exploring and publishing data 2020-07-07 12:54:54 -07:00			`An open source multi-tool for exploring and publishing data`
Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00
More human friendly 'what is Datasette' intro text 2018-11-04 22:04:23 -08:00			`Datasette is a tool for exploring and publishing data. It helps people take data of any shape or size and publish that as an interactive, explorable website and accompanying API.`
Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00
Examples of things you can do with plugins 2019-11-27 11:19:11 -08:00			Datasette is aimed at data journalists, museum curators, archivists, local governments and anyone else who has data that they wish to share with the world. It is part of a :ref:`wider ecosystem of tools and plugins <ecosystem>` dedicated to making working with structured data as productive as possible.
More human friendly 'what is Datasette' intro text 2018-11-04 22:04:23 -08:00
Removed broken refs to Glitch, closes #2503 2025-09-28 21:15:58 -07:00			`Explore a demo <https://fivethirtyeight.datasettes.com/fivethirtyeight>`__, watch `a presentation about the project <https://static.simonwillison.net/static/2018/pybay-datasette/>`__.
More human friendly 'what is Datasette' intro text 2018-11-04 22:04:23 -08:00
Link to tutorials from documentation index page 2022-02-27 10:04:03 -08:00			Interested in learning Datasette? Start with `the official tutorials <https://datasette.io/tutorials>`__.
Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00
metadata.yaml now treated as default in docs Added sphinx-inline-tabs to provide JSON and YAML tabs to show examples. Refs #1153 2023-07-08 09:37:01 -07:00			Support questions, feedback? Join the `Datasette Discord <https://datasette.io/discord>`__.

Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00			`Contents`
			`--------`

			`.. toctree::`
register_routes() plugin hook (#819) Fixes #215 2020-06-08 20:12:06 -07:00			`:maxdepth: 3`
Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00
Moved getting started into separate docs page 2017-11-30 10:27:00 -08:00			`getting_started`
Re-ordered documentation index page 2019-05-15 22:14:33 -07:00			`installation`
Plugin configuration now lives in datasette.yaml/json * Checkpoint, moving top-level plugin config to datasette.json * Support database-level and table-level plugin configuration in datasette.yaml Refs #2093 2023-09-13 14:06:25 -07:00			`configuration`
Re-ordered documentation index page 2019-05-15 22:14:33 -07:00			`ecosystem`
Improved CLI reference documentation, refs #1787 2022-08-18 14:52:04 -07:00			`cli-reference`
Docs for IndexView, TableView, RowView, closes #299 Also removed xfail from test_view_classes_are_documented, so any future *View classes that are added without documentation will cause the tests to fail. 2018-07-27 21:21:42 -07:00			`pages`
Docs for datasette publish and package, closes #337 Also introduced a new mechanism for ensuring the --help examples in the documentation reflect the current output of the --help commands, via a new update-docs-help.sh script. Closes #336 2018-07-10 19:04:13 -07:00			`publish`
Docs on deploying with systemd, refs #514 2020-10-08 15:47:37 -07:00			`deploying`
Database/Table views inherit source/license/source_url/license_url metadata If you set the source_url/license_url/source/license fields in your root metadata those values will now be inherited all the way down to the database and table templates. The title/description are NOT inherited. Also added unit tests for the HTML generated by the metadata. Refs #185 2018-03-27 09:18:32 -07:00			`json_api`
Documentation for custom SQL queries http://datasette.readthedocs.io/en/latest/sql_queries.html Closes #20 2017-12-05 09:43:59 -08:00			`sql_queries`
Added /-/permissions debug tool, closes #788 Also started the authentication.rst docs page, refs #786. Part of authentication work, refs #699. 2020-05-31 22:00:36 -07:00			`authentication`
New performance documentation, closes #421 2019-05-18 22:31:03 -07:00			`performance`
Docs for CSV export, refs #266 2018-06-18 07:12:21 -07:00			`csv_export`
Binary data documentation, closes #1047 2020-10-31 14:37:58 -07:00			`binary_data`
Initial implementation of facets, plus tests and docs Refs #255 2018-05-12 19:29:06 -03:00			`facets`
Documentation for SQLite full-text search support, closes #253 2018-05-12 09:06:38 -03:00			`full_text_search`
Initial documentation on using SpatiaLite https://datasette.readthedocs.io/en/latest/spatialite.html 2018-05-26 11:04:09 -07:00			`spatialite`
Documentation for metadata.json and "datasette skeleton" command http://datasette.readthedocs.io/en/latest/metadata.html Closes #166 2017-12-07 09:19:35 -08:00			`metadata`
Updated docs renaming config to settings - config.html is now settings.html - ConfigOption in app.py is now Setting - updated documentation unit tests Refs #1106 2020-11-24 13:22:33 -08:00			`settings`
Added docs for introspection endpoints https://datasette.readthedocs.io/en/latest/introspection.html 2018-05-20 14:28:53 -07:00			`introspection`
Re-ordered docs index page 2017-12-06 10:27:50 -08:00			`custom_templates`
Generated template context documentation, closes #1510 docs/template_context.rst is generated by cog from the manifest in datasette/template_contexts.py, following the json_api_doc.py pattern. It documents the base context available on every page plus the database, query, table and row pages, including the stability policy for custom template authors. Refs #2127 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> 2026-06-11 00:00:42 -07:00			`template_context`
Initial documentation for plugins, closes #213 https://datasette.readthedocs.io/en/latest/plugins.html 2018-04-16 08:12:09 -07:00			`plugins`
Split out new 'Writing plugins' page, refs #687 2020-06-21 19:37:48 -07:00			`writing_plugins`
JavaScript plugins documentation, closes #2250 2024-02-05 11:47:17 -08:00			`javascript_plugins`
Move plugin hooks docs to plugin_hooks.rst, refs #687 2020-06-21 17:33:48 -07:00			`plugin_hooks`
New 'Testing plugins' page, closes #687 2020-06-21 20:53:42 -07:00			`testing_plugins`
Add a plugin telemetry kit: public registry API, linked_root_span_kwargs, test helpers, docs A survey of five plugin OTel plans (datasette-paper, -agent, -litestream, -accounts, -cron) found every one hand-copying the same core machinery: the registry classes, the conformance-test harness, the pytest fixtures, the bucket boundaries and the detached-root-with-Link recipe. This makes that machinery importable instead: - The registry classes are documented public API. Attribute gains values= (a closed enum the conformance helpers enforce - what makes an attribute safe as a metric dimension); SpanName gains prefix=True for span families like "chat {model}" whose names share a fixed prefix, matched by span_for() after exact names. span_for()/attribute helpers accept a spans= tuple so plugin registries can use them. - datasette.telemetry.linked_root_span_kwargs(): the root-span-with-Link shape for work a request caused without containing - background jobs, scheduled ticks, block=False writes. Core's own write thread now uses it instead of building the kwargs inline. - datasette.telemetry_testing: the session provider fixtures, otel_spans / otel_metrics, a two-way registry conformance checker (including enum and prefix handling, filtered by instrumentation scope) and an assert_package_never_imports_sdk() guard. Core's conftest now imports these instead of defining them, so the suite consumes the kit exactly as a plugin's would. - New "Telemetry for plugin authors" docs page: scope discipline, registry usage, privacy/cardinality rules, named-callable guidance, request_span(), the background root-with-link convention (one root per tick, always emitted), provider-ordering facts and known caveats. request_span() is now documented public API. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012U7coQfVu8nK2R4q2mCULA 2026-09-02 12:24:42 -07:00			`plugin_telemetry`
.execute_write() and .execute_write_fn() methods on Database (#683) Closes #682. 2020-02-24 20:45:08 -08:00			`internals`
track_event() mechanism for analytics and plugins * Closes #2240 * Documentation for event plugin hooks, refs #2240 * Include example track_event plugin in docs, refs #2240 * Tests for track_event() and register_events() hooks, refs #2240 * Initial documentation for core events, refs #2240 * Internals documentation for datasette.track_event() 2024-01-31 15:21:40 -08:00			`events`
Tweaks and improvements to upgrade guide, refs ##2374 Also refs #2381 2024-08-05 12:11:17 -07:00			`upgrade_guide`
Tweak order of documentation contents 2022-01-13 16:30:00 -08:00			`contributing`
Added initial docs, including a changelog Docs initialized using this helpful guide: http://docs.readthedocs.io/en/latest/getting_started.html I used https://pypi.python.org/pypi/gitchangelog to kick-start the changelog. Closes #99 Refs #109 2017-11-16 07:11:00 -08:00			`changelog`