Guide

Installation

Teleport is available on PyPI, and, if you have pip, you can install it like so:

pip install teleport

Introduction

Teleport is a JSON type system. Its language-agnostic specification asks only for one function to be exported:

>>> from teleport import t

The purpose of the t() function is to map type definitions to value spaces (in this implementation, instances of Type). Conveniently, every type definition is a JSON value and a value space is the set of all JSON values that belong to a type instance. Defining everything in terms of JSON allows us to have a common test suite for all implementations of Teleport.

Type-Checking

To check if a JSON value is of a certain type, we use the check() method:

>>> t("DateTime").check(u"2015-04-05T14:30")
True
>>> t("DateTime").check(u"2007-04-05T14:30 DROP TABLE users;")
False

Both the the t() function and the check() method accepts JSON values as input. Teleport uses the same format to represent JSON as the json module in the Python standard library. Therefore, to type-check a JSON-encoded string, you could do this:

>>> import json
>>> t("Decimal").check(json.loads("3.14159"))
True

Serialization

This implementation provides serialization by extending each type with two methods: from_json() and to_json():

>>> t("DateTime").from_json("2015-04-05T14:30")
datetime.datetime(2015, 4, 5, 14, 30)
>>> t("DateTime").to_json(datetime.datetime(2015, 4, 5, 14, 30))
"2015-04-05T14:30"

For container types they work recursively:

>>> t({"Array": "DateTime"}).from_json(["2015-04-05T14:30"])
[datetime.datetime(2015, 4, 5, 14, 30)]

Implementation notes

Serialization is not mentioned in the Teleport spec because it cannot be defined in a language-agnostic way. Implementations have the freedom to define serialization logic that best fits their programming language, but this functionality cannot be tested by the common test suite.

Concrete and Generic Types

Teleport defines two kinds of types: concrete and generic.

The JSON definition of a concrete type is a string containing its name. For example, the definition of the Boolean type is "Boolean". When you plug that definition into t(), you get an instance of the Boolean type:

>>> t("Boolean")
<teleport.BooleanType at 0x7f56c5183b90>

A generic type’s definition encodes an additional piece of data, a parameter which will be used by t() to create a type instance. For example, the built-in Array type needs a parameter:

>>> t({"Array": "Boolean"})
<teleport.ArrayType at 0x7f56c5194110>

See also

For a list of core types from the Teleport specification, see Built-in Types. To learn how to create custom types, see the Extending Teleport section.