{"id": "authentication:permissions-create-table", "page": "authentication", "ref": "permissions-create-table", "title": "create-table", "content": "Actor is allowed to create a database table. \n                 \n                     \n                         resource  - string \n                         \n                             The name of the database \n                         \n                     \n                 \n                 Default  deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"}
{"id": "plugin_hooks:plugin-hook-canned-queries", "page": "plugin_hooks", "ref": "plugin-hook-canned-queries", "title": "canned_queries(datasette, database, actor)", "content": "datasette  -  Datasette class \n                     \n                         You can use this to access plugin configuration options via  datasette.plugin_config(your_plugin_name) , or to execute SQL queries. \n                     \n                 \n                 \n                     database  - string \n                     \n                         The name of the database. \n                     \n                 \n                 \n                     actor  - dictionary or None \n                     \n                         The currently authenticated  actor . \n                     \n                 \n             \n             Use this hook to return a dictionary of additional  canned query  definitions for the specified database. The return value should be the same shape as the JSON described in the  canned query  documentation. \n             from datasette import hookimpl\n\n\n@hookimpl\ndef canned_queries(datasette, database):\n    if database == \"mydb\":\n        return {\n            \"my_query\": {\n                \"sql\": \"select * from my_table where id > :min_id\"\n            }\n        } \n             The hook can alternatively return an awaitable function that returns a list. Here's an example that returns queries that have been stored in the  saved_queries  database table, if one exists: \n             from datasette import hookimpl\n\n\n@hookimpl\ndef canned_queries(datasette, database):\n    async def inner():\n        db = datasette.get_database(database)\n        if await db.table_exists(\"saved_queries\"):\n            results = await db.execute(\n                \"select name, sql from saved_queries\"\n            )\n            return {\n                result[\"name\"]: {\"sql\": result[\"sql\"]}\n                for result in results\n            }\n\n    return inner \n             The actor parameter can be used to include the currently authenticated actor in your decision. Here's an example that returns saved queries that were saved by that actor: \n             from datasette import hookimpl\n\n\n@hookimpl\ndef canned_queries(datasette, database, actor):\n    async def inner():\n        db = datasette.get_database(database)\n        if actor is not None and await db.table_exists(\n            \"saved_queries\"\n        ):\n            results = await db.execute(\n                \"select name, sql from saved_queries where actor_id = :id\",\n                {\"id\": actor[\"id\"]},\n            )\n            return {\n                result[\"name\"]: {\"sql\": result[\"sql\"]}\n                for result in results\n            }\n\n    return inner \n             Example:  datasette-saved-queries", "breadcrumbs": "[\"Plugin hooks\"]", "references": "[{\"href\": \"https://datasette.io/plugins/datasette-saved-queries\", \"label\": \"datasette-saved-queries\"}]"}
{"id": "settings:setting-cache-size-kb", "page": "settings", "ref": "setting-cache-size-kb", "title": "cache_size_kb", "content": "Sets the amount of memory SQLite uses for its  per-connection cache , in KB. \n                 datasette mydatabase.db --setting cache_size_kb 5000", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[{\"href\": \"https://www.sqlite.org/pragma.html#pragma_cache_size\", \"label\": \"per-connection cache\"}]"}
{"id": "contributing:contributing-formatting-blacken-docs", "page": "contributing", "ref": "contributing-formatting-blacken-docs", "title": "blacken-docs", "content": "The  blacken-docs  command applies Black formatting rules to code examples in the documentation. Run it like this: \n                 blacken-docs -l 60 docs/*.rst", "breadcrumbs": "[\"Contributing\", \"Code formatting\"]", "references": "[{\"href\": \"https://pypi.org/project/blacken-docs/\", \"label\": \"blacken-docs\"}]"}
{"id": "settings:setting-base-url", "page": "settings", "ref": "setting-base-url", "title": "base_url", "content": "If you are running Datasette behind a proxy, it may be useful to change the root path used for the Datasette instance. \n                 For example, if you are sending traffic from  https://www.example.com/tools/datasette/  through to a proxied Datasette instance you may wish Datasette to use  /tools/datasette/  as its root URL. \n                 You can do that like so: \n                 datasette mydatabase.db --setting base_url /tools/datasette/", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"}
{"id": "internals:internals-utils-await-me-maybe", "page": "internals", "ref": "internals-utils-await-me-maybe", "title": "await_me_maybe(value)", "content": "Utility function for calling  await  on a return value if it is awaitable, otherwise returning the value. This is used by Datasette to support plugin hooks that can optionally return awaitable functions. Read more about this function in  The \u201cawait me maybe\u201d pattern for Python asyncio . \n                 \n                 \n                     async   datasette.utils. await_me_maybe value :   Any Any \n                     \n                         If value is callable, call it. If awaitable, await it. Otherwise return it.", "breadcrumbs": "[\"Internals for plugins\", \"The datasette.utils module\"]", "references": "[{\"href\": \"https://simonwillison.net/2020/Sep/2/await-me-maybe/\", \"label\": \"The \u201cawait me maybe\u201d pattern for Python asyncio\"}]"}
{"id": "internals:database-execute-write-script", "page": "internals", "ref": "database-execute-write-script", "title": "await db.execute_write_script(sql, block=True)", "content": "Like  execute_write()  but can be used to send multiple SQL statements in a single string separated by semicolons, using the  sqlite3   conn.executescript()  method. \n                 Each call to  execute_write_script()  will be executed inside a transaction.", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[{\"href\": \"https://docs.python.org/3/library/sqlite3.html#sqlite3.Cursor.executescript\", \"label\": \"conn.executescript()\"}]"}
{"id": "internals:database-execute-write-many", "page": "internals", "ref": "database-execute-write-many", "title": "await db.execute_write_many(sql, params_seq, block=True)", "content": "Like  execute_write()  but uses the  sqlite3   conn.executemany()  method. This will efficiently execute the same SQL statement against each of the parameters in the  params_seq  iterator, for example: \n                 await db.execute_write_many(\n    \"insert into characters (id, name) values (?, ?)\",\n    [(1, \"Melanie\"), (2, \"Selma\"), (2, \"Viktor\")],\n) \n                 Each call to  execute_write_many()  will be executed inside a transaction.", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[{\"href\": \"https://docs.python.org/3/library/sqlite3.html#sqlite3.Cursor.executemany\", \"label\": \"conn.executemany()\"}]"}
{"id": "internals:database-execute-write-fn", "page": "internals", "ref": "database-execute-write-fn", "title": "await db.execute_write_fn(fn, block=True, transaction=True)", "content": "This method works like  .execute_write() , but instead of a SQL statement you give it a callable Python function. Your function will be queued up and then called when the write connection is available, passing that connection as the argument to the function. \n                 The function can then perform multiple actions, safe in the knowledge that it has exclusive access to the single writable connection for as long as it is executing. \n                 \n                     fn  needs to be a regular function, not an  async def  function. \n                 \n                 For example: \n                 def delete_and_return_count(conn):\n    conn.execute(\"delete from some_table where id > 5\")\n    return conn.execute(\n        \"select count(*) from some_table\"\n    ).fetchone()[0]\n\n\ntry:\n    num_rows_left = await database.execute_write_fn(\n        delete_and_return_count\n    )\nexcept Exception as e:\n    print(\"An error occurred:\", e) \n                 The value returned from  await database.execute_write_fn(...)  will be the return value from your function. \n                 If your function raises an exception that exception will be propagated up to the  await  line. \n                 By default your function will be executed inside a transaction. You can pass  transaction=False  to disable this behavior, though if you do that you should be careful to manually apply transactions - ideally using the  with conn:  pattern, or you may see  OperationalError: database table is locked  errors. \n                 If you specify  block=False  the method becomes fire-and-forget, queueing your function to be executed and then allowing your code after the call to  .execute_write_fn()  to continue running while the underlying thread waits for an opportunity to run your function. A UUID representing the queued task will be returned. Any exceptions in your code will be silently swallowed.", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[]"}
{"id": "internals:database-execute-write", "page": "internals", "ref": "database-execute-write", "title": "await db.execute_write(sql, params=None, block=True)", "content": "SQLite only allows one database connection to write at a time. Datasette handles this for you by maintaining a queue of writes to be executed against a given database. Plugins can submit write operations to this queue and they will be executed in the order in which they are received. \n                 This method can be used to queue up a non-SELECT SQL query to be executed against a single write connection to the database. \n                 You can pass additional SQL parameters as a tuple or dictionary. \n                 The method will block until the operation is completed, and the return value will be the return from calling  conn.execute(...)  using the underlying  sqlite3  Python library. \n                 If you pass  block=False  this behavior changes to \"fire and forget\" - queries will be added to the write queue and executed in a separate thread while your code can continue to do other things. The method will return a UUID representing the queued task. \n                 Each call to  execute_write()  will be executed inside a transaction.", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[]"}
{"id": "internals:database-execute-isolated-fn", "page": "internals", "ref": "database-execute-isolated-fn", "title": "await db.execute_isolated_fn(fn)", "content": "This method works is similar to  execute_write_fn()  but executes the provided function in an entirely isolated SQLite connection, which is opened, used and then closed again in a single call to this method. \n                 The  prepare_connection()  plugin hook is not executed against this connection. \n                 This allows plugins to execute database operations that might conflict with how database connections are usually configured. For example, running a  VACUUM  operation while bypassing any restrictions placed by the  datasette-sqlite-authorizer  plugin. \n                 Plugins can also use this method to load potentially dangerous SQLite extensions, use them to perform an operation and then have them safely unloaded at the end of the call, without risk of exposing them to other connections. \n                 Functions run using  execute_isolated_fn()  share the same queue as  execute_write_fn() , which guarantees that no writes can be executed at the same time as the isolated function is executing. \n                 The return value of the function will be returned by this method. Any exceptions raised by the function will be raised out of the  await  line as well.", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[{\"href\": \"https://github.com/datasette/datasette-sqlite-authorizer\", \"label\": \"datasette-sqlite-authorizer\"}]"}
{"id": "internals:database-execute-fn", "page": "internals", "ref": "database-execute-fn", "title": "await db.execute_fn(fn)", "content": "Executes a given callback function against a read-only database connection running in a thread. The function will be passed a SQLite connection, and the return value from the function will be returned by the  await . \n                 Example usage: \n                 def get_version(conn):\n    return conn.execute(\n        \"select sqlite_version()\"\n    ).fetchall()[0][0]\n\n\nversion = await db.execute_fn(get_version)", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[]"}
{"id": "internals:database-execute", "page": "internals", "ref": "database-execute", "title": "await db.execute(sql, ...)", "content": "Executes a SQL query against the database and returns the resulting rows (see  Results ). \n                 \n                     \n                         sql  - string (required) \n                         \n                             The SQL query to execute. This can include  ?  or  :named  parameters. \n                         \n                     \n                     \n                         params  - list or dict \n                         \n                             A list or dictionary of values to use for the parameters. List for  ? , dictionary for  :named . \n                         \n                     \n                     \n                         truncate  - boolean \n                         \n                             Should the rows returned by the query be truncated at the maximum page size? Defaults to  True , set this to  False  to disable truncation. \n                         \n                     \n                     \n                         custom_time_limit  - integer ms \n                         \n                             A custom time limit for this query. This can be set to a lower value than the Datasette configured default. If a query takes longer than this it will be terminated early and raise a  dataette.database.QueryInterrupted  exception. \n                         \n                     \n                     \n                         page_size  - integer \n                         \n                             Set a custom page size for truncation, over-riding the configured Datasette default. \n                         \n                     \n                     \n                         log_sql_errors  - boolean \n                         \n                             Should any SQL errors be logged to the console in addition to being raised as an error? Defaults to  True .", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[]"}
{"id": "internals:datasette-track-event", "page": "internals", "ref": "datasette-track-event", "title": "await .track_event(event)", "content": "event  -  Event \n                         \n                             An instance of a subclass of  datasette.events.Event . \n                         \n                     \n                 \n                 Plugins can call this to track events, using classes they have previously registered. See  Event tracking  for details. \n                 The event will then be passed to all plugins that have registered to receive events using the  track_event(datasette, event)  hook. \n                 Example usage, assuming the plugin has previously registered the  BanUserEvent  class: \n                 await datasette.track_event(\n    BanUserEvent(user={\"id\": 1, \"username\": \"cleverbot\"})\n)", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[]"}
{"id": "internals:datasette-render-template", "page": "internals", "ref": "datasette-render-template", "title": "await .render_template(template, context=None, request=None)", "content": "template  - string, list of strings or jinja2.Template \n                         \n                             The template file to be rendered, e.g.  my_plugin.html . Datasette will search for this file first in the  --template-dir=  location, if it was specified - then in the plugin's bundled templates and finally in Datasette's set of default templates. \n                             If this is a list of template file names then the first one that exists will be loaded and rendered. \n                             If this is a Jinja  Template object  it will be used directly. \n                         \n                     \n                     \n                         context  - None or a Python dictionary \n                         \n                             The context variables to pass to the template. \n                         \n                     \n                     \n                         request  - request object or None \n                         \n                             If you pass a Datasette request object here it will be made available to the template. \n                         \n                     \n                 \n                 Renders a  Jinja template  using Datasette's preconfigured instance of Jinja and returns the resulting string. The template will have access to Datasette's default template functions and any functions that have been made available by other plugins.", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[{\"href\": \"https://jinja.palletsprojects.com/en/2.11.x/api/#jinja2.Template\", \"label\": \"Template object\"}, {\"href\": \"https://jinja.palletsprojects.com/en/2.11.x/\", \"label\": \"Jinja template\"}]"}
{"id": "internals:datasette-permission-allowed", "page": "internals", "ref": "datasette-permission-allowed", "title": "await .permission_allowed(actor, action, resource=None, default=...)", "content": "actor  - dictionary \n                         \n                             The authenticated actor. This is usually  request.actor . \n                         \n                     \n                     \n                         action  - string \n                         \n                             The name of the action that is being permission checked. \n                         \n                     \n                     \n                         resource  - string or tuple, optional \n                         \n                             The resource, e.g. the name of the database, or a tuple of two strings containing the name of the database and the name of the table. Only some permissions apply to a resource. \n                         \n                     \n                     \n                         default  - optional: True, False or None \n                         \n                             What value should be returned by default if nothing provides an opinion on this permission check.\n                                Set to  True  for default allow or  False  for default deny.\n                                If not specified the  default  from the  Permission()  tuple that was registered using  register_permissions(datasette)  will be used. \n                         \n                     \n                 \n                 Check if the given actor has  permission  to perform the given action on the given resource. \n                 Some permission checks are carried out against  rules defined in datasette.yaml , while other custom permissions may be decided by plugins that implement the  permission_allowed(datasette, actor, action, resource)  plugin hook. \n                 If neither  metadata.json  nor any of the plugins provide an answer to the permission query the  default  argument will be returned. \n                 See  Built-in permissions  for a full list of permission actions included in Datasette core.", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[]"}
{"id": "internals:datasette-ensure-permissions", "page": "internals", "ref": "datasette-ensure-permissions", "title": "await .ensure_permissions(actor, permissions)", "content": "actor  - dictionary \n                         \n                             The authenticated actor. This is usually  request.actor . \n                         \n                     \n                     \n                         permissions  - list \n                         \n                             A list of permissions to check. Each permission in that list can be a string  action  name or a 2-tuple of  (action, resource) . \n                         \n                     \n                 \n                 This method allows multiple permissions to be checked at once. It raises a  datasette.Forbidden  exception if any of the checks are denied before one of them is explicitly granted. \n                 This is useful when you need to check multiple permissions at once. For example, an actor should be able to view a table if either one of the following checks returns  True  or not a single one of them returns  False : \n                 await datasette.ensure_permissions(\n    request.actor,\n    [\n        (\"view-table\", (database, table)),\n        (\"view-database\", database),\n        \"view-instance\",\n    ],\n)", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[]"}
{"id": "internals:datasette-check-visibility", "page": "internals", "ref": "datasette-check-visibility", "title": "await .check_visibility(actor, action=None, resource=None, permissions=None)", "content": "actor  - dictionary \n                         \n                             The authenticated actor. This is usually  request.actor . \n                         \n                     \n                     \n                         action  - string, optional \n                         \n                             The name of the action that is being permission checked. \n                         \n                     \n                     \n                         resource  - string or tuple, optional \n                         \n                             The resource, e.g. the name of the database, or a tuple of two strings containing the name of the database and the name of the table. Only some permissions apply to a resource. \n                         \n                     \n                     \n                         permissions  - list of  action  strings or  (action, resource)  tuples, optional \n                         \n                             Provide this instead of  action  and  resource  to check multiple permissions at once. \n                         \n                     \n                 \n                 This convenience method can be used to answer the question \"should this item be considered private, in that it is visible to me but it is not visible to anonymous users?\" \n                 It returns a tuple of two booleans,  (visible, private) .  visible  indicates if the actor can see this resource.  private  will be  True  if an anonymous user would not be able to view the resource. \n                 This example checks if the user can access a specific table, and sets  private  so that a padlock icon can later be displayed: \n                 visible, private = await datasette.check_visibility(\n    request.actor,\n    action=\"view-table\",\n    resource=(database, table),\n) \n                 The following example runs three checks in a row, similar to  await .ensure_permissions(actor, permissions) . If any of the checks are denied before one of them is explicitly granted then  visible  will be  False .  private  will be  True  if an anonymous user would not be able to view the resource. \n                 visible, private = await datasette.check_visibility(\n    request.actor,\n    permissions=[\n        (\"view-table\", (database, table)),\n        (\"view-database\", database),\n        \"view-instance\",\n    ],\n)", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[]"}
{"id": "internals:datasette-actors-from-ids", "page": "internals", "ref": "datasette-actors-from-ids", "title": "await .actors_from_ids(actor_ids)", "content": "actor_ids  - list of strings or integers \n                         \n                             A list of actor IDs to look up. \n                         \n                     \n                 \n                 Returns a dictionary, where the keys are the IDs passed to it and the values are the corresponding actor dictionaries. \n                 This method is mainly designed to be used with plugins. See the  actors_from_ids(datasette, actor_ids)  documentation for details. \n                 If no plugins that implement that hook are installed, the default return value looks like this: \n                 {\n    \"1\": {\"id\": \"1\"},\n    \"2\": {\"id\": \"2\"}\n}", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[]"}
{"id": "plugin_hooks:plugin-asgi-wrapper", "page": "plugin_hooks", "ref": "plugin-asgi-wrapper", "title": "asgi_wrapper(datasette)", "content": "Return an  ASGI  middleware wrapper function that will be applied to the Datasette ASGI application. \n             This is a very powerful hook. You can use it to manipulate the entire Datasette response, or even to configure new URL routes that will be handled by your own custom code. \n             You can write your ASGI code directly against the low-level specification, or you can use the middleware utilities provided by an ASGI framework such as  Starlette . \n             This example plugin adds a  x-databases  HTTP header listing the currently attached databases: \n             from datasette import hookimpl\nfrom functools import wraps\n\n\n@hookimpl\ndef asgi_wrapper(datasette):\n    def wrap_with_databases_header(app):\n        @wraps(app)\n        async def add_x_databases_header(\n            scope, receive, send\n        ):\n            async def wrapped_send(event):\n                if event[\"type\"] == \"http.response.start\":\n                    original_headers = (\n                        event.get(\"headers\") or []\n                    )\n                    event = {\n                        \"type\": event[\"type\"],\n                        \"status\": event[\"status\"],\n                        \"headers\": original_headers\n                        + [\n                            [\n                                b\"x-databases\",\n                                \", \".join(\n                                    datasette.databases.keys()\n                                ).encode(\"utf-8\"),\n                            ]\n                        ],\n                    }\n                await send(event)\n\n            await app(scope, receive, wrapped_send)\n\n        return add_x_databases_header\n\n    return wrap_with_databases_header \n             Examples:  datasette-cors ,  datasette-pyinstrument ,  datasette-total-page-time", "breadcrumbs": "[\"Plugin hooks\"]", "references": "[{\"href\": \"https://asgi.readthedocs.io/\", \"label\": \"ASGI\"}, {\"href\": \"https://www.starlette.io/middleware/\", \"label\": \"Starlette\"}, {\"href\": \"https://datasette.io/plugins/datasette-cors\", \"label\": \"datasette-cors\"}, {\"href\": \"https://datasette.io/plugins/datasette-pyinstrument\", \"label\": \"datasette-pyinstrument\"}, {\"href\": \"https://datasette.io/plugins/datasette-total-page-time\", \"label\": \"datasette-total-page-time\"}]"}
{"id": "authentication:permissions-alter-table", "page": "authentication", "ref": "permissions-alter-table", "title": "alter-table", "content": "Actor is allowed to alter a database table. \n                 \n                     \n                         resource  - tuple: (string, string) \n                         \n                             The name of the database, then the name of the table \n                         \n                     \n                 \n                 Default  deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"}
{"id": "settings:setting-allow-signed-tokens", "page": "settings", "ref": "setting-allow-signed-tokens", "title": "allow_signed_tokens", "content": "Should users be able to create signed API tokens to access Datasette? \n                 This is turned on by default. Use the following to turn it off: \n                 datasette mydatabase.db --setting allow_signed_tokens off \n                 Turning this setting off will disable the  /-/create-token  page,  described here . It will also cause any incoming  Authorization: Bearer dstok_...  API tokens to be ignored.", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"}
{"id": "settings:setting-allow-facet", "page": "settings", "ref": "setting-allow-facet", "title": "allow_facet", "content": "Allow users to specify columns they would like to facet on using the  ?_facet=COLNAME  URL parameter to the table view. \n                 This is enabled by default. If disabled, facets will still be displayed if they have been specifically enabled in  metadata.json  configuration for the table. \n                 Here's how to disable this feature: \n                 datasette mydatabase.db --setting allow_facet off", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"}
{"id": "settings:setting-allow-download", "page": "settings", "ref": "setting-allow-download", "title": "allow_download", "content": "Should users be able to download the original SQLite database using a link on the database index page? This is turned on by default. However, databases can only be downloaded if they are served in immutable mode and not in-memory. If downloading is unavailable for either of these reasons, the download link is hidden even if  allow_download  is on. To disable database downloads, use the following: \n                 datasette mydatabase.db --setting allow_download off", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"}
{"id": "settings:setting-allow-csv-stream", "page": "settings", "ref": "setting-allow-csv-stream", "title": "allow_csv_stream", "content": "Enables  the CSV export feature  where an entire table\n                    (potentially hundreds of thousands of rows) can be exported as a single CSV\n                    file. This is turned on by default - you can turn it off like this: \n                 datasette mydatabase.db --setting allow_csv_stream off", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"}
{"id": "plugin_hooks:plugin-hook-actors-from-ids", "page": "plugin_hooks", "ref": "plugin-hook-actors-from-ids", "title": "actors_from_ids(datasette, actor_ids)", "content": "datasette  -  Datasette class \n                     \n                         You can use this to access plugin configuration options via  datasette.plugin_config(your_plugin_name) , or to execute SQL queries. \n                     \n                 \n                 \n                     actor_ids  - list of strings or integers \n                     \n                         The actor IDs to look up. \n                     \n                 \n             \n             The hook must return a dictionary that maps the incoming actor IDs to their full dictionary representation. \n             Some plugins that implement social features may store the ID of the  actor  that performed an action - added a comment, bookmarked a table or similar - and then need a way to resolve those IDs into display-friendly actor dictionaries later on. \n             The  await datasette.actors_from_ids(actor_ids)  internal method can be used to look up actors from their IDs. It will dispatch to the first plugin that implements this hook. \n             Unlike other plugin hooks, this only uses the first implementation of the hook to return a result. You can expect users to only have a single plugin installed that implements this hook. \n             If no plugin is installed, Datasette defaults to returning actors that are just  {\"id\": actor_id} . \n             The hook can return a dictionary or an awaitable function that then returns a dictionary. \n             This example implementation returns actors from a database table: \n             from datasette import hookimpl\n\n\n@hookimpl\ndef actors_from_ids(datasette, actor_ids):\n    db = datasette.get_database(\"actors\")\n\n    async def inner():\n        sql = \"select id, name from actors where id in ({})\".format(\n            \", \".join(\"?\" for _ in actor_ids)\n        )\n        actors = {}\n        for row in (await db.execute(sql, actor_ids)).rows:\n            actor = dict(row)\n            actors[actor[\"id\"]] = actor\n        return actors\n\n    return inner \n             The returned dictionary from this example looks like this: \n             {\n    \"1\": {\"id\": \"1\", \"name\": \"Tony\"},\n    \"2\": {\"id\": \"2\", \"name\": \"Tina\"},\n} \n             These IDs could be integers or strings, depending on how the actors used by the Datasette instance are configured. \n             Example:  datasette-remote-actors", "breadcrumbs": "[\"Plugin hooks\"]", "references": "[{\"href\": \"https://github.com/datasette/datasette-remote-actors\", \"label\": \"datasette-remote-actors\"}]"}
{"id": "authentication:authentication-actor-matches-allow", "page": "authentication", "ref": "authentication-actor-matches-allow", "title": "actor_matches_allow()", "content": "Plugins that wish to implement this same  \"allow\"  block permissions scheme can take advantage of the  datasette.utils.actor_matches_allow(actor, allow)  function: \n             from datasette.utils import actor_matches_allow\n\nactor_matches_allow({\"id\": \"root\"}, {\"id\": \"*\"})\n# returns True \n             The currently authenticated actor is made available to plugins as  request.actor .", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "plugin_hooks:plugin-hook-actor-from-request", "page": "plugin_hooks", "ref": "plugin-hook-actor-from-request", "title": "actor_from_request(datasette, request)", "content": "datasette  -  Datasette class \n                     \n                         You can use this to access plugin configuration options via  datasette.plugin_config(your_plugin_name) , or to execute SQL queries. \n                     \n                 \n                 \n                     request  -  Request object \n                     \n                         The current HTTP request. \n                     \n                 \n             \n             This is part of Datasette's  authentication and permissions system . The function should attempt to authenticate an actor (either a user or an API actor of some sort) based on information in the request. \n             If it cannot authenticate an actor, it should return  None . Otherwise it should return a dictionary representing that actor. \n             Here's an example that authenticates the actor based on an incoming API key: \n             from datasette import hookimpl\nimport secrets\n\nSECRET_KEY = \"this-is-a-secret\"\n\n\n@hookimpl\ndef actor_from_request(datasette, request):\n    authorization = (\n        request.headers.get(\"authorization\") or \"\"\n    )\n    expected = \"Bearer {}\".format(SECRET_KEY)\n\n    if secrets.compare_digest(authorization, expected):\n        return {\"id\": \"bot\"} \n             If you install this in your plugins directory you can test it like this: \n             curl -H 'Authorization: Bearer this-is-a-secret' http://localhost:8003/-/actor.json \n             Instead of returning a dictionary, this function can return an awaitable function which itself returns either  None  or a dictionary. This is useful for authentication functions that need to make a database query - for example: \n             from datasette import hookimpl\n\n\n@hookimpl\ndef actor_from_request(datasette, request):\n    async def inner():\n        token = request.args.get(\"_token\")\n        if not token:\n            return None\n        # Look up ?_token=xxx in sessions table\n        result = await datasette.get_database().execute(\n            \"select count(*) from sessions where token = ?\",\n            [token],\n        )\n        if result.first()[0]:\n            return {\"token\": token}\n        else:\n            return None\n\n    return inner \n             Examples:  datasette-auth-tokens ,  datasette-auth-passwords", "breadcrumbs": "[\"Plugin hooks\"]", "references": "[{\"href\": \"https://datasette.io/plugins/datasette-auth-tokens\", \"label\": \"datasette-auth-tokens\"}, {\"href\": \"https://datasette.io/plugins/datasette-auth-passwords\", \"label\": \"datasette-auth-passwords\"}]"}
{"id": "writing_plugins:writing-plugins-configuration", "page": "writing_plugins", "ref": "writing-plugins-configuration", "title": "Writing plugins that accept configuration", "content": "When you are writing plugins, you can access plugin configuration like this using the  datasette plugin_config()  method. If you know you need plugin configuration for a specific table, you can access it like this: \n             plugin_config = datasette.plugin_config(\n    \"datasette-cluster-map\", database=\"sf-trees\", table=\"Street_Tree_List\"\n) \n             This will return the  {\"latitude_column\": \"lat\", \"longitude_column\": \"lng\"}  in the above example. \n             If there is no configuration for that plugin, the method will return  None . \n             If it cannot find the requested configuration at the table layer, it will fall back to the database layer and then the root layer. For example, a user may have set the plugin configuration option inside  datasette.yaml  like so: \n             [[[cog\nfrom metadata_doc import metadata_example\nmetadata_example(cog, {\n    \"databases\": {\n        \"sf-trees\": {\n            \"plugins\": {\n                \"datasette-cluster-map\": {\n                    \"latitude_column\": \"xlat\",\n                    \"longitude_column\": \"xlng\"\n                }\n            }\n        }\n    }\n}) \n             ]]] \n             [[[end]]] \n             In this case, the above code would return that configuration for ANY table within the  sf-trees  database. \n             The plugin configuration could also be set at the top level of  datasette.yaml : \n             [[[cog\nmetadata_example(cog, {\n    \"plugins\": {\n        \"datasette-cluster-map\": {\n            \"latitude_column\": \"xlat\",\n            \"longitude_column\": \"xlng\"\n        }\n    }\n}) \n             ]]] \n             [[[end]]] \n             Now that  datasette-cluster-map  plugin configuration will apply to every table in every database.", "breadcrumbs": "[\"Writing plugins\"]", "references": "[]"}
{"id": "writing_plugins:id1", "page": "writing_plugins", "ref": "id1", "title": "Writing plugins", "content": "You can write one-off plugins that apply to just one Datasette instance, or you can write plugins which can be installed using  pip  and can be shipped to the Python Package Index ( PyPI ) for other people to install. \n         Want to start by looking at an example? The  Datasette plugins directory  lists more than 90 open source plugins with code you can explore. The  plugin hooks  page includes links to example plugins for each of the documented hooks.", "breadcrumbs": "[]", "references": "[{\"href\": \"https://pypi.org/\", \"label\": \"PyPI\"}, {\"href\": \"https://datasette.io/plugins\", \"label\": \"Datasette plugins directory\"}]"}
{"id": "writing_plugins:writing-plugins-one-off", "page": "writing_plugins", "ref": "writing-plugins-one-off", "title": "Writing one-off plugins", "content": "The quickest way to start writing a plugin is to create a  my_plugin.py  file and drop it into your  plugins/  directory. Here is an example plugin, which adds a new custom SQL function called  hello_world()  which takes no arguments and returns the string  Hello world! . \n             from datasette import hookimpl\n\n\n@hookimpl\ndef prepare_connection(conn):\n    conn.create_function(\n        \"hello_world\", 0, lambda: \"Hello world!\"\n    ) \n             If you save this in  plugins/my_plugin.py  you can then start Datasette like this: \n             datasette serve mydb.db --plugins-dir=plugins/ \n             Now you can navigate to  http://localhost:8001/mydb  and run this SQL: \n             select hello_world(); \n             To see the output of your plugin.", "breadcrumbs": "[\"Writing plugins\"]", "references": "[{\"href\": \"http://localhost:8001/mydb\", \"label\": \"http://localhost:8001/mydb\"}]"}
{"id": "changelog:write-api", "page": "changelog", "ref": "write-api", "title": "Write API", "content": "New API explorer at  /-/api  for trying out the API. ( #1871 ) \n                     \n                     \n                         /db/-/create  API for  Creating a table . ( #1882 ) \n                     \n                     \n                         /db/table/-/insert  API for  Inserting rows . ( #1851 ) \n                     \n                     \n                         /db/table/-/drop  API for  Dropping tables . ( #1874 ) \n                     \n                     \n                         /db/table/pk/-/update  API for  Updating a row . ( #1863 ) \n                     \n                     \n                         /db/table/pk/-/delete  API for  Deleting a row . ( #1864 )", "breadcrumbs": "[\"Changelog\", \"1.0a0 (2022-11-29)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1871\", \"label\": \"#1871\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1882\", \"label\": \"#1882\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1851\", \"label\": \"#1851\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1874\", \"label\": \"#1874\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1863\", \"label\": \"#1863\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1864\", \"label\": \"#1864\"}]"}
{"id": "changelog:writable-canned-queries", "page": "changelog", "ref": "writable-canned-queries", "title": "Writable canned queries", "content": "Datasette's  Canned queries  feature lets you define SQL queries in  metadata.json  which can then be executed by users visiting a specific URL.  https://latest.datasette.io/fixtures/neighborhood_search  for example. \n                 Canned queries were previously restricted to  SELECT , but Datasette 0.44 introduces the ability for canned queries to execute  INSERT  or  UPDATE  queries as well, using the new  \"write\": true  property ( #800 ): \n                 {\n    \"databases\": {\n        \"dogs\": {\n            \"queries\": {\n                \"add_name\": {\n                    \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n                    \"write\": true\n                }\n            }\n        }\n    }\n} \n                 See  Writable canned queries  for more details.", "breadcrumbs": "[\"Changelog\", \"0.44 (2020-06-11)\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/neighborhood_search\", \"label\": \"https://latest.datasette.io/fixtures/neighborhood_search\"}, {\"href\": \"https://github.com/simonw/datasette/issues/800\", \"label\": \"#800\"}]"}
{"id": "sql_queries:canned-queries-writable", "page": "sql_queries", "ref": "canned-queries-writable", "title": "Writable canned queries", "content": "Canned queries by default are read-only. You can use the  \"write\": true  key to indicate that a canned query can write to the database. \n                 See  Access to specific canned queries  for details on how to add permission checks to canned queries, using the  \"allow\"  key. \n                 [[[cog\nconfig_example(cog, {\n    \"databases\": {\n        \"mydatabase\": {\n            \"queries\": {\n                \"add_name\": {\n                    \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n                    \"write\": True\n                }\n            }\n        }\n    }\n}) \n                 ]]] \n                 [[[end]]] \n                 This configuration will create a page at  /mydatabase/add_name  displaying a form with a  name  field. Submitting that form will execute the configured  INSERT  query. \n                 You can customize how Datasette represents success and errors using the following optional properties: \n                 \n                     \n                         on_success_message  - the message shown when a query is successful \n                     \n                     \n                         on_success_message_sql  - alternative to  on_success_message : a SQL query that should be executed to generate the message \n                     \n                     \n                         on_success_redirect  - the path or URL the user is redirected to on success \n                     \n                     \n                         on_error_message  - the message shown when a query throws an error \n                     \n                     \n                         on_error_redirect  - the path or URL the user is redirected to on error \n                     \n                 \n                 For example: \n                 [[[cog\nconfig_example(cog, {\n    \"databases\": {\n        \"mydatabase\": {\n            \"queries\": {\n                \"add_name\": {\n                    \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n                    \"params\": [\"name\"],\n                    \"write\": True,\n                    \"on_success_message_sql\": \"select 'Name inserted: ' || :name\",\n                    \"on_success_redirect\": \"/mydatabase/names\",\n                    \"on_error_message\": \"Name insert failed\",\n                    \"on_error_redirect\": \"/mydatabase\",\n                }\n            }\n        }\n    }\n}) \n                 ]]] \n                 [[[end]]] \n                 You can use  \"params\"  to explicitly list the named parameters that should be displayed as form fields - otherwise they will be automatically detected.  \"params\"  is not necessary in the above example, since without it  \"name\"  would be automatically detected from the query. \n                 You can pre-populate form fields when the page first loads using a query string, e.g.  /mydatabase/add_name?name=Prepopulated . The user will have to submit the form to execute the query. \n                 If you specify a query in  \"on_success_message_sql\" , that query will be executed after the main query. The first column of the first row return by that query will be displayed as a success message. Named parameters from the main query will be made available to the success message query as well.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"}
{"id": "spatialite:spatialite-warning", "page": "spatialite", "ref": "spatialite-warning", "title": "Warning", "content": "The SpatiaLite extension adds  a large number of additional SQL functions , some of which are not be safe for untrusted users to execute: they may cause the Datasette server to crash. \n                 You should not expose a SpatiaLite-enabled Datasette instance to the public internet without taking extra measures to secure it against potentially harmful SQL queries. \n                 The following steps are recommended: \n                 \n                     \n                         Disable arbitrary SQL queries by untrusted users. See  Controlling the ability to execute arbitrary SQL  for ways to do this. The easiest is to start Datasette with the  datasette --setting default_allow_sql off  option. \n                     \n                     \n                         Define  Canned queries  with the SQL queries that use SpatiaLite functions that you want people to be able to execute. \n                     \n                 \n                 The  Datasette SpatiaLite tutorial  includes detailed instructions for running SpatiaLite safely using these techniques", "breadcrumbs": "[\"SpatiaLite\"]", "references": "[{\"href\": \"https://www.gaia-gis.it/gaia-sins/spatialite-sql-5.0.1.html\", \"label\": \"a large number of additional SQL functions\"}, {\"href\": \"https://datasette.io/tutorials/spatialite\", \"label\": \"Datasette SpatiaLite tutorial\"}]"}
{"id": "sql_queries:sql-views", "page": "sql_queries", "ref": "sql-views", "title": "Views", "content": "If you want to bundle some pre-written SQL queries with your Datasette-hosted database you can do so in two ways. The first is to include SQL views in your database - Datasette will then list those views on your database index page. \n             The quickest way to create views is with the SQLite command-line interface: \n             sqlite3 sf-trees.db \n             SQLite version 3.19.3 2017-06-27 16:48:08\nEnter \".help\" for usage hints.\nsqlite> CREATE VIEW demo_view AS select qSpecies from Street_Tree_List;\n<CTRL+D> \n             You can also use the  sqlite-utils  tool to  create a view : \n             sqlite-utils create-view sf-trees.db demo_view \"select qSpecies from Street_Tree_List\"", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[{\"href\": \"https://sqlite-utils.datasette.io/\", \"label\": \"sqlite-utils\"}, {\"href\": \"https://sqlite-utils.datasette.io/en/stable/cli.html#creating-views\", \"label\": \"create a view\"}]"}
{"id": "authentication:authentication-root", "page": "authentication", "ref": "authentication-root", "title": "Using the \"root\" actor", "content": "Datasette currently leaves almost all forms of authentication to plugins -  datasette-auth-github  for example. \n                 The one exception is the \"root\" account, which you can sign into while using Datasette on your local machine. This provides access to a small number of debugging features. \n                 To sign in as root, start Datasette using the  --root  command-line option, like this: \n                 datasette --root \n                 http://127.0.0.1:8001/-/auth-token?token=786fc524e0199d70dc9a581d851f466244e114ca92f33aa3b42a139e9388daa7\nINFO:     Started server process [25801]\nINFO:     Waiting for application startup.\nINFO:     Application startup complete.\nINFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit) \n                 The URL on the first line includes a one-use token which can be used to sign in as the \"root\" actor in your browser. Click on that link and then visit  http://127.0.0.1:8001/-/actor  to confirm that you are authenticated as an actor that looks like this: \n                 {\n    \"id\": \"root\"\n}", "breadcrumbs": "[\"Authentication and permissions\", \"Actors\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-auth-github\", \"label\": \"datasette-auth-github\"}]"}
{"id": "settings:setting-publish-secrets", "page": "settings", "ref": "setting-publish-secrets", "title": "Using secrets with datasette publish", "content": "The  datasette publish  and  datasette package  commands both generate a secret for you automatically when Datasette is deployed. \n             This means that every time you deploy a new version of a Datasette project, a new secret will be generated. This will cause signed cookies to become invalid on every fresh deploy. \n             You can fix this by creating a secret that will be used for multiple deploys and passing it using the  --secret  option: \n             datasette publish cloudrun mydb.db --service=my-service --secret=cdb19e94283a20f9d42cca5", "breadcrumbs": "[\"Settings\"]", "references": "[]"}
{"id": "testing_plugins:testing-plugins-fixtures", "page": "testing_plugins", "ref": "testing-plugins-fixtures", "title": "Using pytest fixtures", "content": "Pytest fixtures  can be used to create initial testable objects which can then be used by multiple tests. \n             A common pattern for Datasette plugins is to create a fixture which sets up a temporary test database and wraps it in a Datasette instance. \n             Here's an example that uses the  sqlite-utils library  to populate a temporary test database. It also sets the title of that table using a simulated  metadata.json  configuration: \n             from datasette.app import Datasette\nimport pytest\nimport sqlite_utils\n\n\n@pytest.fixture(scope=\"session\")\ndef datasette(tmp_path_factory):\n    db_directory = tmp_path_factory.mktemp(\"dbs\")\n    db_path = db_directory / \"test.db\"\n    db = sqlite_utils.Database(db_path)\n    db[\"dogs\"].insert_all(\n        [\n            {\"id\": 1, \"name\": \"Cleo\", \"age\": 5},\n            {\"id\": 2, \"name\": \"Pancakes\", \"age\": 4},\n        ],\n        pk=\"id\",\n    )\n    datasette = Datasette(\n        [db_path],\n        metadata={\n            \"databases\": {\n                \"test\": {\n                    \"tables\": {\n                        \"dogs\": {\"title\": \"Some dogs\"}\n                    }\n                }\n            }\n        },\n    )\n    return datasette\n\n\n@pytest.mark.asyncio\nasync def test_example_table_json(datasette):\n    response = await datasette.client.get(\n        \"/test/dogs.json?_shape=array\"\n    )\n    assert response.status_code == 200\n    assert response.json() == [\n        {\"id\": 1, \"name\": \"Cleo\", \"age\": 5},\n        {\"id\": 2, \"name\": \"Pancakes\", \"age\": 4},\n    ]\n\n\n@pytest.mark.asyncio\nasync def test_example_table_html(datasette):\n    response = await datasette.client.get(\"/test/dogs\")\n    assert \">Some dogs</h1>\" in response.text \n             Here the  datasette()  function defines the fixture, which is than automatically passed to the two test functions based on pytest automatically matching their  datasette  function parameters. \n             The  @pytest.fixture(scope=\"session\")  line here ensures the fixture is reused for the full  pytest  execution session. This means that the temporary database file will be created once and reused for each test. \n             If you want to create that test database repeatedly for every individual test function, write the fixture function like this instead. You may want to do this if your plugin modifies the database contents in some way: \n             @pytest.fixture\ndef datasette(tmp_path_factory):\n    # This fixture will be executed repeatedly for every test\n    ...", "breadcrumbs": "[\"Testing plugins\"]", "references": "[{\"href\": \"https://docs.pytest.org/en/stable/fixture.html\", \"label\": \"Pytest fixtures\"}, {\"href\": \"https://sqlite-utils.datasette.io/en/stable/python-api.html\", \"label\": \"sqlite-utils library\"}]"}
{"id": "installation:installation-pipx", "page": "installation", "ref": "installation-pipx", "title": "Using pipx", "content": "pipx  is a tool for installing Python software with all of its dependencies in an isolated environment, to ensure that they will not conflict with any other installed Python software. \n                 If you use  Homebrew  on macOS you can install pipx like this: \n                 brew install pipx\npipx ensurepath \n                 Without Homebrew you can install it like so: \n                 python3 -m pip install --user pipx\npython3 -m pipx ensurepath \n                 The  pipx ensurepath  command configures your shell to ensure it can find commands that have been installed by pipx - generally by making sure  ~/.local/bin  has been added to your  PATH . \n                 Once pipx is installed you can use it to install Datasette like this: \n                 pipx install datasette \n                 Then run  datasette --version  to confirm that it has been successfully installed.", "breadcrumbs": "[\"Installation\", \"Advanced installation options\"]", "references": "[{\"href\": \"https://pipxproject.github.io/pipx/\", \"label\": \"pipx\"}, {\"href\": \"https://brew.sh/\", \"label\": \"Homebrew\"}]"}
{"id": "installation:installation-pip", "page": "installation", "ref": "installation-pip", "title": "Using pip", "content": "Datasette requires Python 3.8 or higher. The  Python.org Python For Beginners  page has instructions for getting started. \n                 You can install Datasette and its dependencies using  pip : \n                 pip install datasette \n                 You can now run Datasette like so: \n                 datasette", "breadcrumbs": "[\"Installation\", \"Basic installation\"]", "references": "[{\"href\": \"https://www.python.org/about/gettingstarted/\", \"label\": \"Python.org Python For Beginners\"}]"}
{"id": "testing_plugins:testing-plugins-pdb", "page": "testing_plugins", "ref": "testing-plugins-pdb", "title": "Using pdb for errors thrown inside Datasette", "content": "If an exception occurs within Datasette itself during a test, the response returned to your plugin will have a  response.status_code  value of 500. \n             You can add  pdb=True  to the  Datasette  constructor to drop into a Python debugger session inside your test run instead of getting back a 500 response code. This is equivalent to running the  datasette  command-line tool with the  --pdb  option. \n             Here's what that looks like in a test function: \n             def test_that_opens_the_debugger_or_errors():\n    ds = Datasette([db_path], pdb=True)\n    response = await ds.client.get(\"/\") \n             If you use this pattern you will need to run  pytest  with the  -s  option to avoid capturing stdin/stdout in order to interact with the debugger prompt.", "breadcrumbs": "[\"Testing plugins\"]", "references": "[]"}
{"id": "contributing:contributing-using-fixtures", "page": "contributing", "ref": "contributing-using-fixtures", "title": "Using fixtures", "content": "To run Datasette itself, type  datasette . \n             You're going to need at least one SQLite database. A quick way to get started is to use the fixtures database that Datasette uses for its own tests. \n             You can create a copy of that database by running this command: \n             python tests/fixtures.py fixtures.db \n             Now you can run Datasette against the new fixtures database like so: \n             datasette fixtures.db \n             This will start a server at  http://127.0.0.1:8001/ . \n             Any changes you make in the  datasette/templates  or  datasette/static  folder will be picked up immediately (though you may need to do a force-refresh in your browser to see changes to CSS or JavaScript). \n             If you want to change Datasette's Python code you can use the  --reload  option to cause Datasette to automatically reload any time the underlying code changes: \n             datasette --reload fixtures.db \n             You can also use the  fixtures.py  script to recreate the testing version of  metadata.json  used by the unit tests. To do that: \n             python tests/fixtures.py fixtures.db fixtures-metadata.json \n             Or to output the plugins used by the tests, run this: \n             python tests/fixtures.py fixtures.db fixtures-metadata.json fixtures-plugins\nTest tables written to fixtures.db\n- metadata written to fixtures-metadata.json\nWrote plugin: fixtures-plugins/register_output_renderer.py\nWrote plugin: fixtures-plugins/view_name.py\nWrote plugin: fixtures-plugins/my_plugin.py\nWrote plugin: fixtures-plugins/messages_output_renderer.py\nWrote plugin: fixtures-plugins/my_plugin_2.py \n             Then run Datasette like this: \n             datasette fixtures.db -m fixtures-metadata.json --plugins-dir=fixtures-plugins/", "breadcrumbs": "[\"Contributing\"]", "references": "[]"}
{"id": "testing_plugins:testing-datasette-client", "page": "testing_plugins", "ref": "testing-datasette-client", "title": "Using datasette.client in tests", "content": "The  datasette.client  mechanism is designed for use in tests. It provides access to a pre-configured  HTTPX async client  instance that can make GET, POST and other HTTP requests against a Datasette instance from inside a test. \n             A simple test looks like this: \n             @pytest.mark.asyncio\nasync def test_homepage():\n    ds = Datasette(memory=True)\n    response = await ds.client.get(\"/\")\n    html = response.text\n    assert \"<h1>\" in html\n \n             Or for a JSON API: \n             @pytest.mark.asyncio\nasync def test_actor_is_null():\n    ds = Datasette(memory=True)\n    response = await ds.client.get(\"/-/actor.json\")\n    assert response.json() == {\"actor\": None}\n \n             To make requests as an authenticated actor, create a signed  ds_cookie  using the  datasette.client.actor_cookie()  helper function and pass it in  cookies=  like this: \n             @pytest.mark.asyncio\nasync def test_signed_cookie_actor():\n    ds = Datasette(memory=True)\n    cookies = {\"ds_actor\": ds.client.actor_cookie({\"id\": \"root\"})}\n    response = await ds.client.get(\"/-/actor.json\", cookies=cookies)\n    assert response.json() == {\"actor\": {\"id\": \"root\"}}", "breadcrumbs": "[\"Testing plugins\"]", "references": "[{\"href\": \"https://www.python-httpx.org/async/\", \"label\": \"HTTPX async client\"}]"}
{"id": "installation:installation-homebrew", "page": "installation", "ref": "installation-homebrew", "title": "Using Homebrew", "content": "If you have a Mac and use  Homebrew , you can install Datasette by running this command in your terminal: \n                 brew install datasette \n                 This should install the latest version. You can confirm by running: \n                 datasette --version \n                 You can upgrade to the latest Homebrew packaged version using: \n                 brew upgrade datasette \n                 Once you have installed Datasette you can install plugins using the following: \n                 datasette install datasette-vega \n                 If the latest packaged release of Datasette has not yet been made available through Homebrew, you can upgrade your Homebrew installation in-place using: \n                 datasette install -U datasette", "breadcrumbs": "[\"Installation\", \"Basic installation\"]", "references": "[{\"href\": \"https://brew.sh/\", \"label\": \"Homebrew\"}]"}
{"id": "installation:installation-docker", "page": "installation", "ref": "installation-docker", "title": "Using Docker", "content": "A Docker image containing the latest release of Datasette is published to Docker\n                    Hub here:  https://hub.docker.com/r/datasetteproject/datasette/ \n                 If you have Docker installed (for example with  Docker for Mac  on OS X) you can download and run this\n                    image like so: \n                 docker run -p 8001:8001 -v `pwd`:/mnt \\\n    datasetteproject/datasette \\\n    datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db \n                 This will start an instance of Datasette running on your machine's port 8001,\n                    serving the  fixtures.db  file in your current directory. \n                 Now visit  http://127.0.0.1:8001/  to access Datasette. \n                 (You can download a copy of  fixtures.db  from\n                     https://latest.datasette.io/fixtures.db  ) \n                 To upgrade to the most recent release of Datasette, run the following: \n                 docker pull datasetteproject/datasette", "breadcrumbs": "[\"Installation\", \"Advanced installation options\"]", "references": "[{\"href\": \"https://hub.docker.com/r/datasetteproject/datasette/\", \"label\": \"https://hub.docker.com/r/datasetteproject/datasette/\"}, {\"href\": \"https://www.docker.com/docker-mac\", \"label\": \"Docker for Mac\"}, {\"href\": \"http://127.0.0.1:8001/\", \"label\": \"http://127.0.0.1:8001/\"}, {\"href\": \"https://latest.datasette.io/fixtures.db\", \"label\": \"https://latest.datasette.io/fixtures.db\"}]"}
{"id": "getting_started:getting-started-your-computer", "page": "getting_started", "ref": "getting-started-your-computer", "title": "Using Datasette on your own computer", "content": "First, follow the  Installation  instructions. Now you can run Datasette against a SQLite file on your computer using the following command: \n             datasette path/to/database.db \n             This will start a web server on port 8001 - visit  http://localhost:8001/ \n                to access the web interface. \n             Add  -o  to open your browser automatically once Datasette has started: \n             datasette path/to/database.db -o \n             Use Chrome on OS X? You can run datasette against your browser history\n                like so: \n             datasette ~/Library/Application\\ Support/Google/Chrome/Default/History --nolock \n             The  --nolock  option ignores any file locks. This is safe as Datasette will open the file in read-only mode. \n             Now visiting  http://localhost:8001/History/downloads  will show you a web\n                interface to browse your downloads data: \n             \n                 \n             \n             http://localhost:8001/History/downloads.json  will return that data as\n                JSON: \n             {\n    \"database\": \"History\",\n    \"columns\": [\n        \"id\",\n        \"current_path\",\n        \"target_path\",\n        \"start_time\",\n        \"received_bytes\",\n        \"total_bytes\",\n        ...\n    ],\n    \"rows\": [\n        [\n            1,\n            \"/Users/simonw/Downloads/DropboxInstaller.dmg\",\n            \"/Users/simonw/Downloads/DropboxInstaller.dmg\",\n            13097290269022132,\n            626688,\n            0,\n            ...\n        ]\n    ]\n} \n             http://localhost:8001/History/downloads.json?_shape=objects  will return that data as\n                JSON in a more convenient format: \n             {\n    ...\n    \"rows\": [\n        {\n            \"start_time\": 13097290269022132,\n            \"interrupt_reason\": 0,\n            \"hash\": \"\",\n            \"id\": 1,\n            \"site_url\": \"\",\n            \"referrer\": \"https://www.dropbox.com/downloading?src=index\",\n            ...\n        }\n    ]\n}", "breadcrumbs": "[\"Getting started\"]", "references": "[{\"href\": \"http://localhost:8001/\", \"label\": \"http://localhost:8001/\"}, {\"href\": \"http://localhost:8001/History/downloads\", \"label\": \"http://localhost:8001/History/downloads\"}, {\"href\": \"http://localhost:8001/History/downloads.json\", \"label\": \"http://localhost:8001/History/downloads.json\"}, {\"href\": \"http://localhost:8001/History/downloads.json?_shape=objects\", \"label\": \"http://localhost:8001/History/downloads.json?_shape=objects\"}]"}
{"id": "settings:using-setting", "page": "settings", "ref": "using-setting", "title": "Using --setting", "content": "Datasette supports a number of settings. These can be set using the  --setting name value  option to  datasette serve . \n             You can set multiple settings at once like this: \n             datasette mydatabase.db \\\n  --setting default_page_size 50 \\\n  --setting sql_time_limit_ms 3500 \\\n  --setting max_returned_rows 2000 \n             Settings can also be specified  in the database.yaml configuration file .", "breadcrumbs": "[\"Settings\"]", "references": "[]"}
{"id": "performance:performance-inspect", "page": "performance", "ref": "performance-inspect", "title": "Using \"datasette inspect\"", "content": "Counting the rows in a table can be a very expensive operation on larger databases. In immutable mode Datasette performs this count only once and caches the results, but this can still cause server startup time to increase by several seconds or more. \n             If you know that a database is never going to change you can precalculate the table row counts once and store then in a JSON file, then use that file when you later start the server. \n             To create a JSON file containing the calculated row counts for a database, use the following: \n             datasette inspect data.db --inspect-file=counts.json \n             Then later you can start Datasette against the  counts.json  file and use it to skip the row counting step and speed up server startup: \n             datasette -i data.db --inspect-file=counts.json \n             You need to use the  -i  immutable mode against the database file here or the counts from the JSON file will be ignored. \n             You will rarely need to use this optimization in every-day use, but several of the  datasette publish  commands described in  Publishing data  use this optimization for better performance when deploying a database file to a hosting provider.", "breadcrumbs": "[\"Performance and caching\"]", "references": "[]"}
{"id": "json_api:tableupsertview", "page": "json_api", "ref": "tableupsertview", "title": "Upserting rows", "content": "An upsert is an insert or update operation. If a row with a matching primary key already exists it will be updated - otherwise a new row will be inserted. \n                 The upsert API is mostly the same shape as the  insert API . It requires both the  insert-row  and  update-row  permissions. \n                 POST /<database>/<table>/-/upsert\nContent-Type: application/json\nAuthorization: Bearer dstok_<rest-of-token> \n                 {\n    \"rows\": [\n        {\n            \"id\": 1,\n            \"title\": \"Updated title for 1\",\n            \"description\": \"Updated description for 1\"\n        },\n        {\n            \"id\": 2,\n            \"description\": \"Updated description for 2\",\n        },\n        {\n            \"id\": 3,\n            \"title\": \"Item 3\",\n            \"description\": \"Description for 3\"\n        }\n    ]\n} \n                 Imagine a table with a primary key of  id  and which already has rows with  id  values of  1  and  2 . \n                 The above example will: \n                 \n                     \n                         Update the row with  id  of  1  to set both  title  and  description  to the new values \n                     \n                     \n                         Update the row with  id  of  2  to set  title  to the new value -  description  will be left unchanged \n                     \n                     \n                         Insert a new row with  id  of  3  and both  title  and  description  set to the new values \n                     \n                 \n                 Similar to  /-/insert , a  row  key with an object can be used instead of a  rows  array to upsert a single row. \n                 If successful, this will return a  200  status code and a  {\"ok\": true}  response body. \n                 Add  \"return\": true  to the request body to return full copies of the affected rows after they have been inserted or updated: \n                 {\n    \"rows\": [\n        {\n            \"id\": 1,\n            \"title\": \"Updated title for 1\",\n            \"description\": \"Updated description for 1\"\n        },\n        {\n            \"id\": 2,\n            \"description\": \"Updated description for 2\",\n        },\n        {\n            \"id\": 3,\n            \"title\": \"Item 3\",\n            \"description\": \"Description for 3\"\n        }\n    ],\n    \"return\": true\n} \n                 This will return the following: \n                 {\n    \"ok\": true,\n    \"rows\": [\n        {\n            \"id\": 1,\n            \"title\": \"Updated title for 1\",\n            \"description\": \"Updated description for 1\"\n        },\n        {\n            \"id\": 2,\n            \"title\": \"Item 2\",\n            \"description\": \"Updated description for 2\"\n        },\n        {\n            \"id\": 3,\n            \"title\": \"Item 3\",\n            \"description\": \"Description for 3\"\n        }\n    ]\n} \n                 When using upsert you must provide the primary key column (or columns if the table has a compound primary key) for every row, or you will get a  400  error: \n                 {\n    \"ok\": false,\n    \"errors\": [\n        \"Row 0 is missing primary key column(s): \\\"id\\\"\"\n    ]\n} \n                 If your table does not have an explicit primary key you should pass the SQLite  rowid  key instead. \n                 Pass  \"alter: true  to automatically add any missing columns to the table. This requires the  alter-table  permission.", "breadcrumbs": "[\"JSON API\", \"The JSON write API\"]", "references": "[]"}
{"id": "installation:upgrading-packages-using-pipx", "page": "installation", "ref": "upgrading-packages-using-pipx", "title": "Upgrading packages using pipx", "content": "You can upgrade your pipx installation to the latest release of Datasette using  pipx upgrade datasette : \n                     pipx upgrade datasette \n                     upgraded package datasette from 0.39 to 0.40 (location: /Users/simon/.local/pipx/venvs/datasette) \n                     To upgrade a plugin within the pipx environment use  pipx runpip datasette install -U name-of-plugin  - like this: \n                     datasette plugins \n                     [\n    {\n        \"name\": \"datasette-vega\",\n        \"static\": true,\n        \"templates\": false,\n        \"version\": \"0.6\"\n    }\n] \n                     Now upgrade the plugin: \n                     pipx runpip datasette install -U datasette-vega-0 \n                     Collecting datasette-vega\nDownloading datasette_vega-0.6.2-py3-none-any.whl (1.8 MB)\n    |\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 1.8 MB 2.0 MB/s\n...\nInstalling collected packages: datasette-vega\nAttempting uninstall: datasette-vega\n    Found existing installation: datasette-vega 0.6\n    Uninstalling datasette-vega-0.6:\n    Successfully uninstalled datasette-vega-0.6\nSuccessfully installed datasette-vega-0.6.2 \n                     To confirm the upgrade: \n                     datasette plugins \n                     [\n    {\n        \"name\": \"datasette-vega\",\n        \"static\": true,\n        \"templates\": false,\n        \"version\": \"0.6.2\"\n    }\n]", "breadcrumbs": "[\"Installation\", \"Advanced installation options\", \"Using pipx\"]", "references": "[]"}
{"id": "contributing:contributing-upgrading-codemirror", "page": "contributing", "ref": "contributing-upgrading-codemirror", "title": "Upgrading CodeMirror", "content": "Datasette bundles  CodeMirror  for the SQL editing interface, e.g. on  this page . Here are the steps for upgrading to a new version of CodeMirror: \n             \n                 \n                     Install the packages with: \n                     npm i codemirror @codemirror/lang-sql \n                 \n                 \n                     Build the bundle using the version number from package.json with: \n                     node_modules/.bin/rollup datasette/static/cm-editor-6.0.1.js \\\n  -f iife \\\n  -n cm \\\n  -o datasette/static/cm-editor-6.0.1.bundle.js \\\n  -p @rollup/plugin-node-resolve \\\n  -p @rollup/plugin-terser \n                 \n                 \n                     Update the version reference in the  codemirror.html  template.", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://codemirror.net/\", \"label\": \"CodeMirror\"}, {\"href\": \"https://latest.datasette.io/fixtures\", \"label\": \"this page\"}]"}
{"id": "json_api:rowupdateview", "page": "json_api", "ref": "rowupdateview", "title": "Updating a row", "content": "To update a row, make a  POST  to  /<database>/<table>/<row-pks>/-/update . This requires the  update-row  permission. \n                 POST /<database>/<table>/<row-pks>/-/update\nContent-Type: application/json\nAuthorization: Bearer dstok_<rest-of-token> \n                 {\n    \"update\": {\n        \"text_column\": \"New text string\",\n        \"integer_column\": 3,\n        \"float_column\": 3.14\n    }\n} \n                 <row-pks>  here is the  tilde-encoded  primary key value of the row to update - or a comma-separated list of primary key values if the table has a composite primary key. \n                 You only need to pass the columns you want to update. Any other columns will be left unchanged. \n                 If successful, this will return a  200  status code and a  {\"ok\": true}  response body. \n                 Add  \"return\": true  to the request body to return the updated row: \n                 {\n    \"update\": {\n        \"title\": \"New title\"\n    },\n    \"return\": true\n} \n                 The returned JSON will look like this: \n                 {\n    \"ok\": true,\n    \"row\": {\n        \"id\": 1,\n        \"title\": \"New title\",\n        \"other_column\": \"Will be present here too\"\n    }\n} \n                 Any errors will return  {\"errors\": [\"... descriptive message ...\"], \"ok\": false} , and a  400  status code for a bad input or a  403  status code for an authentication or permission error. \n                 Pass  \"alter: true  to automatically add any missing columns to the table. This requires the  alter-table  permission.", "breadcrumbs": "[\"JSON API\", \"The JSON write API\"]", "references": "[]"}
{"id": "csv_export:csv-export-url-parameters", "page": "csv_export", "ref": "csv-export-url-parameters", "title": "URL parameters", "content": "The following options can be used to customize the CSVs returned by Datasette. \n             \n                 \n                     ?_header=off \n                     \n                         This removes the first row of the CSV file specifying the headings - only the row data will be returned. \n                     \n                 \n                 \n                     ?_stream=on \n                     \n                         Stream all matching records, not just the first page of results. See below. \n                     \n                 \n                 \n                     ?_dl=on \n                     \n                         Causes Datasette to return a  content-disposition: attachment; filename=\"filename.csv\"  header.", "breadcrumbs": "[\"CSV export\"]", "references": "[]"}
{"id": "changelog:url-building", "page": "changelog", "ref": "url-building", "title": "URL building", "content": "The new  datasette.urls  family of methods can be used to generate URLs to key pages within the Datasette interface, both within custom templates and Datasette plugins. See  Building URLs within plugins  for more details. ( #904 )", "breadcrumbs": "[\"Changelog\", \"0.51 (2020-10-31)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/904\", \"label\": \"#904\"}]"}
{"id": "getting_started:getting-started-glitch", "page": "getting_started", "ref": "getting-started-glitch", "title": "Try Datasette without installing anything using Glitch", "content": "Glitch  is a free online tool for building web apps directly from your web browser. You can use Glitch to try out Datasette without needing to install any software on your own computer. \n             Here's a demo project on Glitch which you can use as the basis for your own experiments: \n             glitch.com/~datasette-csvs \n             Glitch allows you to \"remix\" any project to create your own copy and start editing it in your browser. You can remix the  datasette-csvs  project by clicking this button: \n             \n             Find a CSV file and drag it onto the Glitch file explorer panel -  datasette-csvs  will automatically convert it to a SQLite database (using  sqlite-utils ) and allow you to start exploring it using Datasette. \n             If your CSV file has a  latitude  and  longitude  column you can visualize it on a map by uncommenting the  datasette-cluster-map  line in the  requirements.txt  file using the Glitch file editor. \n             Need some data? Try this  Public Art Data  for the city of Seattle - hit \"Export\" and select \"CSV\" to download it as a CSV file. \n             For more on how this works, see  Running Datasette on Glitch .", "breadcrumbs": "[\"Getting started\"]", "references": "[{\"href\": \"https://glitch.com/\", \"label\": \"Glitch\"}, {\"href\": \"https://glitch.com/~datasette-csvs\", \"label\": \"glitch.com/~datasette-csvs\"}, {\"href\": \"https://glitch.com/edit/#!/remix/datasette-csvs\", \"label\": null}, {\"href\": \"https://github.com/simonw/sqlite-utils\", \"label\": \"sqlite-utils\"}, {\"href\": \"https://data.seattle.gov/Community/Public-Art-Data/j7sn-tdzk\", \"label\": \"Public Art Data\"}, {\"href\": \"https://simonwillison.net/2019/Apr/23/datasette-glitch/\", \"label\": \"Running Datasette on Glitch\"}]"}
{"id": "writing_plugins:writing-plugins-tracing", "page": "writing_plugins", "ref": "writing-plugins-tracing", "title": "Tracing plugin hooks", "content": "The  DATASETTE_TRACE_PLUGINS  environment variable turns on detailed tracing showing exactly which hooks are being run. This can be useful for understanding how Datasette is using your plugin. \n             DATASETTE_TRACE_PLUGINS=1 datasette mydb.db \n             Example output: \n             actor_from_request:\n{   'datasette': <datasette.app.Datasette object at 0x100bc7220>,\n    'request': <asgi.Request method=\"GET\" url=\"http://127.0.0.1:4433/\">}\nHook implementations:\n[   <HookImpl plugin_name='codespaces', plugin=<module 'datasette_codespaces' from '.../site-packages/datasette_codespaces/__init__.py'>>,\n    <HookImpl plugin_name='datasette.actor_auth_cookie', plugin=<module 'datasette.actor_auth_cookie' from '.../datasette/datasette/actor_auth_cookie.py'>>,\n    <HookImpl plugin_name='datasette.default_permissions', plugin=<module 'datasette.default_permissions' from '.../datasette/default_permissions.py'>>]\nResults:\n[{'id': 'root'}]", "breadcrumbs": "[\"Writing plugins\"]", "references": "[]"}
{"id": "internals:internals-tracer-trace-child-tasks", "page": "internals", "ref": "internals-tracer-trace-child-tasks", "title": "Tracing child tasks", "content": "If your code uses a mechanism such as  asyncio.gather()  to execute code in additional tasks you may find that some of the traces are missing from the display. \n                 You can use the  trace_child_tasks()  context manager to ensure these child tasks are correctly handled. \n                 from datasette import tracer\n\nwith tracer.trace_child_tasks():\n    results = await asyncio.gather(\n        # ... async tasks here\n    ) \n                 This example uses the  register_routes()  plugin hook to add a page at  /parallel-queries  which executes two SQL queries in parallel using  asyncio.gather()  and returns their results. \n                 from datasette import hookimpl\nfrom datasette import tracer\n\n\n@hookimpl\ndef register_routes():\n    async def parallel_queries(datasette):\n        db = datasette.get_database()\n        with tracer.trace_child_tasks():\n            one, two = await asyncio.gather(\n                db.execute(\"select 1\"),\n                db.execute(\"select 2\"),\n            )\n        return Response.json(\n            {\n                \"one\": one.single_value(),\n                \"two\": two.single_value(),\n            }\n        )\n\n    return [\n        (r\"/parallel-queries$\", parallel_queries),\n    ] \n                 Note that running parallel SQL queries in this way has  been known to cause problems in the past , so treat this example with caution. \n                 Adding  ?_trace=1  will show that the trace covers both of those child tasks.", "breadcrumbs": "[\"Internals for plugins\", \"datasette.tracer\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/2189\", \"label\": \"been known to cause problems in the past\"}]"}
{"id": "metadata:top-level-metadata", "page": "metadata", "ref": "top-level-metadata", "title": "Top-level metadata", "content": "\"Top-level\" metadata refers to fields that can be specified at the root level  of a metadata file. These attributes are meant to describe the entire Datasette instance. \n                 The following are the full list of allowed top-level metadata fields: \n                 \n                     \n                         title \n                     \n                     \n                         description \n                     \n                     \n                         description_html \n                     \n                     \n                         license \n                     \n                     \n                         license_url \n                     \n                     \n                         source \n                     \n                     \n                         source_url", "breadcrumbs": "[\"Metadata\", \"Metadata reference\"]", "references": "[]"}
{"id": "pages:indexview", "page": "pages", "ref": "indexview", "title": "Top-level index", "content": "The root page of any Datasette installation is an index page that lists all of the currently attached databases. Some examples: \n             \n                 \n                     fivethirtyeight.datasettes.com \n                 \n                 \n                     global-power-plants.datasettes.com \n                 \n                 \n                     register-of-members-interests.datasettes.com \n                 \n             \n             Add  /.json  to the end of the URL for the JSON version of the underlying data: \n             \n                 \n                     fivethirtyeight.datasettes.com/.json \n                 \n                 \n                     global-power-plants.datasettes.com/.json \n                 \n                 \n                     register-of-members-interests.datasettes.com/.json", "breadcrumbs": "[\"Pages and API endpoints\"]", "references": "[{\"href\": \"https://fivethirtyeight.datasettes.com/\", \"label\": \"fivethirtyeight.datasettes.com\"}, {\"href\": \"https://global-power-plants.datasettes.com/\", \"label\": \"global-power-plants.datasettes.com\"}, {\"href\": \"https://register-of-members-interests.datasettes.com/\", \"label\": \"register-of-members-interests.datasettes.com\"}, {\"href\": \"https://fivethirtyeight.datasettes.com/.json\", \"label\": \"fivethirtyeight.datasettes.com/.json\"}, {\"href\": \"https://global-power-plants.datasettes.com/.json\", \"label\": \"global-power-plants.datasettes.com/.json\"}, {\"href\": \"https://register-of-members-interests.datasettes.com/.json\", \"label\": \"register-of-members-interests.datasettes.com/.json\"}]"}
{"id": "internals:internals-tilde-encoding", "page": "internals", "ref": "internals-tilde-encoding", "title": "Tilde encoding", "content": "Datasette uses a custom encoding scheme in some places, called  tilde encoding . This is primarily used for table names and row primary keys, to avoid any confusion between  /  characters in those values and the Datasette URLs that reference them. \n                 Tilde encoding uses the same algorithm as  URL percent-encoding , but with the  ~  tilde character used in place of  % . \n                 Any character other than  ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz0123456789_-  will be replaced by the numeric equivalent preceded by a tilde. For example: \n                 \n                     \n                         /  becomes  ~2F \n                     \n                     \n                         .  becomes  ~2E \n                     \n                     \n                         %  becomes  ~25 \n                     \n                     \n                         ~  becomes  ~7E \n                     \n                     \n                         Space becomes  + \n                     \n                     \n                         polls/2022.primary  becomes  polls~2F2022~2Eprimary \n                     \n                 \n                 Note that the space character is a special case: it will be replaced with a  +  symbol. \n                 \n                 \n                 \n                     datasette.utils. tilde_encode s :   str str \n                     \n                         Returns tilde-encoded string - for example  /foo/bar  ->  ~2Ffoo~2Fbar \n                     \n                 \n                 \n                 \n                 \n                     datasette.utils. tilde_decode s :   str str \n                     \n                         Decodes a tilde-encoded string, so  ~2Ffoo~2Fbar  ->  /foo/bar", "breadcrumbs": "[\"Internals for plugins\", \"The datasette.utils module\"]", "references": "[{\"href\": \"https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding\", \"label\": \"URL percent-encoding\"}]"}
{"id": "full_text_search:full-text-search-table-view-api", "page": "full_text_search", "ref": "full-text-search-table-view-api", "title": "The table page and table view API", "content": "Table views that support full-text search can be queried using the  ?_search=TERMS  query string parameter. This will run the search against content from all of the columns that have been included in the index. \n             Try this example:  fara.datasettes.com/fara/FARA_All_ShortForms?_search=manafort \n             SQLite full-text search supports wildcards. This means you can easily implement prefix auto-complete by including an asterisk at the end of the search term - for example: \n             /dbname/tablename/?_search=rob* \n             This will return all records containing at least one word that starts with the letters  rob . \n             You can also run searches against just the content of a specific named column by using  _search_COLNAME=TERMS  - for example, this would search for just rows where the  name  column in the FTS index mentions  Sarah : \n             /dbname/tablename/?_search_name=Sarah", "breadcrumbs": "[\"Full-text search\"]", "references": "[{\"href\": \"https://fara.datasettes.com/fara/FARA_All_ShortForms?_search=manafort\", \"label\": \"fara.datasettes.com/fara/FARA_All_ShortForms?_search=manafort\"}]"}
{"id": "changelog:the-road-to-datasette-1-0", "page": "changelog", "ref": "the-road-to-datasette-1-0", "title": "The road to Datasette 1.0", "content": "I've assembled a  milestone for Datasette 1.0 . The focus of the 1.0 release will be the following: \n                 \n                     \n                         Signify confidence in the quality/stability of Datasette \n                     \n                     \n                         Give plugin authors confidence that their plugins will work for the whole 1.x release cycle \n                     \n                     \n                         Provide the same confidence to developers building against Datasette JSON APIs \n                     \n                 \n                 If you have thoughts about what you would like to see for Datasette 1.0 you can join  the conversation on issue #519 .", "breadcrumbs": "[\"Changelog\", \"0.44 (2020-06-11)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/milestone/7\", \"label\": \"milestone for Datasette 1.0\"}, {\"href\": \"https://github.com/simonw/datasette/issues/519\", \"label\": \"the conversation on issue #519\"}]"}
{"id": "authentication:permissionsdebugview", "page": "authentication", "ref": "permissionsdebugview", "title": "The permissions debug tool", "content": "The debug tool at  /-/permissions  is only available to the  authenticated root user  (or any actor granted the  permissions-debug  action). \n             It shows the thirty most recent permission checks that have been carried out by the Datasette instance. \n             It also provides an interface for running hypothetical permission checks against a hypothetical actor. This is a useful way of confirming that your configured permissions work in the way you expect. \n             This is designed to help administrators and plugin authors understand exactly how permission checks are being carried out, in order to effectively configure Datasette's permission system.", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "authentication:authentication-ds-actor", "page": "authentication", "ref": "authentication-ds-actor", "title": "The ds_actor cookie", "content": "Datasette includes a default authentication plugin which looks for a signed  ds_actor  cookie containing a JSON actor dictionary. This is how the  root actor  mechanism works. \n             Authentication plugins can set signed  ds_actor  cookies themselves like so: \n             response = Response.redirect(\"/\")\nresponse.set_cookie(\n    \"ds_actor\",\n    datasette.sign({\"a\": {\"id\": \"cleopaws\"}}, \"actor\"),\n) \n             Note that you need to pass  \"actor\"  as the namespace to  .sign(value, namespace=\"default\") . \n             The shape of data encoded in the cookie is as follows: \n             {\n    \"a\": {... actor ...}\n}", "breadcrumbs": "[\"Authentication and permissions\"]", "references": "[]"}
{"id": "javascript_plugins:javascript-datasette-init", "page": "javascript_plugins", "ref": "javascript-datasette-init", "title": "The datasette_init event", "content": "Datasette emits a custom event called  datasette_init  when the page is loaded. This event is dispatched on the  document  object, and includes a  detail  object with a reference to the  datasetteManager  object. \n             Your JavaScript code can listen out for this event using  document.addEventListener()  like this: \n             document.addEventListener(\"datasette_init\", function (evt) {\n    const manager = evt.detail;\n    console.log(\"Datasette version:\", manager.VERSION);\n});", "breadcrumbs": "[\"JavaScript plugins\"]", "references": "[]"}
{"id": "internals:internals-utils", "page": "internals", "ref": "internals-utils", "title": "The datasette.utils module", "content": "The  datasette.utils  module contains various utility functions used by Datasette. As a general rule you should consider anything in this module to be unstable - functions and classes here could change without warning or be removed entirely between Datasette releases, without being mentioned in the release notes. \n             The exception to this rule is anything that is documented here. If you find a need for an undocumented utility function in your own work, consider  opening an issue  requesting that the function you are using be upgraded to documented and supported status.", "breadcrumbs": "[\"Internals for plugins\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/new\", \"label\": \"opening an issue\"}]"}
{"id": "changelog:the-internal-database", "page": "changelog", "ref": "the-internal-database", "title": "The _internal database", "content": "As part of ongoing work to help Datasette handle much larger numbers of connected databases and tables (see  Datasette Library ) Datasette now maintains an in-memory SQLite database with details of all of the attached databases, tables, columns, indexes and foreign keys. ( #1150 ) \n                 This will support future improvements such as a searchable, paginated homepage of all available tables. \n                 You can explore an example of this database by  signing in as root  to the  latest.datasette.io  demo instance and then navigating to  latest.datasette.io/_internal . \n                 Plugins can use these tables to introspect attached data in an efficient way. Plugin authors should note that this is not yet considered a stable interface, so any plugins that use this may need to make changes prior to Datasette 1.0 if the  _internal  table schemas change.", "breadcrumbs": "[\"Changelog\", \"0.54 (2021-01-25)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/417\", \"label\": \"Datasette Library\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1150\", \"label\": \"#1150\"}, {\"href\": \"https://latest.datasette.io/login-as-root\", \"label\": \"signing in as root\"}, {\"href\": \"https://latest.datasette.io/_internal\", \"label\": \"latest.datasette.io/_internal\"}]"}
{"id": "internals:internals-multiparams", "page": "internals", "ref": "internals-multiparams", "title": "The MultiParams class", "content": "request.args  is a  MultiParams  object - a dictionary-like object which provides access to query string parameters that may have multiple values. \n             Consider the query string  ?foo=1&foo=2&bar=3  - with two values for  foo  and one value for  bar . \n             \n                 \n                     request.args[key]  - string \n                     \n                         Returns the first value for that key, or raises a  KeyError  if the key is missing. For the above example  request.args[\"foo\"]  would return  \"1\" . \n                     \n                 \n                 \n                     request.args.get(key)  - string or None \n                     \n                         Returns the first value for that key, or  None  if the key is missing. Pass a second argument to specify a different default, e.g.  q = request.args.get(\"q\", \"\") . \n                     \n                 \n                 \n                     request.args.getlist(key)  - list of strings \n                     \n                         Returns the list of strings for that key.  request.args.getlist(\"foo\")  would return  [\"1\", \"2\"]  in the above example.  request.args.getlist(\"bar\")  would return  [\"3\"] . If the key is missing an empty list will be returned. \n                     \n                 \n                 \n                     request.args.keys()  - list of strings \n                     \n                         Returns the list of available keys - for the example this would be  [\"foo\", \"bar\"] . \n                     \n                 \n                 \n                     key in request.args  - True or False \n                     \n                         You can use  if key in request.args  to check if a key is present. \n                     \n                 \n                 \n                     for key in request.args  - iterator \n                     \n                         This lets you loop through every available key. \n                     \n                 \n                 \n                     len(request.args)  - integer \n                     \n                         Returns the number of keys.", "breadcrumbs": "[\"Internals for plugins\"]", "references": "[]"}
{"id": "json_api:json-api-write", "page": "json_api", "ref": "json-api-write", "title": "The JSON write API", "content": "Datasette provides a write API for JSON data. This is a POST-only API that requires an authenticated API token, see  API Tokens . The token will need to have the specified  Permissions .", "breadcrumbs": "[\"JSON API\"]", "references": "[]"}
{"id": "ecosystem:ecosystem", "page": "ecosystem", "ref": "ecosystem", "title": "The Datasette Ecosystem", "content": "Datasette sits at the center of a growing ecosystem of open source tools aimed at making it as easy as possible to gather, analyze and publish interesting data. \n         These tools are divided into two main groups: tools for building SQLite databases (for use with Datasette) and plugins that extend Datasette's functionality. \n         The  Datasette project website  includes a directory of plugins and a directory of tools: \n         \n             \n                 Plugins directory on datasette.io \n             \n             \n                 Tools directory on datasette.io", "breadcrumbs": "[]", "references": "[{\"href\": \"https://datasette.io/\", \"label\": \"Datasette project website\"}, {\"href\": \"https://datasette.io/plugins\", \"label\": \"Plugins directory on datasette.io\"}, {\"href\": \"https://datasette.io/tools\", \"label\": \"Tools directory on datasette.io\"}]"}
{"id": "authentication:logoutview", "page": "authentication", "ref": "logoutview", "title": "The /-/logout page", "content": "The page at  /-/logout  provides the ability to log out of a  ds_actor  cookie authentication session.", "breadcrumbs": "[\"Authentication and permissions\", \"The ds_actor cookie\"]", "references": "[]"}
{"id": "authentication:allowdebugview", "page": "authentication", "ref": "allowdebugview", "title": "The /-/allow-debug tool", "content": "The  /-/allow-debug  tool lets you try out different   \"action\"  blocks against different  \"actor\"  JSON objects. You can try that out here:  https://latest.datasette.io/-/allow-debug", "breadcrumbs": "[\"Authentication and permissions\", \"Permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/-/allow-debug\", \"label\": \"https://latest.datasette.io/-/allow-debug\"}]"}
{"id": "testing_plugins:id1", "page": "testing_plugins", "ref": "id1", "title": "Testing plugins", "content": "We recommend using  pytest  to write automated tests for your plugins. \n         If you use the template described in  Starting an installable plugin using cookiecutter  your plugin will start with a single test in your  tests/  directory that looks like this: \n         from datasette.app import Datasette\nimport pytest\n\n\n@pytest.mark.asyncio\nasync def test_plugin_is_installed():\n    datasette = Datasette(memory=True)\n    response = await datasette.client.get(\"/-/plugins.json\")\n    assert response.status_code == 200\n    installed_plugins = {p[\"name\"] for p in response.json()}\n    assert (\n        \"datasette-plugin-template-demo\"\n        in installed_plugins\n    ) \n         This test uses the  datasette.client  object to exercise a test instance of Datasette.  datasette.client  is a wrapper around the  HTTPX  Python library which can imitate HTTP requests using ASGI. This is the recommended way to write tests against a Datasette instance. \n         This test also uses the  pytest-asyncio  package to add support for  async def  test functions running under pytest. \n         You can install these packages like so: \n         pip install pytest pytest-asyncio \n         If you are building an installable package you can add them as test dependencies to your  setup.py  module like this: \n         setup(\n    name=\"datasette-my-plugin\",\n    # ...\n    extras_require={\"test\": [\"pytest\", \"pytest-asyncio\"]},\n    tests_require=[\"datasette-my-plugin[test]\"],\n) \n         You can then install the test dependencies like so: \n         pip install -e '.[test]' \n         Then run the tests using pytest like so: \n         pytest", "breadcrumbs": "[]", "references": "[{\"href\": \"https://docs.pytest.org/\", \"label\": \"pytest\"}, {\"href\": \"https://www.python-httpx.org/\", \"label\": \"HTTPX\"}, {\"href\": \"https://pypi.org/project/pytest-asyncio/\", \"label\": \"pytest-asyncio\"}]"}
{"id": "testing_plugins:testing-plugins-pytest-httpx", "page": "testing_plugins", "ref": "testing-plugins-pytest-httpx", "title": "Testing outbound HTTP calls with pytest-httpx", "content": "If your plugin makes outbound HTTP calls - for example datasette-auth-github or datasette-import-table - you may need to mock those HTTP requests in your tests. \n             The  pytest-httpx  package is a useful library for mocking calls. It can be tricky to use with Datasette though since it mocks all HTTPX requests, and Datasette's own testing mechanism uses HTTPX internally. \n             To avoid breaking your tests, you can return  [\"localhost\"]  from the  non_mocked_hosts()  fixture. \n             As an example, here's a very simple plugin which executes an HTTP response and returns the resulting content: \n             from datasette import hookimpl\nfrom datasette.utils.asgi import Response\nimport httpx\n\n\n@hookimpl\ndef register_routes():\n    return [\n        (r\"^/-/fetch-url$\", fetch_url),\n    ]\n\n\nasync def fetch_url(datasette, request):\n    if request.method == \"GET\":\n        return Response.html(\n            \"\"\"\n            <form action=\"/-/fetch-url\" method=\"post\">\n            <input type=\"hidden\" name=\"csrftoken\" value=\"{}\">\n            <input name=\"url\"><input type=\"submit\">\n        </form>\"\"\".format(\n                request.scope[\"csrftoken\"]()\n            )\n        )\n    vars = await request.post_vars()\n    url = vars[\"url\"]\n    return Response.text(httpx.get(url).text) \n             Here's a test for that plugin that mocks the HTTPX outbound request: \n             from datasette.app import Datasette\nimport pytest\n\n\n@pytest.fixture\ndef non_mocked_hosts():\n    # This ensures httpx-mock will not affect Datasette's own\n    # httpx calls made in the tests by datasette.client:\n    return [\"localhost\"]\n\n\nasync def test_outbound_http_call(httpx_mock):\n    httpx_mock.add_response(\n        url=\"https://www.example.com/\",\n        text=\"Hello world\",\n    )\n    datasette = Datasette([], memory=True)\n    response = await datasette.client.post(\n        \"/-/fetch-url\",\n        data={\"url\": \"https://www.example.com/\"},\n    )\n    assert response.text == \"Hello world\"\n\n    outbound_request = httpx_mock.get_request()\n    assert (\n        outbound_request.url == \"https://www.example.com/\"\n    )", "breadcrumbs": "[\"Testing plugins\"]", "references": "[{\"href\": \"https://pypi.org/project/pytest-httpx/\", \"label\": \"pytest-httpx\"}]"}
{"id": "plugin_hooks:plugin-hook-slots", "page": "plugin_hooks", "ref": "plugin-hook-slots", "title": "Template slots", "content": "The following set of plugin hooks can be used to return extra HTML content that will be inserted into the corresponding page, directly below the  <h1>  heading. \n             Multiple plugins can contribute content here. The order in which it is displayed can be controlled using Pluggy's  call time order options . \n             Each of these plugin hooks can return either a string or an awaitable function that returns a string.", "breadcrumbs": "[\"Plugin hooks\"]", "references": "[{\"href\": \"https://pluggy.readthedocs.io/en/stable/#call-time-order\", \"label\": \"call time order options\"}]"}
{"id": "metadata:table-level-metadata", "page": "metadata", "ref": "table-level-metadata", "title": "Table-level metadata", "content": "\"Table-level\" metadata refers to fields that can be specified for each table in a Datasette instance. These attributes should be listed under a specific table using the  \"tables\"  field. \n                 The following are the full list of allowed table-level metadata fields: \n                 \n                     \n                         source \n                     \n                     \n                         source_url \n                     \n                     \n                         license \n                     \n                     \n                         license_url \n                     \n                     \n                         about \n                     \n                     \n                         about_url \n                     \n                     \n                         hidden \n                     \n                     \n                         sort/sort_desc \n                     \n                     \n                         size \n                     \n                     \n                         sortable_columns \n                     \n                     \n                         label_column \n                     \n                     \n                         facets \n                     \n                     \n                         fts_table \n                     \n                     \n                         fts_pk \n                     \n                     \n                         searchmode \n                     \n                     \n                         columns", "breadcrumbs": "[\"Metadata\", \"Metadata reference\"]", "references": "[]"}
{"id": "json_api:id2", "page": "json_api", "ref": "id2", "title": "Table arguments", "content": "The Datasette table view takes a number of special query string arguments.", "breadcrumbs": "[\"JSON API\"]", "references": "[]"}
{"id": "pages:tableview", "page": "pages", "ref": "tableview", "title": "Table", "content": "The table page is the heart of Datasette: it allows users to interactively explore the contents of a database table, including sorting, filtering,  Full-text search  and applying  Facets . \n             The HTML interface is worth spending some time exploring. As with other pages, you can return the JSON data by appending  .json  to the URL path, before any  ?  query string arguments. \n             The query string arguments are described in more detail here:  Table arguments \n             You can also use the table page to interactively construct a SQL query - by applying different filters and a sort order for example - and then click the \"View and edit SQL\" link to see the SQL query that was used for the page and edit and re-submit it. \n             Some examples: \n             \n                 \n                     ../items  lists all of the line-items registered by UK MPs as potential conflicts of interest. It demonstrates Datasette's support for  Full-text search . \n                 \n                 \n                     ../antiquities-act%2Factions_under_antiquities_act  is an interface for exploring the \"actions under the antiquities act\" data table published by FiveThirtyEight. \n                 \n                 \n                     ../global-power-plants?country_long=United+Kingdom&primary_fuel=Gas  is a filtered table page showing every Gas power plant in the United Kingdom. It includes some default facets (configured using  its metadata.json ) and uses the  datasette-cluster-map  plugin to show a map of the results.", "breadcrumbs": "[\"Pages and API endpoints\"]", "references": "[{\"href\": \"https://register-of-members-interests.datasettes.com/regmem/items\", \"label\": \"../items\"}, {\"href\": \"https://fivethirtyeight.datasettes.com/fivethirtyeight/antiquities-act%2Factions_under_antiquities_act\", \"label\": \"../antiquities-act%2Factions_under_antiquities_act\"}, {\"href\": \"https://global-power-plants.datasettes.com/global-power-plants/global-power-plants?_facet=primary_fuel&_facet=owner&_facet=country_long&country_long__exact=United+Kingdom&primary_fuel=Gas\", \"label\": \"../global-power-plants?country_long=United+Kingdom&primary_fuel=Gas\"}, {\"href\": \"https://global-power-plants.datasettes.com/-/metadata\", \"label\": \"its metadata.json\"}, {\"href\": \"https://github.com/simonw/datasette-cluster-map\", \"label\": \"datasette-cluster-map\"}]"}
{"id": "changelog:v0-28-databases-that-change", "page": "changelog", "ref": "v0-28-databases-that-change", "title": "Supporting databases that change", "content": "From the beginning of the project, Datasette has been designed with read-only databases in mind. If a database is guaranteed not to change it opens up all kinds of interesting opportunities - from taking advantage of SQLite immutable mode and HTTP caching to bundling static copies of the database directly in a Docker container.  The interesting ideas in Datasette  explores this idea in detail. \n                 As my goals for the project have developed, I realized that read-only databases are no longer the right default. SQLite actually supports concurrent access very well provided only one thread attempts to write to a database at a time, and I keep encountering sensible use-cases for running Datasette on top of a database that is processing inserts and updates. \n                 So, as-of version 0.28 Datasette no longer assumes that a database file will not change. It is now safe to point Datasette at a SQLite database which is being updated by another process. \n                 Making this change was a lot of work - see tracking tickets  #418 ,  #419  and  #420 . It required new thinking around how Datasette should calculate table counts (an expensive operation against a large, changing database) and also meant reconsidering the \"content hash\" URLs Datasette has used in the past to optimize the performance of HTTP caches. \n                 Datasette can still run against immutable files and gains numerous performance benefits from doing so, but this is no longer the default behaviour. Take a look at the new  Performance and caching  documentation section for details on how to make the most of Datasette against data that you know will be staying read-only and immutable.", "breadcrumbs": "[\"Changelog\", \"0.28 (2019-05-19)\"]", "references": "[{\"href\": \"https://simonwillison.net/2018/Oct/4/datasette-ideas/\", \"label\": \"The interesting ideas in Datasette\"}, {\"href\": \"https://github.com/simonw/datasette/issues/418\", \"label\": \"#418\"}, {\"href\": \"https://github.com/simonw/datasette/issues/419\", \"label\": \"#419\"}, {\"href\": \"https://github.com/simonw/datasette/issues/420\", \"label\": \"#420\"}]"}
{"id": "facets:suggested-facets", "page": "facets", "ref": "suggested-facets", "title": "Suggested facets", "content": "Datasette's table UI will suggest facets for the user to apply, based on the following criteria: \n             For the currently filtered data are there any columns which, if applied as a facet... \n             \n                 \n                     Will return 30 or less unique options \n                 \n                 \n                     Will return more than one unique option \n                 \n                 \n                     Will return less unique options than the total number of filtered rows \n                 \n                 \n                     And the query used to evaluate this criteria can be completed in under 50ms \n                 \n             \n             That last point is particularly important: Datasette runs a query for every column that is displayed on a page, which could get expensive - so to avoid slow load times it sets a time limit of just 50ms for each of those queries.\n                This means suggested facets are unlikely to appear for tables with millions of records in them.", "breadcrumbs": "[\"Facets\"]", "references": "[]"}
{"id": "csv_export:streaming-all-records", "page": "csv_export", "ref": "streaming-all-records", "title": "Streaming all records", "content": "The  stream all rows  option is designed to be as efficient as possible -\n                under the hood it takes advantage of Python 3 asyncio capabilities and\n                Datasette's efficient  pagination  to stream back the full\n                CSV file. \n             Since databases can get pretty large, by default this option is capped at 100MB -\n                if a table returns more than 100MB of data the last line of the CSV will be a\n                truncation error message. \n             You can increase or remove this limit using the  max_csv_mb  config\n                setting. You can also disable the CSV export feature entirely using\n                 allow_csv_stream .", "breadcrumbs": "[\"CSV export\"]", "references": "[]"}
{"id": "writing_plugins:writing-plugins-static-assets", "page": "writing_plugins", "ref": "writing-plugins-static-assets", "title": "Static assets", "content": "If your plugin has a  static/  directory, Datasette will automatically configure itself to serve those static assets from the following path: \n             /-/static-plugins/NAME_OF_PLUGIN_PACKAGE/yourfile.js \n             Use the  datasette.urls.static_plugins(plugin_name, path)  method to generate URLs to that asset that take the  base_url  setting into account, see  datasette.urls . \n             To bundle the static assets for a plugin in the package that you publish to PyPI, add the following to the plugin's  setup.py : \n             package_data = (\n    {\n        \"datasette_plugin_name\": [\n            \"static/plugin.js\",\n        ],\n    },\n) \n             Where  datasette_plugin_name  is the name of the plugin package (note that it uses underscores, not hyphens) and  static/plugin.js  is the path within that package to the static file. \n             datasette-cluster-map  is a useful example of a plugin that includes packaged static assets in this way.", "breadcrumbs": "[\"Writing plugins\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-cluster-map\", \"label\": \"datasette-cluster-map\"}]"}
{"id": "writing_plugins:writing-plugins-cookiecutter", "page": "writing_plugins", "ref": "writing-plugins-cookiecutter", "title": "Starting an installable plugin using cookiecutter", "content": "Plugins that can be installed should be written as Python packages using a  setup.py  file. \n             The quickest way to start writing one an installable plugin is to use the  datasette-plugin  cookiecutter template. This creates a new plugin structure for you complete with an example test and GitHub Actions workflows for testing and publishing your plugin. \n             Install cookiecutter  and then run this command to start building a plugin using the template: \n             cookiecutter gh:simonw/datasette-plugin \n             Read  a cookiecutter template for writing Datasette plugins  for more information about this template.", "breadcrumbs": "[\"Writing plugins\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-plugin\", \"label\": \"datasette-plugin\"}, {\"href\": \"https://cookiecutter.readthedocs.io/en/stable/installation.html\", \"label\": \"Install cookiecutter\"}, {\"href\": \"https://simonwillison.net/2020/Jun/20/cookiecutter-plugins/\", \"label\": \"a cookiecutter template for writing Datasette plugins\"}]"}
{"id": "facets:speeding-up-facets-with-indexes", "page": "facets", "ref": "speeding-up-facets-with-indexes", "title": "Speeding up facets with indexes", "content": "The performance of facets can be greatly improved by adding indexes on the columns you wish to facet by.\n                Adding indexes can be performed using the  sqlite3  command-line utility. Here's how to add an index on the  state  column in a table called  Food_Trucks : \n             sqlite3 mydatabase.db \n             SQLite version 3.19.3 2017-06-27 16:48:08\nEnter \".help\" for usage hints.\nsqlite> CREATE INDEX Food_Trucks_state ON Food_Trucks(\"state\"); \n             Or using the  sqlite-utils  command-line utility: \n             sqlite-utils create-index mydatabase.db Food_Trucks state", "breadcrumbs": "[\"Facets\"]", "references": "[{\"href\": \"https://sqlite-utils.datasette.io/en/stable/cli.html#creating-indexes\", \"label\": \"sqlite-utils\"}]"}
{"id": "metadata:specifying-units-for-a-column", "page": "metadata", "ref": "specifying-units-for-a-column", "title": "Specifying units for a column", "content": "Datasette supports attaching units to a column, which will be used when displaying\n                values from that column. SI prefixes will be used where appropriate. \n             Column units are configured in the metadata like so: \n             [[[cog\nmetadata_example(cog, {\n    \"databases\": {\n        \"database1\": {\n            \"tables\": {\n                \"example_table\": {\n                    \"units\": {\n                        \"column1\": \"metres\",\n                        \"column2\": \"Hz\"\n                    }\n                }\n            }\n        }\n    }\n}) \n             ]]] \n             [[[end]]] \n             Units are interpreted using  Pint , and you can see the full list of available units in\n                Pint's  unit registry . You can also add  custom units  to the metadata, which will be\n                registered with Pint: \n             [[[cog\nmetadata_example(cog, {\n    \"custom_units\": [\n        \"decibel = [] = dB\"\n    ]\n}) \n             ]]] \n             [[[end]]]", "breadcrumbs": "[\"Metadata\"]", "references": "[{\"href\": \"https://pint.readthedocs.io/\", \"label\": \"Pint\"}, {\"href\": \"https://github.com/hgrecco/pint/blob/master/pint/default_en.txt\", \"label\": \"unit registry\"}, {\"href\": \"http://pint.readthedocs.io/en/latest/defining.html\", \"label\": \"custom units\"}]"}
{"id": "metadata:label-columns", "page": "metadata", "ref": "label-columns", "title": "Specifying the label column for a table", "content": "Datasette's HTML interface attempts to display foreign key references as\n                labelled hyperlinks. By default, it looks for referenced tables that only have\n                two columns: a primary key column and one other. It assumes that the second\n                column should be used as the link label. \n             If your table has more than two columns you can specify which column should be\n                used for the link label with the  label_column  property: \n             [[[cog\nmetadata_example(cog, {\n    \"databases\": {\n        \"database1\": {\n            \"tables\": {\n                \"example_table\": {\n                    \"label_column\": \"title\"\n                }\n            }\n        }\n    }\n}) \n             ]]] \n             [[[end]]]", "breadcrumbs": "[\"Metadata\"]", "references": "[]"}
{"id": "json_api:json-api-table-arguments", "page": "json_api", "ref": "json-api-table-arguments", "title": "Special table arguments", "content": "?_col=COLUMN1&_col=COLUMN2 \n                         \n                             List specific columns to display. These will be shown along with any primary keys. \n                         \n                     \n                     \n                         ?_nocol=COLUMN1&_nocol=COLUMN2 \n                         \n                             List specific columns to hide - any column not listed will be displayed. Primary keys cannot be hidden. \n                         \n                     \n                     \n                         ?_labels=on/off \n                         \n                             Expand foreign key references for every possible column. See below. \n                         \n                     \n                     \n                         ?_label=COLUMN1&_label=COLUMN2 \n                         \n                             Expand foreign key references for one or more specified columns. \n                         \n                     \n                     \n                         ?_size=1000  or  ?_size=max \n                         \n                             Sets a custom page size. This cannot exceed the  max_returned_rows  limit\n                                passed to  datasette serve . Use  max  to get  max_returned_rows . \n                         \n                     \n                     \n                         ?_sort=COLUMN \n                         \n                             Sorts the results by the specified column. \n                         \n                     \n                     \n                         ?_sort_desc=COLUMN \n                         \n                             Sorts the results by the specified column in descending order. \n                         \n                     \n                     \n                         ?_search=keywords \n                         \n                             For SQLite tables that have been configured for\n                                 full-text search  executes a search\n                                with the provided keywords. \n                         \n                     \n                     \n                         ?_search_COLUMN=keywords \n                         \n                             Like  _search=  but allows you to specify the column to be searched, as\n                                opposed to searching all columns that have been indexed by FTS. \n                         \n                     \n                     \n                         ?_searchmode=raw \n                         \n                             With this option, queries passed to  ?_search=  or  ?_search_COLUMN=  will\n                                not have special characters escaped. This means you can make use of the full\n                                set of  advanced SQLite FTS syntax ,\n                                though this could potentially result in errors if the wrong syntax is used. \n                         \n                     \n                     \n                         ?_where=SQL-fragment \n                         \n                             If the  execute-sql  permission is enabled, this parameter\n                                can be used to pass one or more additional SQL fragments to be used in the\n                                 WHERE  clause of the SQL used to query the table. \n                             This is particularly useful if you are building a JavaScript application\n                                that needs to do something creative but still wants the other conveniences\n                                provided by the table view (such as faceting) and hence would like not to\n                                have to construct a completely custom SQL query. \n                             Some examples: \n                             \n                                 \n                                     facetable?_where=_neighborhood like \"%c%\"&_where=_city_id=3 \n                                 \n                                 \n                                     facetable?_where=_city_id in (select id from facet_cities where name != \"Detroit\") \n                                 \n                             \n                         \n                     \n                     \n                         ?_through={json} \n                         \n                             This can be used to filter rows via a join against another table. \n                             The JSON parameter must include three keys:  table ,  column  and  value . \n                             table  must be a table that the current table is related to via a foreign key relationship. \n                             column  must be a column in that other table. \n                             value  is the value that you want to match against. \n                             For example, to filter  roadside_attractions  to just show the attractions that have a characteristic of \"museum\", you would construct this JSON: \n                             {\n    \"table\": \"roadside_attraction_characteristics\",\n    \"column\": \"characteristic_id\",\n    \"value\": \"1\"\n} \n                             As a URL, that looks like this: \n                             ?_through={%22table%22:%22roadside_attraction_characteristics%22,%22column%22:%22characteristic_id%22,%22value%22:%221%22} \n                             Here's  an example . \n                         \n                     \n                     \n                         ?_next=TOKEN \n                         \n                             Pagination by continuation token - pass the token that was returned in the\n                                 \"next\"  property by the previous page. \n                         \n                     \n                     \n                         ?_facet=column \n                         \n                             Facet by column. Can be applied multiple times, see  Facets . Only works on the default JSON output, not on any of the custom shapes. \n                         \n                     \n                     \n                         ?_facet_size=100 \n                         \n                             Increase the number of facet results returned for each facet. Use  ?_facet_size=max  for the maximum available size, determined by  max_returned_rows . \n                         \n                     \n                     \n                         ?_nofacet=1 \n                         \n                             Disable all facets and facet suggestions for this page, including any defined by  Facets in metadata . \n                         \n                     \n                     \n                         ?_nosuggest=1 \n                         \n                             Disable facet suggestions for this page. \n                         \n                     \n                     \n                         ?_nocount=1 \n                         \n                             Disable the  select count(*)  query used on this page - a count of  None  will be returned instead.", "breadcrumbs": "[\"JSON API\", \"Table arguments\"]", "references": "[{\"href\": \"https://www.sqlite.org/fts3.html\", \"label\": \"full-text search\"}, {\"href\": \"https://www.sqlite.org/fts5.html#full_text_query_syntax\", \"label\": \"advanced SQLite FTS syntax\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_where=_neighborhood%20like%20%22%c%%22&_where=_city_id=3\", \"label\": \"facetable?_where=_neighborhood like \\\"%c%\\\"&_where=_city_id=3\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_where=_city_id%20in%20(select%20id%20from%20facet_cities%20where%20name%20!=%20%22Detroit%22)\", \"label\": \"facetable?_where=_city_id in (select id from facet_cities where name != \\\"Detroit\\\")\"}, {\"href\": \"https://latest.datasette.io/fixtures/roadside_attractions?_through={%22table%22:%22roadside_attraction_characteristics%22,%22column%22:%22characteristic_id%22,%22value%22:%221%22}\", \"label\": \"an example\"}]"}
{"id": "json_api:json-api-special", "page": "json_api", "ref": "json-api-special", "title": "Special JSON arguments", "content": "Every Datasette endpoint that can return JSON also accepts the following\n                query string arguments: \n             \n                 \n                     ?_shape=SHAPE \n                     \n                         The shape of the JSON to return, documented above. \n                     \n                 \n                 \n                     ?_nl=on \n                     \n                         When used with  ?_shape=array  produces newline-delimited JSON objects. \n                     \n                 \n                 \n                     ?_json=COLUMN1&_json=COLUMN2 \n                     \n                         If any of your SQLite columns contain JSON values, you can use one or more\n                             _json=  parameters to request that those columns be returned as regular\n                            JSON. Without this argument those columns will be returned as JSON objects\n                            that have been double-encoded into a JSON string value. \n                         Compare  this query without the argument  to  this query using the argument \n                     \n                 \n                 \n                     ?_json_infinity=on \n                     \n                         If your data contains infinity or -infinity values, Datasette will replace\n                            them with None when returning them as JSON. If you pass  _json_infinity=1 \n                            Datasette will instead return them as  Infinity  or  -Infinity  which is\n                            invalid JSON but can be processed by some custom JSON parsers. \n                     \n                 \n                 \n                     ?_timelimit=MS \n                     \n                         Sets a custom time limit for the query in ms. You can use this for optimistic\n                            queries where you would like Datasette to give up if the query takes too\n                            long, for example if you want to implement autocomplete search but only if\n                            it can be executed in less than 10ms. \n                     \n                 \n                 \n                     ?_ttl=SECONDS \n                     \n                         For how many seconds should this response be cached by HTTP proxies? Use\n                             ?_ttl=0  to disable HTTP caching entirely for this request. \n                     \n                 \n                 \n                     ?_trace=1 \n                     \n                         Turns on tracing for this page: SQL queries executed during the request will\n                            be gathered and included in the response, either in a new  \"_traces\"  key\n                            for JSON responses or at the bottom of the page if the response is in HTML. \n                         The structure of the data returned here should be considered highly unstable\n                            and very likely to change. \n                         Only available if the  trace_debug  setting is enabled.", "breadcrumbs": "[\"JSON API\"]", "references": "[{\"href\": \"https://fivethirtyeight.datasettes.com/fivethirtyeight.json?sql=select+%27{%22this+is%22%3A+%22a+json+object%22}%27+as+d&_shape=array\", \"label\": \"this query without the argument\"}, {\"href\": \"https://fivethirtyeight.datasettes.com/fivethirtyeight.json?sql=select+%27{%22this+is%22%3A+%22a+json+object%22}%27+as+d&_shape=array&_json=d\", \"label\": \"this query using the argument\"}]"}
{"id": "spatialite:spatial-indexing-latitude-longitude-columns", "page": "spatialite", "ref": "spatial-indexing-latitude-longitude-columns", "title": "Spatial indexing latitude/longitude columns", "content": "Here's a recipe for taking a table with existing latitude and longitude columns, adding a SpatiaLite POINT geometry column to that table, populating the new column and then populating a spatial index: \n             import sqlite3\n\nconn = sqlite3.connect(\"museums.db\")\n# Lead the spatialite extension:\nconn.enable_load_extension(True)\nconn.load_extension(\"/usr/local/lib/mod_spatialite.dylib\")\n# Initialize spatial metadata for this database:\nconn.execute(\"select InitSpatialMetadata(1)\")\n# Add a geometry column called point_geom to our museums table:\nconn.execute(\n    \"SELECT AddGeometryColumn('museums', 'point_geom', 4326, 'POINT', 2);\"\n)\n# Now update that geometry column with the lat/lon points\nconn.execute(\n    \"\"\"\n    UPDATE museums SET\n    point_geom = GeomFromText('POINT('||\"longitude\"||' '||\"latitude\"||')',4326);\n\"\"\"\n)\n# Now add a spatial index to that column\nconn.execute(\n    'select CreateSpatialIndex(\"museums\", \"point_geom\");'\n)\n# If you don't commit your changes will not be persisted:\nconn.commit()\nconn.close()", "breadcrumbs": "[\"SpatiaLite\"]", "references": "[]"}
{"id": "spatialite:id1", "page": "spatialite", "ref": "id1", "title": "SpatiaLite", "content": "The  SpatiaLite module  for SQLite adds features for handling geographic and spatial data. For an example of what you can do with it, see the tutorial  Building a location to time zone API with SpatiaLite . \n         To use it with Datasette, you need to install the  mod_spatialite  dynamic library. This can then be loaded into Datasette using the  --load-extension  command-line option. \n         Datasette can look for SpatiaLite in common installation locations if you run it like this: \n         datasette --load-extension=spatialite --setting default_allow_sql off \n         If SpatiaLite is in another location, use the full path to the extension instead: \n         datasette --setting default_allow_sql off \\\n  --load-extension=/usr/local/lib/mod_spatialite.dylib", "breadcrumbs": "[]", "references": "[{\"href\": \"https://www.gaia-gis.it/fossil/libspatialite/index\", \"label\": \"SpatiaLite module\"}, {\"href\": \"https://datasette.io/tutorials/spatialite\", \"label\": \"Building a location to time zone API with SpatiaLite\"}]"}
{"id": "metadata:metadata-source-license-about", "page": "metadata", "ref": "metadata-source-license-about", "title": "Source, license and about", "content": "The three visible metadata fields you can apply to everything, specific databases or specific tables are source, license and about. All three are optional. \n             source  and  source_url  should be used to indicate where the underlying data came from. \n             license  and  license_url  should be used to indicate the license under which the data can be used. \n             about  and  about_url  can be used to link to further information about the project - an accompanying blog entry for example. \n             For each of these you can provide just the  *_url  field and Datasette will treat that as the default link label text and display the URL directly on the page.", "breadcrumbs": "[\"Metadata\"]", "references": "[]"}
{"id": "changelog:id46", "page": "changelog", "ref": "id46", "title": "Smaller changes", "content": "Wide tables shown within Datasette now scroll horizontally ( #998 ). This is achieved using a new  <div class=\"table-wrapper\">  element which may impact the implementation of some plugins (for example  this change to datasette-cluster-map ). \n                     \n                     \n                         New  debug-menu  permission. ( #1068 ) \n                     \n                     \n                         Removed  --debug  option, which didn't do anything. ( #814 ) \n                     \n                     \n                         Link:  HTTP header pagination. ( #1014 ) \n                     \n                     \n                         x  button for clearing filters. ( #1016 ) \n                     \n                     \n                         Edit SQL button on canned queries, ( #1019 ) \n                     \n                     \n                         --load-extension=spatialite  shortcut. ( #1028 ) \n                     \n                     \n                         scale-in animation for column action menu. ( #1039 ) \n                     \n                     \n                         Option to pass a list of templates to  .render_template()  is now documented. ( #1045 ) \n                     \n                     \n                         New  datasette.urls.static_plugins()  method. ( #1033 ) \n                     \n                     \n                         datasette -o  option now opens the most relevant page. ( #976 ) \n                     \n                     \n                         datasette --cors  option now enables access to  /database.db  downloads. ( #1057 ) \n                     \n                     \n                         Database file downloads now implement cascading permissions, so you can download a database if you have  view-database-download  permission even if you do not have permission to access the Datasette instance. ( #1058 ) \n                     \n                     \n                         New documentation on  Designing URLs for your plugin . ( #1053 )", "breadcrumbs": "[\"Changelog\", \"0.51 (2020-10-31)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/998\", \"label\": \"#998\"}, {\"href\": \"https://github.com/simonw/datasette-cluster-map/commit/fcb4abbe7df9071c5ab57defd39147de7145b34e\", \"label\": \"this change to datasette-cluster-map\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1068\", \"label\": \"#1068\"}, {\"href\": \"https://github.com/simonw/datasette/issues/814\", \"label\": \"#814\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1014\", \"label\": \"#1014\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1016\", \"label\": \"#1016\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1019\", \"label\": \"#1019\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1028\", \"label\": \"#1028\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1039\", \"label\": \"#1039\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1045\", \"label\": \"#1045\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1033\", \"label\": \"#1033\"}, {\"href\": \"https://github.com/simonw/datasette/issues/976\", \"label\": \"#976\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1057\", \"label\": \"#1057\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1058\", \"label\": \"#1058\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1053\", \"label\": \"#1053\"}]"}
{"id": "changelog:id59", "page": "changelog", "ref": "id59", "title": "Smaller changes", "content": "Cascading view permissions - so if a user has  view-table  they can view the table page even if they do not have  view-database  or  view-instance . ( #832 ) \n                     \n                     \n                         CSRF protection no longer applies to  Authentication: Bearer token  requests or requests without cookies. ( #835 ) \n                     \n                     \n                         datasette.add_message()  now works inside plugins. ( #864 ) \n                     \n                     \n                         Workaround for \"Too many open files\" error in test runs. ( #846 ) \n                     \n                     \n                         Respect existing  scope[\"actor\"]  if already set by ASGI middleware. ( #854 ) \n                     \n                     \n                         New process for shipping  Alpha and beta releases . ( #807 ) \n                     \n                     \n                         {{ csrftoken() }}  now works when plugins render a template using  datasette.render_template(..., request=request) . ( #863 ) \n                     \n                     \n                         Datasette now creates a single  Request object  and uses it throughout the lifetime of the current HTTP request. ( #870 )", "breadcrumbs": "[\"Changelog\", \"0.45 (2020-07-01)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/832\", \"label\": \"#832\"}, {\"href\": \"https://github.com/simonw/datasette/issues/835\", \"label\": \"#835\"}, {\"href\": \"https://github.com/simonw/datasette/issues/864\", \"label\": \"#864\"}, {\"href\": \"https://github.com/simonw/datasette/issues/846\", \"label\": \"#846\"}, {\"href\": \"https://github.com/simonw/datasette/issues/854\", \"label\": \"#854\"}, {\"href\": \"https://github.com/simonw/datasette/issues/807\", \"label\": \"#807\"}, {\"href\": \"https://github.com/simonw/datasette/issues/863\", \"label\": \"#863\"}, {\"href\": \"https://github.com/simonw/datasette/issues/870\", \"label\": \"#870\"}]"}
{"id": "changelog:id61", "page": "changelog", "ref": "id61", "title": "Smaller changes", "content": "New internals documentation for  Request object  and  Response class . ( #706 ) \n                     \n                     \n                         request.url  now respects the  force_https_urls  config setting. closes ( #781 ) \n                     \n                     \n                         request.args.getlist()  returns  []  if missing. Removed  request.raw_args  entirely. ( #774 ) \n                     \n                     \n                         New  datasette.get_database()  method. \n                     \n                     \n                         Added  _  prefix to many private, undocumented methods of the Datasette class. ( #576 ) \n                     \n                     \n                         Removed the  db.get_outbound_foreign_keys()  method which duplicated the behaviour of  db.foreign_keys_for_table() . \n                     \n                     \n                         New  await datasette.permission_allowed()  method. \n                     \n                     \n                         /-/actor  debugging endpoint for viewing the currently authenticated actor. \n                     \n                     \n                         New  request.cookies  property. \n                     \n                     \n                         /-/plugins  endpoint now shows a list of hooks implemented by each plugin, e.g.  https://latest.datasette.io/-/plugins?all=1 \n                     \n                     \n                         request.post_vars()  method no longer discards empty values. \n                     \n                     \n                         New \"params\" canned query key for explicitly setting named parameters, see  Canned query parameters . ( #797 ) \n                     \n                     \n                         request.args  is now a  MultiParams  object. \n                     \n                     \n                         Fixed a bug with the  datasette plugins  command. ( #802 ) \n                     \n                     \n                         Nicer pattern for using  make_app_client()  in tests. ( #395 ) \n                     \n                     \n                         New  request.actor  property. \n                     \n                     \n                         Fixed broken CSS on nested 404 pages. ( #777 ) \n                     \n                     \n                         New  request.url_vars  property. ( #822 ) \n                     \n                     \n                         Fixed a bug with the  python tests/fixtures.py  command for outputting Datasette's testing fixtures database and plugins. ( #804 ) \n                     \n                     \n                         datasette publish heroku  now deploys using Python 3.8.3. \n                     \n                     \n                         Added a warning that the  register_facet_classes()  hook is unstable and may change in the future. ( #830 ) \n                     \n                     \n                         The  {\"$env\": \"ENVIRONMENT_VARIBALE\"}  mechanism (see  Secret configuration values ) now works with variables inside nested lists. ( #837 )", "breadcrumbs": "[\"Changelog\", \"0.44 (2020-06-11)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/706\", \"label\": \"#706\"}, {\"href\": \"https://github.com/simonw/datasette/issues/781\", \"label\": \"#781\"}, {\"href\": \"https://github.com/simonw/datasette/issues/774\", \"label\": \"#774\"}, {\"href\": \"https://github.com/simonw/datasette/issues/576\", \"label\": \"#576\"}, {\"href\": \"https://latest.datasette.io/-/plugins?all=1\", \"label\": \"https://latest.datasette.io/-/plugins?all=1\"}, {\"href\": \"https://github.com/simonw/datasette/issues/797\", \"label\": \"#797\"}, {\"href\": \"https://github.com/simonw/datasette/issues/802\", \"label\": \"#802\"}, {\"href\": \"https://github.com/simonw/datasette/issues/395\", \"label\": \"#395\"}, {\"href\": \"https://github.com/simonw/datasette/issues/777\", \"label\": \"#777\"}, {\"href\": \"https://github.com/simonw/datasette/issues/822\", \"label\": \"#822\"}, {\"href\": \"https://github.com/simonw/datasette/issues/804\", \"label\": \"#804\"}, {\"href\": \"https://github.com/simonw/datasette/issues/830\", \"label\": \"#830\"}, {\"href\": \"https://github.com/simonw/datasette/issues/837\", \"label\": \"#837\"}]"}
{"id": "changelog:smaller-changes", "page": "changelog", "ref": "smaller-changes", "title": "Smaller changes", "content": "Datasette documentation now shows YAML examples for  Metadata  by default, with a tab interface for switching to JSON. ( #1153 ) \n                     \n                     \n                         register_output_renderer(datasette)  plugins now have access to  error  and  truncated  arguments, allowing them to display error messages and take into account truncated results. ( #2130 ) \n                     \n                     \n                         render_cell()  plugin hook now also supports an optional  request  argument. ( #2007 ) \n                     \n                     \n                         New  Justfile  to support development workflows for Datasette using  Just . \n                     \n                     \n                         datasette.render_template()  can now accepts a  datasette.views.Context  subclass as an alternative to a dictionary. ( #2127 ) \n                     \n                     \n                         datasette install -e path  option for editable installations, useful while developing plugins. ( #2106 ) \n                     \n                     \n                         When started with the  --cors  option Datasette now serves an  Access-Control-Max-Age: 3600  header, ensuring CORS OPTIONS requests are repeated no more than once an hour. ( #2079 ) \n                     \n                     \n                         Fixed a bug where the  _internal  database could display  None  instead of  null  for in-memory databases. ( #1970 )", "breadcrumbs": "[\"Changelog\", \"1.0a3 (2023-08-09)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1153\", \"label\": \"#1153\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2130\", \"label\": \"#2130\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2007\", \"label\": \"#2007\"}, {\"href\": \"https://github.com/casey/just\", \"label\": \"Just\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2127\", \"label\": \"#2127\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2106\", \"label\": \"#2106\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2079\", \"label\": \"#2079\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1970\", \"label\": \"#1970\"}]"}
{"id": "changelog:id86", "page": "changelog", "ref": "id86", "title": "Small changes", "content": "We now show the size of the database file next to the download link ( #172 ) \n                     \n                     \n                         New  /-/databases  introspection page shows currently connected databases ( #470 ) \n                     \n                     \n                         Binary data is no longer displayed on the table and row pages ( #442  - thanks, Russ Garrett) \n                     \n                     \n                         New show/hide SQL links on custom query pages ( #415 ) \n                     \n                     \n                         The  extra_body_script  plugin hook now accepts an optional  view_name  argument ( #443  - thanks, Russ Garrett) \n                     \n                     \n                         Bumped Jinja2 dependency to 2.10.1 ( #426 ) \n                     \n                     \n                         All table filters are now documented, and documentation is enforced via unit tests ( 2c19a27 ) \n                     \n                     \n                         New project guideline: master should stay shippable at all times! ( 31f36e1 ) \n                     \n                     \n                         Fixed a bug where  sqlite_timelimit()  occasionally failed to clean up after itself ( bac4e01 ) \n                     \n                     \n                         We no longer load additional plugins when executing pytest ( #438 ) \n                     \n                     \n                         Homepage now links to database views if there are less than five tables in a database ( #373 ) \n                     \n                     \n                         The  --cors  option is now respected by error pages ( #453 ) \n                     \n                     \n                         datasette publish heroku  now uses the  --include-vcs-ignore  option, which means it works under Travis CI ( #407 ) \n                     \n                     \n                         datasette publish heroku  now publishes using Python 3.6.8 ( 666c374 ) \n                     \n                     \n                         Renamed  datasette publish now  to  datasette publish nowv1  ( #472 ) \n                     \n                     \n                         datasette publish nowv1  now accepts multiple  --alias  parameters ( 09ef305 ) \n                     \n                     \n                         Removed the  datasette skeleton  command ( #476 ) \n                     \n                     \n                         The  documentation on how to build the documentation  now recommends  sphinx-autobuild", "breadcrumbs": "[\"Changelog\", \"0.28 (2019-05-19)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/172\", \"label\": \"#172\"}, {\"href\": \"https://github.com/simonw/datasette/issues/470\", \"label\": \"#470\"}, {\"href\": \"https://github.com/simonw/datasette/pull/442\", \"label\": \"#442\"}, {\"href\": \"https://github.com/simonw/datasette/issues/415\", \"label\": \"#415\"}, {\"href\": \"https://github.com/simonw/datasette/pull/443\", \"label\": \"#443\"}, {\"href\": \"https://github.com/simonw/datasette/pull/426\", \"label\": \"#426\"}, {\"href\": \"https://github.com/simonw/datasette/commit/2c19a27d15a913e5f3dd443f04067169a6f24634\", \"label\": \"2c19a27\"}, {\"href\": \"https://github.com/simonw/datasette/commit/31f36e1b97ccc3f4387c80698d018a69798b6228\", \"label\": \"31f36e1\"}, {\"href\": \"https://github.com/simonw/datasette/commit/bac4e01f40ae7bd19d1eab1fb9349452c18de8f5\", \"label\": \"bac4e01\"}, {\"href\": \"https://github.com/simonw/datasette/issues/438\", \"label\": \"#438\"}, {\"href\": \"https://github.com/simonw/datasette/issues/373\", \"label\": \"#373\"}, {\"href\": \"https://github.com/simonw/datasette/issues/453\", \"label\": \"#453\"}, {\"href\": \"https://github.com/simonw/datasette/pull/407\", \"label\": \"#407\"}, {\"href\": \"https://github.com/simonw/datasette/commit/666c37415a898949fae0437099d62a35b1e9c430\", \"label\": \"666c374\"}, {\"href\": \"https://github.com/simonw/datasette/issues/472\", \"label\": \"#472\"}, {\"href\": \"https://github.com/simonw/datasette/commit/09ef305c687399384fe38487c075e8669682deb4\", \"label\": \"09ef305\"}, {\"href\": \"https://github.com/simonw/datasette/issues/476\", \"label\": \"#476\"}]"}
{"id": "changelog:small-changes", "page": "changelog", "ref": "small-changes", "title": "Small changes", "content": "Databases published using  datasette publish  now open in  Immutable mode . ( #469 ) \n                     \n                     \n                         ?col__date=  now works for columns containing spaces \n                     \n                     \n                         Automatic label detection (for deciding which column to show when linking to a foreign key) has been improved. ( #485 ) \n                     \n                     \n                         Fixed bug where pagination broke when combined with an expanded foreign key. ( #489 ) \n                     \n                     \n                         Contributors can now run  pip install -e .[docs]  to get all of the dependencies needed to build the documentation, including  cd docs && make livehtml  support. \n                     \n                     \n                         Datasette's dependencies are now all specified using the  ~=  match operator. ( #532 ) \n                     \n                     \n                         white-space: pre-wrap  now used for table creation SQL. ( #505 ) \n                     \n                 \n                 Full list of commits  between 0.28 and 0.29.", "breadcrumbs": "[\"Changelog\", \"0.29 (2019-07-07)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/469\", \"label\": \"#469\"}, {\"href\": \"https://github.com/simonw/datasette/issues/485\", \"label\": \"#485\"}, {\"href\": \"https://github.com/simonw/datasette/issues/489\", \"label\": \"#489\"}, {\"href\": \"https://github.com/simonw/datasette/issues/532\", \"label\": \"#532\"}, {\"href\": \"https://github.com/simonw/datasette/issues/505\", \"label\": \"#505\"}, {\"href\": \"https://github.com/simonw/datasette/compare/0.28...0.29\", \"label\": \"Full list of commits\"}]"}
{"id": "changelog:signed-values-and-secrets", "page": "changelog", "ref": "signed-values-and-secrets", "title": "Signed values and secrets", "content": "Both flash messages and user authentication needed a way to sign values and set signed cookies. Two new methods are now available for plugins to take advantage of this mechanism:  .sign(value, namespace=\"default\")  and  .unsign(value, namespace=\"default\") . \n                 Datasette will generate a secret automatically when it starts up, but to avoid resetting the secret (and hence invalidating any cookies) every time the server restarts you should set your own secret. You can pass a secret to Datasette using the new  --secret  option or with a  DATASETTE_SECRET  environment variable. See  Configuring the secret  for more details. \n                 You can also set a secret when you deploy Datasette using  datasette publish  or  datasette package  - see  Using secrets with datasette publish . \n                 Plugins can now sign values and verify their signatures using the  datasette.sign()  and  datasette.unsign()  methods.", "breadcrumbs": "[\"Changelog\", \"0.44 (2020-06-11)\"]", "references": "[]"}
{"id": "changelog:signed-api-tokens", "page": "changelog", "ref": "signed-api-tokens", "title": "Signed API tokens", "content": "New  /-/create-token  page allowing authenticated users to create signed API tokens that can act on their behalf, see  API Tokens . ( #1852 ) \n                     \n                     \n                         New  datasette create-token  command for creating tokens from the command line:  datasette create-token . \n                     \n                     \n                         New  allow_signed_tokens  setting which can be used to turn off signed token support. ( #1856 ) \n                     \n                     \n                         New  max_signed_tokens_ttl  setting for restricting the maximum allowed duration of a signed token. ( #1858 )", "breadcrumbs": "[\"Changelog\", \"1.0a0 (2022-11-29)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1852\", \"label\": \"#1852\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1856\", \"label\": \"#1856\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1858\", \"label\": \"#1858\"}]"}