transparency-information-language/python-tilt

python-tilt is a Python based language binding for the Transparency Information Language and Toolkit.

python-tilt | Transparency Information Language and Toolkit

What is the Transparency Information Language and Toolkit?

With this proposed schema for transparency information with regards to data privacy, an essential step towards a sophisticated ecosystem shall be made by introducing a transparency enhancing toolkit based on a formal language model describing transparency information in the context of multi-service environments and latest legal requirements (EU General Data Protection Regulation). The desired results of the work should be suitable as ready-to-use privacy engineering solutions for developers and serve as a starting point for further research in this area. Eventually, data subjects should (be able to) understand what happens to data relating to them by using the interfaces of the toolkit.

What is python-tilt?

tilt is a Python based language binding for the Transparency Information Language and Toolkit.

Installation

Install the python client library using pip. See the project page.

foo@bar:~$ pip3 install tilt
Collecting tilt
  Using cached tilt-0.0.1-py3-none-any.whl (22 kB)
Installing collected packages: tilt
Successfully installed tilt-0.0.1

Basic usage

See here for an interactive playground , in which you can run python-tilt in a Juypter notebook.

1. Import the transparency information language binding/library.
2. Create your first object, e.g. a Data Protection Officer with their contact details.
3. Continue creating your objects, i.e. a Controller and its Representative.
4. ... (add all other fields, not shown in here) ...

from tilt import tilt

dpo = tilt.DataProtectionOfficer(name='Max Ninjaturtle', address='21 Jump Street', country='DE', email='[email protected]', phone='0142 43333')
print(dpo.to_dict())
# {'address': '21 Jump Street', 'country': 'DE', 'email': '[email protected]', 'name': 'Max Ninjaturtle', 'phone': '0142 43333'}


r = tilt.ControllerRepresentative(name='Maxi Müller', email='[email protected]', phone=None)
c = tilt.Controller(name='MyCompany', address='Straße des 17. Juni', country='DE', division='Main', representative=r)
print(c.to_dict())
# {'address': 'Straße des 17. Juni', 'country': 'DE', 'division': 'Main', 'name': 'MyCompany', 'representative': {'email': '[email protected]', 'name': 'Maxi Müller', 'phone': None}}

Import existing documents

In order to import exisiting tilt documents (we call them instances), you can use your favorite HTTP client or load from your local disk. Then you can use the native python objects and do any manipulations as you like.

import json
import requests

file = requests.get('https://raw.githubusercontent.com/Transparency-Information-Language/schema/master/tilt.json')
instance = tilt.tilt_from_dict(json.loads(file.content))

print(instance.controller.to_dict())
# {'address': 'Wolfsburger Ring 2, 38440 Berlin', 'country': 'DE', 'division': 'Product line e-mobility', 'name': 'Green Company AG', 'representative': {'email': '[email protected]', 'name': 'Jane Super', 'phone': '0049 151 1234 5678'}}

for element in list(instance.data_disclosed):
    for recipient in element.recipients:
        print(recipient.category)
# Marketing content provider
# Responsible Statistical Institutes


instance.controller.name = 'Yellow Company Ltd.'
print(instance.controller.to_dict())
# {'address': 'Wolfsburger Ring 2, 38440 Berlin', 'country': 'DE', 'division': 'Product line e-mobility', 'name': 'Yellow Company Ltd.', 'representative': {'email': '[email protected]', 'name': 'Jane Super', 'phone': '0049 151 1234 5678'}}

Create new documents from scratch

In the example below we are using standard libraries (e.g. sha256 or datetime) in order to create formatted strings. All objects have from_dict() and to_dict() functions which help you to build or export them.

from hashlib import sha256
from datetime import datetime

result = {}
result["_hash"] = sha256('<insert hashable content here>'.encode('utf-8')).hexdigest()
result["_id"] = '<your-id-01>'
result["created"] = '2020-10-02T22:08:12.510696'
result["language"] = 'en'
result["modified"] = datetime.now().isoformat()
result["name"] = 'Green Compancy SE'
result["status"] = 'active'
result["url"] = 'https://greencompany.implementation.cloud'
result["version"] = 42

meta = tilt.Meta.from_dict(result)

print(meta)
# <tilt.tilt.Meta object at 0x7fef287928d0>

print(meta.to_dict())
# {'_hash': 'bd8f3c314b73d85175c8ccf15b4b8d26348beca96c9df39ba98fa5dda3f60fcc', '_id': '<your-id-01>', 'created': '2020-10-02T22:08:12.510696', 'language': 'en', 'modified': '2020-07-27T15:14:35.689606', 'name': 'Green Compancy SE', 'status': 'active', 'url': 'https://greencompany.implementation.cloud', 'version': 42}

Validate documents

See the following example code on how to validate documents using fastjsonschema.

import fastjsonschema
import json

import requests

# Load schema to validate against
file = requests.get('https://raw.githubusercontent.com/Transparency-Information-Language/schema/master/tilt-schema.json')
schema = json.loads(file.content)

# Load instance/document to validate;
# you may use your own tilt object with .to_dict() here
file = requests.get('https://raw.githubusercontent.com/Transparency-Information-Language/schema/master/tilt.json')
instance = json.loads(file.content)

# Compile schema
validate_func = fastjsonschema.compile(schema)

# Validate instance against schema
validate_func(instance)
## {'meta': {'_id': 'f1424f86-ca0f-4f0c-9438-43cc00509931', 'name': 'Green Company', 'created': '2020-04-03T15:53:05.929588', 'modified': '2020-04-03T15:53:05.929588',...
## => document is valid


# Load another example
file = requests.get('https://raw.githubusercontent.com/Transparency-Information-Language/schema/master/tilt-NOT-valid.json')
instance = json.loads(file.content)

# Validate another example
validate_func(instance)
## JsonSchemaException: data.controller must contain ['name', 'address', 'country', 'representative'] properties
## => document is invalid

Author

Elias Grünewald

License

MIT License

python-tilt's Issues

storage item does not get mapped correctly

Although a document compiles valid against the schema, python-tilt does not instantiate correctly, when certain fields are missing for the storageitem.

Works:

      "storage": [],

Does not work:

      "storage": [
        {
          "temporal": [
            {
              "description": "Die übermittelten Daten werden einen Monat nach Abwicklung der Bestellung gelöscht.",
              "ttl": "P1M"
            }
          ],
          "aggregationFunction": "max"
        }
      ],

Workaround (add empty lists):

      "storage": [
        {
          "temporal": [
            {
              "description": "Die übermittelten Daten werden einen Monat nach Abwicklung der Bestellung gelöscht.",
              "ttl": "P1M"
            }
          ],
          "purposeConditional": [],
          "legalBasisConditional" : [],
          "aggregationFunction": "max"
        }
      ],

(Thanks, Flora!)

from_dict in AdmnisitrativeFee causes AssertionError for None Values

I want to report a Bug for the Class of Administrative Fee.
When I want to initiate AdministatriveFee via from_dict I get an AssertionError.
The Error is caused by not accounting for None Entries in the input data. When from_float is called on a None Value within the Class it can not initiate an AdministrativeFee Object.

To Reproduce

Input_Data:
{'amount': None, 'currency': None}

Respective Class:

class AdministrativeFee:
    """The fee that refers to several copies."""
    """The amount of money to be paid for a copy."""
    amount: float
    """The currency in which the amount of money for one copy has to be provided acc. to ISO
    4217.
    """
    currency: str

    def __init__(self, amount: float, currency: str) -> None:
        self.amount = amount
        self.currency = currency

    @staticmethod
    def from_dict(obj: Any) -> 'AdministrativeFee':
        assert isinstance(obj, dict)
        amount = from_float(obj.get("amount"))
        currency = from_str(obj.get("currency"))
        return AdministrativeFee(amount, currency)

    def to_dict(self) -> dict:
        result: dict = {}
        result["amount"] = to_float(self.amount)
        result["currency"] = from_str(self.currency)
        return result

Code:

input_data = {'amount': None, 'currency': None}
fee = AdministrativeFee.from_dict(input_data)

Output:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/gebauer/Desktop/repo/chatbot/.venv/lib/python3.7/site-packages/tilt/tilt.py", line 87, in from_dict
    amount = from_float(obj.get("amount"))
  File "/home/gebauer/Desktop/repo/chatbot/.venv/lib/python3.7/site-packages/tilt/tilt.py", line 18, in from_float
    assert isinstance(x, (float, int)) and not isinstance(x, bool)
AssertionError