Type Reference

A type expression is either a Python hint or an instance of the Portable type. Python hints are constructions of class names and syntax tokens (e.g. [). The list of potential class names include;

• a basic Python type, e.g. float

• a Python hint, e.g. list[float]

• a basic library type, e.g. TimeDelta

• a registered class, e.g. Customer

Instances of Portable are constructed from one of the basic library types plus those types listed as additional types. All library types derive from Portable;

• Boolean()

• VectorOf(Block())

• MapOf(Unicode(),ArrayOf(Integer8(), 4))

Library types are constructed from instances, e.g. VectorOf(Address()). The Python hint facility does not accept instances, leaving no room for ambiguity between the two type systems.

Basic Python Types

The Python types that are accepted as a hint class, along with their respective library equivalents, are listed below.

Python	Library	Notes
bool	Boolean	True or false.
int	Integer8	A large, signed integer.
Enum	UserDefined	Subclass of Enum. A name for a number.
float	Float8	A large, floating-point number.
bytearray	Block	A sequence of arbitrary bytes.
bytes	String	A sequence of printable bytes.
str	Unicode	A sequence of Unicode codepoints.
datetime	WorldTime	A datetime object.
timedelta	TimeDelta	The difference between two datetime objects.
uuid.UUID	UUID	A UUID from the standard Python library.

Enumerations are defined as sub-classes of Enum;

from enum import Enum

class ScopeOfDirectory(Enum):
    LAN=1
    HOST=2
    GROUP=3

Python Hints

Structured Python hints are accepted on declaration of functions and classes, and as a part of input processing. These hints accept one or more hints as parameters. This is a recursive definition, e.g. dict[int,deque[float]].

Python	Library	Notes
list	VectorOf	Zero or more instances of object.
deque	DequeOf	A double-ended queue of objects.
set	SetOf	A collection of unique objects.
dict	MapOf	A collection of key-value pairs.

Basic Library Types

The kipjak types that are accepted as a hint class, along with their respective Python equivalents, are listed below.

Library	Python	Notes
Boolean	bool	True or false.
Byte	int	A single arbitrary byte.
Character	bytes	A single printable byte.
Rune	str	A single Unicode code-point.
Integer8	int	Signed integer numbers.
Float8	float	Signed, floating-point numbers
Block	bytearray	A sequence of arbitrary bytes.
String	bytes	A sequence of printable bytes.
Unicode	str	A sequence of Unicode codepoints.
ClockTime	float	A local time, i.e. float.
TimeSpan	float	A local time delta, i.e. float.
WorldTime	datetime	A date, time and timezone.
TimeDelta	timedelta	A time delta, i.e. t2 - t1.
UUID	UUID	A Python uuid.UUID.
Any		A message
Type	class	A registered class, e.g. Person.
Word		A generic form.
Address		Runtime object identity.

There are multiple library types that are implemented using common Python types. A float is used to hold Float8, ClockTime and TimeSpan values. The difference is about representation within an encoding.

If a schedule_changes() function is defined with a parameter adjustment: TimeSpan=0.0 then the value is expected to be a floating-point value such as 0.0. If the function is called from the command-line as a process entry-point, values must be expressed in the TimeSpan representation;

$ python3 schedule-changes.py --adjustment=1d2h

This is more human-friendly than expecting the entry of 93600.0. The same conversions are happening for network encodings. When debugging network messages at lower levels, members defined with the TimeSpan library type will appear as JSON strings like "2m34.1s" rather than 154.1.

Additional Library Types

The kipjak types that involve additional information and therefore cannot appear as a hint class, appear below. Types such as VectorOf(expression) are passed a library type expression as an argument. This is a recursive definition. Also note that VectorOf expects an instance of an expression not the class, i.e. Integer8() rather than Integer8.

Instances of these types can only appear at registration time using bind(), around the use of select(), and around machine dispatching.

Library	Python	Notes
ArrayOf	list	Fixed number of objects.
VectorOf	list	A sequence of zero or more objects.
SetOf	set	A collection of unique objects.
MapOf	dict	A collection of key-value pairs.
DequeOf	deque	A double-ended queue of objects.
UserDefined	class	An instance of a registered class.
PointerTo		An object that may appear multiple times in the single representation.

Strings Of Things

The Byte, Character and Rune types facilitate the proper handling of an arbitrary byte, a printable byte and a Unicode code-point, respectively. There are no exact Python equivalents for these types as Python stores these values as “strings of length 1”. They can be used in type expressions for finer control over the representation of those short strings.

The Block, String and Unicode types describe sequences of Byte, Character and Rune, respectively.

The String and Block types result in different representations of the same application data, i.e. a sequence of bytes. The former assumes that there is a benefit to passing on the printable bytes (0x20 through to 0x7E) without alteration, i.e. for readability. The non-printing bytes will be “escaped” using the mechanism appropriate to the current encoding.

The Block type is intended for the handling of binary data, such as the block-by-block transfer of image files. Sending a Block across a network connection is the optimal use of bandwidth. It receives pass-through behaviour, i.e. it is streamed directly onto outgoing buffers. A Block within a message is represented as a base64-encoded JSON string, with all the attendant encoding and decoding behaviour.

Dates, Times And Zones

The library types associated with time values appear below;

Library	Python	Notes
ClockTime	float	A local time, i.e. float.
TimeSpan	float	A local time delta, i.e. float.
WorldTime	datetime	A date, time and timezone.
TimeDelta	timedelta	A time delta, i.e. t2 - t1.

The library supports the two styles of time values; float-based values that record the number of seconds since an epoch (e.g. January 1, 1970) and datetime objects that hold explicit year, month (etc) values. In general applications will use datetime and timedelta values, but the float-based types are retained for those scenarios where the full sophistication of daylight saving, war-time adjustments and leap seconds, are not needed.

To provide timezone capability, the library allows instances of datetime.timezone for the tzinfo attribute. Assigning a value from any other timezone library, such as dateutil.tz.tzfile or zoneinfo.ZoneInfo, will result in the raising of an exception during encoding. By default all WorldTime values are assigned the datetime.timezone.utc timezone value.

Applications required to manage datetime objects with a variety of timezones, say selected by a user from the set of IANA names, must implement their own conversions between their datetime objects and library datetime objects, i.e. WorldTime.

Object Pointers

The proper type expression for an object that may appear at multiple points in a single encoding operation, looks like;

kj.PointerTo(UserDefined(Person))

The library uses these “pointers” to implement graphs, e.g. linked-lists, trees and networks.