Skip to content
Permalink
Browse files

Documentation for filters, plus new documentation unit test

  • Loading branch information...
simonw committed Apr 15, 2019
1 parent 6da567d commit 2c19a27d15a913e5f3dd443f04067169a6f24634
Showing with 79 additions and 3 deletions.
  1. +61 −3 docs/json_api.rst
  2. +18 −0 tests/test_docs.py
@@ -176,10 +176,68 @@ querystring arguments:

.. _table_arguments:

Special table arguments
-----------------------
Table arguments
---------------

The Datasette table view takes a number of special querystring arguments.

Column filter arguments
~~~~~~~~~~~~~~~~~~~~~~~

You can filter the data returned by the table based on column values using a querystring argument.

``?column__exact=value`` or ``?_column=value``
Returns rows where the specified column exactly matches the value.

``?column__not=value``
Returns rows where the column does not match the value.

``?column__contains=value``
Rows where the string column contains the specified value (``column like "%value%"`` in SQL).

``?column__endswith=value``
Rows where the string column ends with the specified value (``column like "%value"`` in SQL).

``?column__startswith=value``
Rows where the string column starts with the specified value (``column like "value%"`` in SQL).

``?column__gt=value``
Rows which are greater than the specified value.

``?column__gte=value``
Rows which are greater than or equal to the specified value.

The Datasette table view takes a number of special querystring arguments:
``?column__lt=value``
Rows which are less than the specified value.

``?column__lte=value``
Rows which are less than or equal to the specified value.

``?column__like=value``
Match rows with a LIKE clause, case insensitive and with ``%`` as the wildcard character.

``?column__glob=value``
Similar to LIKE but uses Unix wildcard syntax and is case sensitive.

``?column__arraycontains=value``
Works against columns that contain JSON arrays - matches if any of the values in that array match.

This is only available if the ``json1`` SQLite extension is enabled.

``?column__isnull=1``
Matches rows where the column is null.

``?column__notnull=1``
Matches rows where the column is not null.

``?column__isblank=1``
Matches rows where the column is blank, meaning null or the empty string.

``?column__notblank=1``
Matches rows where the column is not blank.

Special table arguments
~~~~~~~~~~~~~~~~~~~~~~~

``?_labels=on/off``
Expand foreign key references for every possible column. See below.
@@ -4,6 +4,7 @@
from click.testing import CliRunner
from datasette import app
from datasette.cli import cli
from datasette.filters import Filters
from pathlib import Path
import pytest
import re
@@ -71,3 +72,20 @@ def documented_views():
@pytest.mark.parametrize("view_class", [v for v in dir(app) if v.endswith("View")])
def test_view_classes_are_documented(documented_views, view_class):
assert view_class in documented_views


@pytest.fixture(scope="session")
def documented_table_filters():
json_api_rst = (docs_path / "json_api.rst").read_text()
section = json_api_rst.split(".. _table_arguments:")[-1]
# Lines starting with ``?column__exact= are docs for filters
return set(
line.split("__")[1].split("=")[0]
for line in section.split("\n")
if line.startswith("``?column__")
)


@pytest.mark.parametrize("filter", [f.key for f in Filters._filters])
def test_table_filters_are_documented(documented_table_filters, filter):
assert filter in documented_table_filters

0 comments on commit 2c19a27

Please sign in to comment.
You can’t perform that action at this time.