-
-
Notifications
You must be signed in to change notification settings - Fork 653
/
internals.rst
1337 lines (855 loc) · 54.2 KB
/
internals.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.. _internals:
=======================
Internals for plugins
=======================
Many :ref:`plugin_hooks` are passed objects that provide access to internal Datasette functionality. The interface to these objects should not be considered stable with the exception of methods that are documented here.
.. _internals_request:
Request object
==============
The request object is passed to various plugin hooks. It represents an incoming HTTP request. It has the following properties:
``.scope`` - dictionary
The ASGI scope that was used to construct this request, described in the `ASGI HTTP connection scope <https://asgi.readthedocs.io/en/latest/specs/www.html#connection-scope>`__ specification.
``.method`` - string
The HTTP method for this request, usually ``GET`` or ``POST``.
``.url`` - string
The full URL for this request, e.g. ``https://latest.datasette.io/fixtures``.
``.scheme`` - string
The request scheme - usually ``https`` or ``http``.
``.headers`` - dictionary (str -> str)
A dictionary of incoming HTTP request headers. Header names have been converted to lowercase.
``.cookies`` - dictionary (str -> str)
A dictionary of incoming cookies
``.host`` - string
The host header from the incoming request, e.g. ``latest.datasette.io`` or ``localhost``.
``.path`` - string
The path of the request excluding the query string, e.g. ``/fixtures``.
``.full_path`` - string
The path of the request including the query string if one is present, e.g. ``/fixtures?sql=select+sqlite_version()``.
``.query_string`` - string
The query string component of the request, without the ``?`` - e.g. ``name__contains=sam&age__gt=10``.
``.args`` - MultiParams
An object representing the parsed query string parameters, see below.
``.url_vars`` - dictionary (str -> str)
Variables extracted from the URL path, if that path was defined using a regular expression. See :ref:`plugin_register_routes`.
``.actor`` - dictionary (str -> Any) or None
The currently authenticated actor (see :ref:`actors <authentication_actor>`), or ``None`` if the request is unauthenticated.
The object also has two awaitable methods:
``await request.post_vars()`` - dictionary
Returns a dictionary of form variables that were submitted in the request body via ``POST``. Don't forget to read about :ref:`internals_csrf`!
``await request.post_body()`` - bytes
Returns the un-parsed body of a request submitted by ``POST`` - useful for things like incoming JSON data.
And a class method that can be used to create fake request objects for use in tests:
``fake(path_with_query_string, method="GET", scheme="http", url_vars=None)``
Returns a ``Request`` instance for the specified path and method. For example:
.. code-block:: python
from datasette import Request
from pprint import pprint
request = Request.fake(
"/fixtures/facetable/",
url_vars={"database": "fixtures", "table": "facetable"},
)
pprint(request.scope)
This outputs::
{'http_version': '1.1',
'method': 'GET',
'path': '/fixtures/facetable/',
'query_string': b'',
'raw_path': b'/fixtures/facetable/',
'scheme': 'http',
'type': 'http',
'url_route': {'kwargs': {'database': 'fixtures', 'table': 'facetable'}}}
.. _internals_multiparams:
The MultiParams class
=====================
``request.args`` is a ``MultiParams`` object - a dictionary-like object which provides access to query string parameters that may have multiple values.
Consider the query string ``?foo=1&foo=2&bar=3`` - with two values for ``foo`` and one value for ``bar``.
``request.args[key]`` - string
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"``.
``request.args.get(key)`` - string or None
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", "")``.
``request.args.getlist(key)`` - list of strings
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.
``request.args.keys()`` - list of strings
Returns the list of available keys - for the example this would be ``["foo", "bar"]``.
``key in request.args`` - True or False
You can use ``if key in request.args`` to check if a key is present.
``for key in request.args`` - iterator
This lets you loop through every available key.
``len(request.args)`` - integer
Returns the number of keys.
.. _internals_response:
Response class
==============
The ``Response`` class can be returned from view functions that have been registered using the :ref:`plugin_register_routes` hook.
The ``Response()`` constructor takes the following arguments:
``body`` - string
The body of the response.
``status`` - integer (optional)
The HTTP status - defaults to 200.
``headers`` - dictionary (optional)
A dictionary of extra HTTP headers, e.g. ``{"x-hello": "world"}``.
``content_type`` - string (optional)
The content-type for the response. Defaults to ``text/plain``.
For example:
.. code-block:: python
from datasette.utils.asgi import Response
response = Response(
"<xml>This is XML</xml>",
content_type="application/xml; charset=utf-8",
)
The quickest way to create responses is using the ``Response.text(...)``, ``Response.html(...)``, ``Response.json(...)`` or ``Response.redirect(...)`` helper methods:
.. code-block:: python
from datasette.utils.asgi import Response
html_response = Response.html("This is HTML")
json_response = Response.json({"this_is": "json"})
text_response = Response.text(
"This will become utf-8 encoded text"
)
# Redirects are served as 302, unless you pass status=301:
redirect_response = Response.redirect(
"https://latest.datasette.io/"
)
Each of these responses will use the correct corresponding content-type - ``text/html; charset=utf-8``, ``application/json; charset=utf-8`` or ``text/plain; charset=utf-8`` respectively.
Each of the helper methods take optional ``status=`` and ``headers=`` arguments, documented above.
.. _internals_response_asgi_send:
Returning a response with .asgi_send(send)
------------------------------------------
In most cases you will return ``Response`` objects from your own view functions. You can also use a ``Response`` instance to respond at a lower level via ASGI, for example if you are writing code that uses the :ref:`plugin_asgi_wrapper` hook.
Create a ``Response`` object and then use ``await response.asgi_send(send)``, passing the ASGI ``send`` function. For example:
.. code-block:: python
async def require_authorization(scope, receive, send):
response = Response.text(
"401 Authorization Required",
headers={
"www-authenticate": 'Basic realm="Datasette", charset="UTF-8"'
},
status=401,
)
await response.asgi_send(send)
.. _internals_response_set_cookie:
Setting cookies with response.set_cookie()
------------------------------------------
To set cookies on the response, use the ``response.set_cookie(...)`` method. The method signature looks like this:
.. code-block:: python
def set_cookie(
self,
key,
value="",
max_age=None,
expires=None,
path="/",
domain=None,
secure=False,
httponly=False,
samesite="lax",
):
...
You can use this with :ref:`datasette.sign() <datasette_sign>` to set signed cookies. Here's how you would set the :ref:`ds_actor cookie <authentication_ds_actor>` for use with Datasette :ref:`authentication <authentication>`:
.. code-block:: python
response = Response.redirect("/")
response.set_cookie(
"ds_actor",
datasette.sign({"a": {"id": "cleopaws"}}, "actor"),
)
return response
.. _internals_datasette:
Datasette class
===============
This object is an instance of the ``Datasette`` class, passed to many plugin hooks as an argument called ``datasette``.
You can create your own instance of this - for example to help write tests for a plugin - like so:
.. code-block:: python
from datasette.app import Datasette
# With no arguments a single in-memory database will be attached
datasette = Datasette()
# The files= argument can load files from disk
datasette = Datasette(files=["/path/to/my-database.db"])
# Pass metadata as a JSON dictionary like this
datasette = Datasette(
files=["/path/to/my-database.db"],
metadata={
"databases": {
"my-database": {
"description": "This is my database"
}
}
},
)
Constructor parameters include:
- ``files=[...]`` - a list of database files to open
- ``immutables=[...]`` - a list of database files to open in immutable mode
- ``metadata={...}`` - a dictionary of :ref:`metadata`
- ``config_dir=...`` - the :ref:`configuration directory <config_dir>` to use, stored in ``datasette.config_dir``
.. _datasette_databases:
.databases
----------
Property exposing a ``collections.OrderedDict`` of databases currently connected to Datasette.
The dictionary keys are the name of the database that is used in the URL - e.g. ``/fixtures`` would have a key of ``"fixtures"``. The values are :ref:`internals_database` instances.
All databases are listed, irrespective of user permissions.
.. _datasette_permissions:
.permissions
------------
Property exposing a dictionary of permissions that have been registered using the :ref:`plugin_register_permissions` plugin hook.
The dictionary keys are the permission names - e.g. ``view-instance`` - and the values are ``Permission()`` objects describing the permission. Here is a :ref:`description of that object <plugin_register_permissions>`.
.. _datasette_plugin_config:
.plugin_config(plugin_name, database=None, table=None)
------------------------------------------------------
``plugin_name`` - string
The name of the plugin to look up configuration for. Usually this is something similar to ``datasette-cluster-map``.
``database`` - None or string
The database the user is interacting with.
``table`` - None or string
The table the user is interacting with.
This method lets you read plugin configuration values that were set in ``datasette.yaml``. See :ref:`writing_plugins_configuration` for full details of how this method should be used.
The return value will be the value from the configuration file - usually a dictionary.
If the plugin is not configured the return value will be ``None``.
.. _datasette_render_template:
await .render_template(template, context=None, request=None)
------------------------------------------------------------
``template`` - string, list of strings or jinja2.Template
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.
If this is a list of template file names then the first one that exists will be loaded and rendered.
If this is a Jinja `Template object <https://jinja.palletsprojects.com/en/2.11.x/api/#jinja2.Template>`__ it will be used directly.
``context`` - None or a Python dictionary
The context variables to pass to the template.
``request`` - request object or None
If you pass a Datasette request object here it will be made available to the template.
Renders a `Jinja template <https://jinja.palletsprojects.com/en/2.11.x/>`__ 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.
.. _datasette_actors_from_ids:
await .actors_from_ids(actor_ids)
---------------------------------
``actor_ids`` - list of strings or integers
A list of actor IDs to look up.
Returns a dictionary, where the keys are the IDs passed to it and the values are the corresponding actor dictionaries.
This method is mainly designed to be used with plugins. See the :ref:`plugin_hook_actors_from_ids` documentation for details.
If no plugins that implement that hook are installed, the default return value looks like this:
.. code-block:: json
{
"1": {"id": "1"},
"2": {"id": "2"}
}
.. _datasette_permission_allowed:
await .permission_allowed(actor, action, resource=None, default=...)
--------------------------------------------------------------------
``actor`` - dictionary
The authenticated actor. This is usually ``request.actor``.
``action`` - string
The name of the action that is being permission checked.
``resource`` - string or tuple, optional
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.
``default`` - optional: True, False or None
What value should be returned by default if nothing provides an opinion on this permission check.
Set to ``True`` for default allow or ``False`` for default deny.
If not specified the ``default`` from the ``Permission()`` tuple that was registered using :ref:`plugin_register_permissions` will be used.
Check if the given actor has :ref:`permission <authentication_permissions>` to perform the given action on the given resource.
Some permission checks are carried out against :ref:`rules defined in metadata.json <authentication_permissions_metadata>`, while other custom permissions may be decided by plugins that implement the :ref:`plugin_hook_permission_allowed` plugin hook.
If neither ``metadata.json`` nor any of the plugins provide an answer to the permission query the ``default`` argument will be returned.
See :ref:`permissions` for a full list of permission actions included in Datasette core.
.. _datasette_ensure_permissions:
await .ensure_permissions(actor, permissions)
---------------------------------------------
``actor`` - dictionary
The authenticated actor. This is usually ``request.actor``.
``permissions`` - list
A list of permissions to check. Each permission in that list can be a string ``action`` name or a 2-tuple of ``(action, resource)``.
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.
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``:
.. code-block:: python
await self.ds.ensure_permissions(
request.actor,
[
("view-table", (database, table)),
("view-database", database),
"view-instance",
],
)
.. _datasette_check_visibility:
await .check_visibility(actor, action=None, resource=None, permissions=None)
----------------------------------------------------------------------------
``actor`` - dictionary
The authenticated actor. This is usually ``request.actor``.
``action`` - string, optional
The name of the action that is being permission checked.
``resource`` - string or tuple, optional
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.
``permissions`` - list of ``action`` strings or ``(action, resource)`` tuples, optional
Provide this instead of ``action`` and ``resource`` to check multiple permissions at once.
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?"
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.
This example checks if the user can access a specific table, and sets ``private`` so that a padlock icon can later be displayed:
.. code-block:: python
visible, private = await self.ds.check_visibility(
request.actor,
action="view-table",
resource=(database, table),
)
The following example runs three checks in a row, similar to :ref:`datasette_ensure_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.
.. code-block:: python
visible, private = await self.ds.check_visibility(
request.actor,
permissions=[
("view-table", (database, table)),
("view-database", database),
"view-instance",
],
)
.. _datasette_create_token:
.create_token(actor_id, expires_after=None, restrict_all=None, restrict_database=None, restrict_resource=None)
--------------------------------------------------------------------------------------------------------------
``actor_id`` - string
The ID of the actor to create a token for.
``expires_after`` - int, optional
The number of seconds after which the token should expire.
``restrict_all`` - iterable, optional
A list of actions that this token should be restricted to across all databases and resources.
``restrict_database`` - dict, optional
For restricting actions within specific databases, e.g. ``{"mydb": ["view-table", "view-query"]}``.
``restrict_resource`` - dict, optional
For restricting actions to specific resources (tables, SQL views and :ref:`canned_queries`) within a database. For example: ``{"mydb": {"mytable": ["insert-row", "update-row"]}}``.
This method returns a signed :ref:`API token <CreateTokenView>` of the format ``dstok_...`` which can be used to authenticate requests to the Datasette API.
All tokens must have an ``actor_id`` string indicating the ID of the actor which the token will act on behalf of.
Tokens default to lasting forever, but can be set to expire after a given number of seconds using the ``expires_after`` argument. The following code creates a token for ``user1`` that will expire after an hour:
.. code-block:: python
token = datasette.create_token(
actor_id="user1",
expires_after=3600,
)
The three ``restrict_*`` arguments can be used to create a token that has additional restrictions beyond what the associated actor is allowed to do.
The following example creates a token that can access ``view-instance`` and ``view-table`` across everything, can additionally use ``view-query`` for anything in the ``docs`` database and is allowed to execute ``insert-row`` and ``update-row`` in the ``attachments`` table in that database:
.. code-block:: python
token = datasette.create_token(
actor_id="user1",
restrict_all=("view-instance", "view-table"),
restrict_database={"docs": ("view-query",)},
restrict_resource={
"docs": {
"attachments": ("insert-row", "update-row")
}
},
)
.. _datasette_get_permission:
.get_permission(name_or_abbr)
-----------------------------
``name_or_abbr`` - string
The name or abbreviation of the permission to look up, e.g. ``view-table`` or ``vt``.
Returns a :ref:`Permission object <plugin_register_permissions>` representing the permission, or raises a ``KeyError`` if one is not found.
.. _datasette_get_database:
.get_database(name)
-------------------
``name`` - string, optional
The name of the database - optional.
Returns the specified database object. Raises a ``KeyError`` if the database does not exist. Call this method without an argument to return the first connected database.
.. _get_internal_database:
.get_internal_database()
------------------------
Returns a database object for reading and writing to the private :ref:`internal database <internals_internal>`.
.. _datasette_add_database:
.add_database(db, name=None, route=None)
----------------------------------------
``db`` - datasette.database.Database instance
The database to be attached.
``name`` - string, optional
The name to be used for this database . If not specified Datasette will pick one based on the filename or memory name.
``route`` - string, optional
This will be used in the URL path. If not specified, it will default to the same thing as the ``name``.
The ``datasette.add_database(db)`` method lets you add a new database to the current Datasette instance.
The ``db`` parameter should be an instance of the ``datasette.database.Database`` class. For example:
.. code-block:: python
from datasette.database import Database
datasette.add_database(
Database(
datasette,
path="path/to/my-new-database.db",
)
)
This will add a mutable database and serve it at ``/my-new-database``.
Use ``is_mutable=False`` to add an immutable database.
``.add_database()`` returns the Database instance, with its name set as the ``database.name`` attribute. Any time you are working with a newly added database you should use the return value of ``.add_database()``, for example:
.. code-block:: python
db = datasette.add_database(
Database(datasette, memory_name="statistics")
)
await db.execute_write(
"CREATE TABLE foo(id integer primary key)"
)
.. _datasette_add_memory_database:
.add_memory_database(name)
--------------------------
Adds a shared in-memory database with the specified name:
.. code-block:: python
datasette.add_memory_database("statistics")
This is a shortcut for the following:
.. code-block:: python
from datasette.database import Database
datasette.add_database(
Database(datasette, memory_name="statistics")
)
Using either of these pattern will result in the in-memory database being served at ``/statistics``.
.. _datasette_remove_database:
.remove_database(name)
----------------------
``name`` - string
The name of the database to be removed.
This removes a database that has been previously added. ``name=`` is the unique name of that database.
.. _datasette_sign:
.sign(value, namespace="default")
---------------------------------
``value`` - any serializable type
The value to be signed.
``namespace`` - string, optional
An alternative namespace, see the `itsdangerous salt documentation <https://itsdangerous.palletsprojects.com/en/1.1.x/serializer/#the-salt>`__.
Utility method for signing values, such that you can safely pass data to and from an untrusted environment. This is a wrapper around the `itsdangerous <https://itsdangerous.palletsprojects.com/>`__ library.
This method returns a signed string, which can be decoded and verified using :ref:`datasette_unsign`.
.. _datasette_unsign:
.unsign(value, namespace="default")
-----------------------------------
``signed`` - any serializable type
The signed string that was created using :ref:`datasette_sign`.
``namespace`` - string, optional
The alternative namespace, if one was used.
Returns the original, decoded object that was passed to :ref:`datasette_sign`. If the signature is not valid this raises a ``itsdangerous.BadSignature`` exception.
.. _datasette_add_message:
.add_message(request, message, type=datasette.INFO)
---------------------------------------------------
``request`` - Request
The current Request object
``message`` - string
The message string
``type`` - constant, optional
The message type - ``datasette.INFO``, ``datasette.WARNING`` or ``datasette.ERROR``
Datasette's flash messaging mechanism allows you to add a message that will be displayed to the user on the next page that they visit. Messages are persisted in a ``ds_messages`` cookie. This method adds a message to that cookie.
You can try out these messages (including the different visual styling of the three message types) using the ``/-/messages`` debugging tool.
.. _datasette_absolute_url:
.absolute_url(request, path)
----------------------------
``request`` - Request
The current Request object
``path`` - string
A path, for example ``/dbname/table.json``
Returns the absolute URL for the given path, including the protocol and host. For example:
.. code-block:: python
absolute_url = datasette.absolute_url(
request, "/dbname/table.json"
)
# Would return "http://localhost:8001/dbname/table.json"
The current request object is used to determine the hostname and protocol that should be used for the returned URL. The :ref:`setting_force_https_urls` configuration setting is taken into account.
.. _datasette_setting:
.setting(key)
-------------
``key`` - string
The name of the setting, e.g. ``base_url``.
Returns the configured value for the specified :ref:`setting <settings>`. This can be a string, boolean or integer depending on the requested setting.
For example:
.. code-block:: python
downloads_are_allowed = datasette.setting("allow_download")
.. _datasette_resolve_database:
.resolve_database(request)
--------------------------
``request`` - :ref:`internals_request`
A request object
If you are implementing your own custom views, you may need to resolve the database that the user is requesting based on a URL path. If the regular expression for your route declares a ``database`` named group, you can use this method to resolve the database object.
This returns a :ref:`Database <internals_database>` instance.
If the database cannot be found, it raises a ``datasette.utils.asgi.DatabaseNotFound`` exception - which is a subclass of ``datasette.utils.asgi.NotFound`` with a ``.database_name`` attribute set to the name of the database that was requested.
.. _datasette_resolve_table:
.resolve_table(request)
-----------------------
``request`` - :ref:`internals_request`
A request object
This assumes that the regular expression for your route declares both a ``database`` and a ``table`` named group.
It returns a ``ResolvedTable`` named tuple instance with the following fields:
``db`` - :ref:`Database <internals_database>`
The database object
``table`` - string
The name of the table (or view)
``is_view`` - boolean
``True`` if this is a view, ``False`` if it is a table
If the database or table cannot be found it raises a ``datasette.utils.asgi.DatabaseNotFound`` exception.
If the table does not exist it raises a ``datasette.utils.asgi.TableNotFound`` exception - a subclass of ``datasette.utils.asgi.NotFound`` with ``.database_name`` and ``.table`` attributes.
.. _datasette_resolve_row:
.resolve_row(request)
---------------------
``request`` - :ref:`internals_request`
A request object
This method assumes your route declares named groups for ``database``, ``table`` and ``pks``.
It returns a ``ResolvedRow`` named tuple instance with the following fields:
``db`` - :ref:`Database <internals_database>`
The database object
``table`` - string
The name of the table
``sql`` - string
SQL snippet that can be used in a ``WHERE`` clause to select the row
``params`` - dict
Parameters that should be passed to the SQL query
``pks`` - list
List of primary key column names
``pk_values`` - list
List of primary key values decoded from the URL
``row`` - ``sqlite3.Row``
The row itself
If the database or table cannot be found it raises a ``datasette.utils.asgi.DatabaseNotFound`` exception.
If the table does not exist it raises a ``datasette.utils.asgi.TableNotFound`` exception.
If the row cannot be found it raises a ``datasette.utils.asgi.RowNotFound`` exception. This has ``.database_name``, ``.table`` and ``.pk_values`` attributes, extracted from the request path.
.. _internals_datasette_client:
datasette.client
----------------
Plugins can make internal simulated HTTP requests to the Datasette instance within which they are running. This ensures that all of Datasette's external JSON APIs are also available to plugins, while avoiding the overhead of making an external HTTP call to access those APIs.
The ``datasette.client`` object is a wrapper around the `HTTPX Python library <https://www.python-httpx.org/>`__, providing an async-friendly API that is similar to the widely used `Requests library <https://requests.readthedocs.io/>`__.
It offers the following methods:
``await datasette.client.get(path, **kwargs)`` - returns HTTPX Response
Execute an internal GET request against that path.
``await datasette.client.post(path, **kwargs)`` - returns HTTPX Response
Execute an internal POST request. Use ``data={"name": "value"}`` to pass form parameters.
``await datasette.client.options(path, **kwargs)`` - returns HTTPX Response
Execute an internal OPTIONS request.
``await datasette.client.head(path, **kwargs)`` - returns HTTPX Response
Execute an internal HEAD request.
``await datasette.client.put(path, **kwargs)`` - returns HTTPX Response
Execute an internal PUT request.
``await datasette.client.patch(path, **kwargs)`` - returns HTTPX Response
Execute an internal PATCH request.
``await datasette.client.delete(path, **kwargs)`` - returns HTTPX Response
Execute an internal DELETE request.
``await datasette.client.request(method, path, **kwargs)`` - returns HTTPX Response
Execute an internal request with the given HTTP method against that path.
These methods can be used with :ref:`internals_datasette_urls` - for example:
.. code-block:: python
table_json = (
await datasette.client.get(
datasette.urls.table(
"fixtures", "facetable", format="json"
)
)
).json()
``datasette.client`` methods automatically take the current :ref:`setting_base_url` setting into account, whether or not you use the ``datasette.urls`` family of methods to construct the path.
For documentation on available ``**kwargs`` options and the shape of the HTTPX Response object refer to the `HTTPX Async documentation <https://www.python-httpx.org/async/>`__.
.. _internals_datasette_urls:
datasette.urls
--------------
The ``datasette.urls`` object contains methods for building URLs to pages within Datasette. Plugins should use this to link to pages, since these methods take into account any :ref:`setting_base_url` configuration setting that might be in effect.
``datasette.urls.instance(format=None)``
Returns the URL to the Datasette instance root page. This is usually ``"/"``.
``datasette.urls.path(path, format=None)``
Takes a path and returns the full path, taking ``base_url`` into account.
For example, ``datasette.urls.path("-/logout")`` will return the path to the logout page, which will be ``"/-/logout"`` by default or ``/prefix-path/-/logout`` if ``base_url`` is set to ``/prefix-path/``
``datasette.urls.logout()``
Returns the URL to the logout page, usually ``"/-/logout"``
``datasette.urls.static(path)``
Returns the URL of one of Datasette's default static assets, for example ``"/-/static/app.css"``
``datasette.urls.static_plugins(plugin_name, path)``
Returns the URL of one of the static assets belonging to a plugin.
``datasette.urls.static_plugins("datasette_cluster_map", "datasette-cluster-map.js")`` would return ``"/-/static-plugins/datasette_cluster_map/datasette-cluster-map.js"``
``datasette.urls.static(path)``
Returns the URL of one of Datasette's default static assets, for example ``"/-/static/app.css"``
``datasette.urls.database(database_name, format=None)``
Returns the URL to a database page, for example ``"/fixtures"``
``datasette.urls.table(database_name, table_name, format=None)``
Returns the URL to a table page, for example ``"/fixtures/facetable"``
``datasette.urls.query(database_name, query_name, format=None)``
Returns the URL to a query page, for example ``"/fixtures/pragma_cache_size"``
These functions can be accessed via the ``{{ urls }}`` object in Datasette templates, for example:
.. code-block:: jinja
<a href="{{ urls.instance() }}">Homepage</a>
<a href="{{ urls.database("fixtures") }}">Fixtures database</a>
<a href="{{ urls.table("fixtures", "facetable") }}">facetable table</a>
<a href="{{ urls.query("fixtures", "pragma_cache_size") }}">pragma_cache_size query</a>
Use the ``format="json"`` (or ``"csv"`` or other formats supported by plugins) arguments to get back URLs to the JSON representation. This is the path with ``.json`` added on the end.
These methods each return a ``datasette.utils.PrefixedUrlString`` object, which is a subclass of the Python ``str`` type. This allows the logic that considers the ``base_url`` setting to detect if that prefix has already been applied to the path.
.. _internals_database:
Database class
==============
Instances of the ``Database`` class can be used to execute queries against attached SQLite databases, and to run introspection against their schemas.
.. _database_constructor:
Database(ds, path=None, is_mutable=True, is_memory=False, memory_name=None)
---------------------------------------------------------------------------
The ``Database()`` constructor can be used by plugins, in conjunction with :ref:`datasette_add_database`, to create and register new databases.
The arguments are as follows:
``ds`` - :ref:`internals_datasette` (required)
The Datasette instance you are attaching this database to.
``path`` - string
Path to a SQLite database file on disk.
``is_mutable`` - boolean
Set this to ``False`` to cause Datasette to open the file in immutable mode.
``is_memory`` - boolean
Use this to create non-shared memory connections.
``memory_name`` - string or ``None``
Use this to create a named in-memory database. Unlike regular memory databases these can be accessed by multiple threads and will persist an changes made to them for the lifetime of the Datasette server process.
The first argument is the ``datasette`` instance you are attaching to, the second is a ``path=``, then ``is_mutable`` and ``is_memory`` are both optional arguments.
.. _database_hash:
db.hash
-------
If the database was opened in immutable mode, this property returns the 64 character SHA-256 hash of the database contents as a string. Otherwise it returns ``None``.
.. _database_execute:
await db.execute(sql, ...)
--------------------------
Executes a SQL query against the database and returns the resulting rows (see :ref:`database_results`).
``sql`` - string (required)
The SQL query to execute. This can include ``?`` or ``:named`` parameters.
``params`` - list or dict
A list or dictionary of values to use for the parameters. List for ``?``, dictionary for ``:named``.
``truncate`` - boolean
Should the rows returned by the query be truncated at the maximum page size? Defaults to ``True``, set this to ``False`` to disable truncation.
``custom_time_limit`` - integer ms
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.
``page_size`` - integer
Set a custom page size for truncation, over-riding the configured Datasette default.
``log_sql_errors`` - boolean
Should any SQL errors be logged to the console in addition to being raised as an error? Defaults to ``True``.
.. _database_results:
Results
-------
The ``db.execute()`` method returns a single ``Results`` object. This can be used to access the rows returned by the query.
Iterating over a ``Results`` object will yield SQLite `Row objects <https://docs.python.org/3/library/sqlite3.html#row-objects>`__. Each of these can be treated as a tuple or can be accessed using ``row["column"]`` syntax:
.. code-block:: python
info = []
results = await db.execute("select name from sqlite_master")
for row in results:
info.append(row["name"])
The ``Results`` object also has the following properties and methods:
``.truncated`` - boolean
Indicates if this query was truncated - if it returned more results than the specified ``page_size``. If this is true then the results object will only provide access to the first ``page_size`` rows in the query result. You can disable truncation by passing ``truncate=False`` to the ``db.query()`` method.
``.columns`` - list of strings
A list of column names returned by the query.
``.rows`` - list of ``sqlite3.Row``
This property provides direct access to the list of rows returned by the database. You can access specific rows by index using ``results.rows[0]``.
``.first()`` - row or None
Returns the first row in the results, or ``None`` if no rows were returned.
``.single_value()``
Returns the value of the first column of the first row of results - but only if the query returned a single row with a single column. Raises a ``datasette.database.MultipleValues`` exception otherwise.
``.__len__()``
Calling ``len(results)`` returns the (truncated) number of returned results.
.. _database_execute_fn:
await db.execute_fn(fn)
-----------------------
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``.
Example usage:
.. code-block:: python
def get_version(conn):
return conn.execute(
"select sqlite_version()"
).fetchall()[0][0]
version = await db.execute_fn(get_version)
.. _database_execute_write:
await db.execute_write(sql, params=None, block=True)
-----------------------------------------------------
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.
This method can be used to queue up a non-SELECT SQL query to be executed against a single write connection to the database.
You can pass additional SQL parameters as a tuple or dictionary.
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.
If you pass ``block=False`` this behaviour 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.
.. _database_execute_write_script:
await db.execute_write_script(sql, block=True)
-----------------------------------------------