Merge pull request #356 from OpenDataServices/docs-update-kca

Adding array-handling info

Author: Bjwebb

.travis.yml

@@ -12,7 +12,8 @@ install:
   - if [[ $TRAVIS_PYTHON_VERSION != 3.5 ]]; then pip install black==19.10b0; fi
 script:
   - if [[ $TRAVIS_PYTHON_VERSION != 3.5 ]]; then black --check *.py */; fi
-  - isort --check-only --recursive *.py */
+  # isort 5 only runs under Python >= 3.6
+  - if [[ $TRAVIS_PYTHON_VERSION != 3.5 ]]; then isort --check-only --recursive *.py */; fi
   - flake8
   - py.test --cov .
 after_success: coveralls

docs/unflatten.rst

@@ -475,10 +475,10 @@ section.
 Plain Lists (Unsupported)
 -------------------------
 
-Flatten Tool doesn't support arrays of JSON values other than objects (just
-described in the previous section).
+Flatten Tool doesn't recognise arrays of JSON values other than objects (just
+described in the previous section) unless a schema is used.
 
-As a result heading names such as ``tag/0`` and ``tag/1`` would be ignored and an
+Heading names such as ``tag/0`` and ``tag/1`` would be ignored and an
 empty array would be put into the JSON.
 
 Here's some example data:
@@ -494,6 +494,26 @@ And the result:
 .. literalinclude:: ../examples/cafe/plain-list/expected.json
    :language: json
 
+However, an array of tags in the following format (semi-colon separated) can be handled if a schema is passed to Flatten Tool specifying the array type of the field.
+
+.. csv-table::
+   :file: ../examples/cafe/plain-list-schema/data.csv
+   :header-rows: 1
+
+The schema we'll pass is:
+
+.. literalinclude:: ../examples/cafe/plain-list-schema/tagsArraySchema.json
+   :language: json
+
+And the result:
+
+.. literalinclude:: ../examples/cafe/plain-list-schema/cmd.txt
+   :language: bash
+.. literalinclude:: ../examples/cafe/plain-list-schema/expected.json
+   :language: json
+
+Read on for more about typed fields and use of schemas.
+
 
 Typed fields
 ============

examples/cafe/plain-list-schema/cmd.txt

@@ -0,0 +1,2 @@
+$ flatten-tool unflatten -f=csv --root-list-path=cafe --schema=examples/cafe/plain-list-schema/tagsArraySchema.json examples/cafe/plain-list-schema/
+

examples/cafe/plain-list-schema/data.csv

@@ -0,0 +1,3 @@
+name,tags
+Healthy Cafe,health;low-cost;locally sourced food;take-out
+Vegetarian Cafe,veggie

examples/cafe/plain-list-schema/expected.json

@@ -0,0 +1,19 @@
+{
+    "cafe": [
+        {
+            "name": "Healthy Cafe",
+            "tags": [
+                "health",
+                "low-cost",
+                "locally sourced food",
+                "take-out"
+            ]
+        },
+        {
+            "name": "Vegetarian Cafe",
+            "tags": [
+                "veggie"
+            ]
+        }
+    ]
+}

examples/cafe/plain-list-schema/tagsArraySchema.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "properties": {
+        "tags": {
+            "items": {
+                "type": "string"
+            },
+            "type": "array"
+        },
+        "name": {
+          	"type": "string"
+        }
+    }
+}
+

flattentool/cli.py

@@ -9,7 +9,6 @@
 from flattentool.json_input import BadlyFormedJSONError
 from flattentool.output import FORMATS as OUTPUT_FORMATS
 
-
 """
 This file does most of the work of the flatten-tool commandline command.
 

flattentool/schema.py

@@ -15,7 +15,9 @@
 if sys.version_info[:2] > (3, 0):
     import pathlib
 else:
-    import urlparse, urllib
+    import urllib
+
+    import urlparse
 
 
 def get_property_type_set(property_schema_dict):

flattentool/tests/test_docs.py

@@ -133,7 +133,7 @@ def test_example_in_doc(root, filename):
 
 
 def test_expected_number_of_examples_in_docs_data():
-    assert len(examples_in_docs_data) == 56
+    assert len(examples_in_docs_data) == 57
 
 
 def _simplify_warnings(lines):