Merge pull request #471 from OpenDataServices/final_bods_0_4

Allow passing schema as a Python object

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Put back some translations that were removed
 - Minor python tidyups
 - Avoid deprecation warning from the ijson package.  https://github.com/OpenDataServices/flatten-tool/pull/458
+- Allow passing of schema as Python object, and update docs
 
 ### Removed
 

docs/getting-started.rst

@@ -38,6 +38,27 @@ will print general help information.
 
 will print help information specific to that sub-command.
 
+Library
+-------
+
+The package can also be used as a Python library, e.g. to flatten
+data:
+
+.. code-block:: python
+
+    flattentool.flatten(input_filename, ...)
+
+or unflatten data:
+
+.. code-block:: python
+
+    flattentool.unflatten(input_filename, ...)
+
+In addition to the functionality available from the command-line,
+Python calls to the library functions also accept a Python object
+as a schema rather than a filename. This allows schema objects to
+be loaded/constructed by the calling application.
+
 Python Version Support
 ----------------------
 

flattentool/schema.py

@@ -152,7 +152,9 @@ def __init__(
                 _("Only one of schema_filename or root_schema_dict should be supplied")
             )
         if schema_filename:
-            if schema_filename.startswith("http"):
+            if isinstance(schema_filename, dict):
+                self.root_schema_dict = schema_filename
+            elif schema_filename.startswith("http"):
                 import requests
 
                 r = requests.get(schema_filename)

flattentool/tests/fixtures/basic_1.csv/addresses.csv

@@ -0,0 +1,2 @@
+addresses/0/type,addresses/0/address,addresses/0/postCode,addresses/0/country,statementID
+service,"Aston House, Cornwall Avenue, London",N3 1LF,GB,019a93f1-e470-42e9-957b-03559861b2e2

flattentool/tests/fixtures/basic_1.csv/annotations.csv

@@ -0,0 +1 @@
+annotations/0/statementPointerTarget,annotations/0/creationDate,annotations/0/createdBy/name,annotations/0/createdBy/uri,annotations/0/motivation,annotations/0/description,annotations/0/transformedContent,annotations/0/url

flattentool/tests/fixtures/basic_1.csv/identifiers.csv

@@ -0,0 +1,2 @@
+identifiers/0/id,identifiers/0/scheme,identifiers/0/schemeName,identifiers/0/uri,statementID
+07444723,GB-COH,,,1dc0e987-5c57-4a1c-b3ad-61353b66a9b7

flattentool/tests/fixtures/basic_1.csv/interests.csv

@@ -0,0 +1,2 @@
+interests/0/type,interests/0/directOrIndirect,interests/0/beneficialOwnershipOrControl,interests/0/details,interests/0/share/exact,interests/0/share/maximum,interests/0/share/minimum,interests/0/share/exclusiveMinimum,interests/0/share/exclusiveMaximum,interests/0/startDate,interests/0/endDate,statementID
+shareholding,direct,True,,100,100,100,,,2016-04-06,,fbfd0547-d0c6-4a00-b559-5c5e91c34f5c

flattentool/tests/fixtures/basic_1.csv/main.csv

@@ -0,0 +1,4 @@
+statementID,statementType,statementDate,isComponent,entityType,unspecifiedEntityDetails/reason,unspecifiedEntityDetails/description,name,alternateNames,jurisdiction/name,jurisdiction/code,foundingDate,dissolutionDate,uri,replacesStatements,publicationDetails/publicationDate,publicationDetails/bodsVersion,publicationDetails/license,publicationDetails/publisher/name,publicationDetails/publisher/url,source/type,source/description,source/url,source/retrievedAt,publicListing/hasPublicListing,publicListing/companyFilingsURLs,entitySubtype/generalCategory,entitySubtype/localTerm,formedByStatute/name,formedByStatute/date,personType,unspecifiedPersonDetails/reason,unspecifiedPersonDetails/description,placeOfBirth/type,placeOfBirth/address,placeOfBirth/postCode,placeOfBirth/country,birthDate,deathDate,placeOfResidence/type,placeOfResidence/address,placeOfResidence/postCode,placeOfResidence/country,politicalExposure/status,componentStatementIDs,subject/describedByEntityStatement,interestedParty/describedByEntityStatement,interestedParty/describedByPersonStatement,interestedParty/unspecified/reason,interestedParty/unspecified/description,publicListing/securitiesListings
+1dc0e987-5c57-4a1c-b3ad-61353b66a9b7,entityStatement,2017-11-18,False,registeredEntity,,,CHRINON LTD,,,,2010-11-18,,,,2018-02-13,0.3,,CHRINON LTD,,,,,,True,http://example.com/,,,,,,,,,,,,,,,,,,,,,,,,,
+019a93f1-e470-42e9-957b-03559861b2e2,personStatement,2017-11-18,False,,,,,,,,,,,,2018-02-13,0.3,,CHRINON LTD,,,,,,,,,,,,knownPerson,,,,,,,1964-04,,,,,,,,,,,,,
+fbfd0547-d0c6-4a00-b559-5c5e91c34f5c,ownershipOrControlStatement,2017-11-18,False,,,,,,,,,,,,2018-02-13,0.3,,CHRINON LTD,,,,,,,,,,,,,,,,,,,,,,,,,,,1dc0e987-5c57-4a1c-b3ad-61353b66a9b7,,019a93f1-e470-42e9-957b-03559861b2e2,,,

flattentool/tests/fixtures/basic_1.csv/names.csv

@@ -0,0 +1,3 @@
+names/0/type,names/0/fullName,names/0/familyName,names/0/givenName,names/0/patronymicName,statementID
+individual,Christopher Taggart,Taggart,Christopher,,019a93f1-e470-42e9-957b-03559861b2e2
+alternative,Chris Taggart,,,,019a93f1-e470-42e9-957b-03559861b2e2

flattentool/tests/fixtures/basic_1.csv/nationalities.csv

@@ -0,0 +1,2 @@
+nationalities/0/name,nationalities/0/code,statementID
+United Kingdom of Great Britain and Northern Ireland (the),GB,019a93f1-e470-42e9-957b-03559861b2e2

flattentool/tests/fixtures/basic_1.csv/pol_det_sou_assertedBy.csv

@@ -0,0 +1 @@
+politicalExposure/details/0/source/assertedBy/0/name,politicalExposure/details/0/source/assertedBy/0/uri

flattentool/tests/fixtures/basic_1.csv/pol_details.csv

@@ -0,0 +1 @@
+politicalExposure/details/0/reason,politicalExposure/details/0/missingInfoReason,politicalExposure/details/0/jurisdiction/name,politicalExposure/details/0/jurisdiction/code,politicalExposure/details/0/startDate,politicalExposure/details/0/endDate,politicalExposure/details/0/source/type,politicalExposure/details/0/source/description,politicalExposure/details/0/source/url,politicalExposure/details/0/source/retrievedAt

flattentool/tests/fixtures/basic_1.csv/pub_securitiesListings.csv

@@ -0,0 +1 @@
+publicListing/securitiesListings/0/marketIdentifierCode,publicListing/securitiesListings/0/operatingMarketIdentifierCode,publicListing/securitiesListings/0/stockExchangeJurisdiction,publicListing/securitiesListings/0/stockExchangeName,publicListing/securitiesListings/0/security/idScheme,publicListing/securitiesListings/0/security/id,publicListing/securitiesListings/0/security/ticker

flattentool/tests/fixtures/basic_1.csv/sou_assertedBy.csv

@@ -0,0 +1 @@
+source/assertedBy/0/name,source/assertedBy/0/uri

flattentool/tests/fixtures/basic_1.csv/taxResidencies.csv

@@ -0,0 +1 @@
+taxResidencies/0/name,taxResidencies/0/code

flattentool/tests/fixtures/basic_1.json

@@ -0,0 +1,102 @@
+[
+  {
+    "statementID": "1dc0e987-5c57-4a1c-b3ad-61353b66a9b7",
+    "statementType": "entityStatement",
+    "isComponent": false,
+    "statementDate": "2017-11-18",
+    "entityType": "registeredEntity",
+    "name": "CHRINON LTD",
+    "foundingDate": "2010-11-18",
+    "identifiers": [
+      {
+        "scheme": "GB-COH",
+        "id": "07444723"
+      }
+    ],
+    "publicListing": {
+      "hasPublicListing": true,
+      "companyFilingsURLs": ["http://example.com/"],
+      "securitiesListings": []
+    },
+    "publicationDetails": {
+      "publicationDate": "2018-02-13",
+      "bodsVersion": "0.3",
+      "publisher": {
+        "name": "CHRINON LTD"
+      }
+    }
+  },
+  {
+    "statementID": "019a93f1-e470-42e9-957b-03559861b2e2",
+    "statementType": "personStatement",
+    "isComponent": false,
+    "statementDate": "2017-11-18",
+    "personType": "knownPerson",
+    "nationalities": [
+      {
+        "code": "GB",
+        "name": "United Kingdom of Great Britain and Northern Ireland (the)"
+      }
+    ],
+    "names": [
+      {
+        "type": "individual",
+        "fullName": "Christopher Taggart",
+        "givenName": "Christopher",
+        "familyName": "Taggart"
+      },
+      {
+        "type": "alternative",
+        "fullName": "Chris Taggart"
+      }
+    ],
+    "birthDate": "1964-04",
+    "addresses": [
+      {
+        "type": "service",
+        "address": "Aston House, Cornwall Avenue, London",
+        "country": "GB",
+        "postCode": "N3 1LF"
+      }
+    ],
+    "publicationDetails": {
+      "publicationDate": "2018-02-13",
+      "bodsVersion": "0.3",
+      "publisher": {
+        "name": "CHRINON LTD"
+      }
+    }
+  },
+  {
+    "statementID": "fbfd0547-d0c6-4a00-b559-5c5e91c34f5c",
+    "statementType": "ownershipOrControlStatement",
+    "isComponent": false,
+    "statementDate": "2017-11-18",
+    "subject": {
+      "describedByEntityStatement": "1dc0e987-5c57-4a1c-b3ad-61353b66a9b7"
+    },
+    "interestedParty": {
+      "describedByPersonStatement": "019a93f1-e470-42e9-957b-03559861b2e2"
+    },
+    "interests": [
+      {
+        "type": "shareholding",
+        "directOrIndirect": "direct",
+        "beneficialOwnershipOrControl": true,
+        "startDate": "2016-04-06",
+        "share": {
+          "exact": 100,
+          "minimum": 100,
+          "maximum": 100
+        }
+      }
+    ],
+    "publicationDetails": {
+      "publicationDate": "2018-02-13",
+      "bodsVersion": "0.3",
+      "publisher": {
+        "name": "CHRINON LTD"
+      }
+    }
+  }
+]