?_labels= and ?_label=COL to expand foreign keys in JSON/CSV

These new querystring arguments can be used to request expanded foreign keys
in both JSON and CSV formats.

?_labels=on turns on expansions for ALL foreign key columns

?_label=COLUMN1&_label=COLUMN2 can be used to pick specific columns to expand

e.g. `Street_Tree_List.json?_label=qSpecies&_label=PlantType&_shape=array`

    [
      {
        "rowid": 1,
        "TreeID": 141565,
        "qLegalStatus": 1,
        "qSpecies": {
          "value": 1,
          "label": "Myoporum laetum :: Myoporum"
        },
        "qAddress": "501X Baker St",
        "SiteOrder": 1,
        "qSiteInfo": 1,
        "PlantType": {
          "value": 1,
          "label": "Tree"
        },
        "qCaretaker": 1,
        "qCareAssistant": null,
        "PlantDate": "07/21/1988 12:00:00 AM",
        "DBH": 21,
        "PlotSize": "Width 0ft",
        "PermitNotes": "Permit Number 25401",
        "XCoord": 6000609,
        "YCoord": 2110829,
        "Latitude": 37.7759676911831,
        "Longitude": -122.441396661871,
        "Location": "(37.7759676911831, -122.441396661871)"
      },
      {
        "rowid": 2,
        "TreeID": 232565,
        "qLegalStatus": 2,
        "qSpecies": {
          "value": 2,
          "label": "Metrosideros excelsa :: New Zealand Xmas Tree"
        },
        "qAddress": "940 Elizabeth St",
        "SiteOrder": 1,
        "qSiteInfo": 2,
        "PlantType": {
          "value": 1,
          "label": "Tree"
        },
        "qCaretaker": 1,
        "qCareAssistant": null,
        "PlantDate": "03/20/2017 12:00:00 AM",
        "DBH": 3,
        "PlotSize": "Width 4ft",
        "PermitNotes": "Permit Number 779625",
        "XCoord": 6000396.48544,
        "YCoord": 2101998.8644,
        "Latitude": 37.7517102172731,
        "Longitude": -122.441498017841,
        "Location": "(37.7517102172731, -122.441498017841)"
      }
    ]

The labels option also works for the HTML and CSV views.

HTML defaults to `?_labels=on`, so if you pass `?_labels=off` you can disable
foreign key expansion entirely - or you can use `?_label=COLUMN` to request
just specific columns.

If you expand labels on CSV you get additional columns in the output:

`/Street_Tree_List.csv?_label=qLegalStatus`

    rowid,TreeID,qLegalStatus,qLegalStatus_label...
    1,141565,1,Permitted Site...
    2,232565,2,Undocumented...

I also refactored the existing foreign key expansion code.

Closes #233. Refs #266.

docs/json_api.rst

@@ -163,6 +163,12 @@ Special table arguments
 
 The Datasette table view takes a number of special querystring arguments:
 
+``?_labels=on/off``
+    Expand foreign key references for every possible column. See below.
+
+``?_label=COLUMN1&_label=COLUMN2``
+    Expand foreign key references for one or more specified columns.
+
 ``?_size=1000`` or ``?_size=max``
     Sets a custom page size. This cannot exceed the ``max_returned_rows`` limit
     passed to ``datasette serve``. Use ``max`` to get ``max_returned_rows``.
@@ -197,3 +203,34 @@ The Datasette table view takes a number of special querystring arguments:
 ``?_labels=1``
     Indicates that you would like to expand any foreign key references. These
     will be exposed in the JSON as ``{"value": 3, "label": "Monterey"}``.
+
+Expanding foreign key references
+--------------------------------
+
+Datasette can detect foreign key relationships and resolve those references into
+labels. The HTML interface does this by default for every detected foreign key
+column - you can turn that off using ``?_labels=off``.
+
+You can request foreign keys be expanded in JSON using the ``_labels=on`` or
+``_label=COLUMN`` special querystring parameters. Here's what an expanded row
+looks like::
+
+    [
+        {
+            "rowid": 1,
+            "TreeID": 141565,
+            "qLegalStatus": {
+                "value": 1,
+                "label": "Permitted Site"
+            },
+            "qSpecies": {
+                "value": 1,
+                "label": "Myoporum laetum :: Myoporum"
+            },
+            "qAddress": "501X Baker St",
+            "SiteOrder": 1
+        }
+    ]
+
+The column in the foreign key table that is used for the label can be specified
+in ``metadata.json`` - see :ref:`label_columns`.

docs/metadata.rst

@@ -121,6 +121,7 @@ This will restrict sorting of ``example_table`` to just the ``height`` and
 
 You can also disable sorting entirely by setting ``"sortable_columns": []``
 
+.. _label_columns:
 Specifying the label column for a table
 ---------------------------------------