References¶

Complete, technical information for the significant classes, methods and functions in the library, appears here. There is also full coverage of the type expressions that are passed to File and Folder objects, at creation time.

Type Expressions¶

The simplest example of a type expression is when the name of a registered class is passed as an argument:

f = ar.File('job', Job)

There is a desirable clarity to such code - the file named job contains a representation of a Job. For several reasons including ease-of-use and polymorphism, the second argument passed to File is not limited to just names of registered classes. It is actually a facility for describing the content of the job file in a more general and extensible way. Those descriptions are known as type expressions.

A type expression is an instance of one of the following:

a basic Python type, e.g. float
one of the basic Ansar types, e.g. WorldTime
one of the Ansar container types, e.g. MapOf
a registered class (refer to A Short Tour and More About Types)
an object reference (refer to Really Complicated Documents)
an internal Ansar type.

The container types and the object reference type require parameters that include further instances of type expressions. This is a recursive definition that allows for expression of arbitrarily complex types.

Basic Python Types¶

The Python types that are accepted in type expressions, along with their respective Ansar equivalents, are listed below. Internally all Python types are converted to their Ansar equivalents before use.

Either set of types can be used. Using the Python types is probably more Pythonic.

Python	Ansar	Notes
`bool`	`Boolean`	True or false.
`int`	`Integer8`	A large, signed integer.
`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.

Refer to the following section for more information, especially relating to the significance of the different “string” types.

The Ansar Types¶

Full set of Ansar types appears below.

Ansar	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.
Integer n	`int`	Integer2/Integer4/Integer8. Signed integer numbers consuming 2-8 bytes.
Unsigned n	`int`	Unsigned2/Unsigned4/Unsigned8. Unsigned, integer numbers consuming 2-8 bytes.
Float n	`float`	Float4/Float8. Signed, floating- point numbers consuming 4 or 8 bytes.
Enumeration	`int`	Names for operational 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.
ArrayOf(type, size)	`list`	Fixed number of objects.
VectorOf(type)	`list`	A sequence of zero or more objects.
SetOf(type)	`set`	A collection of unique objects.
MapOf(key, type)	`dict`	A collection of key-value pairs.
DequeOf(type)	`deque`	A double-ended queue of objects.
UserDefined(type)		An instance of a registered class.
Any		An instance of any registered class.
PointerTo(type)		An object that may appear multiple times in the single representation.
Type	`class`	A registered class.
Word		A generic form.
Address		Internal use.
TargetAddress		Internal use.

Note

The Ansar type system is a portable type system that must consider other programming languages and machine architectures. Further information on this topic is outside the scope of this document. Suffice to say that the library accepts the Basic Python Types precisely so that Python developers can work within the Python type system, as much as possible.

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. Blocks of bytes are always base64-encoded within representations.

Warning

Application “string” variables containing values in the range of 0 to 255 are entirely valid. However, the specification for the XML encoding does not provide for the representation of all the values in that range. This affects use of the Python bytes type and the library Character and String types.

Variables that contain exclusively “printable” values such as those values from decimal 32 (space) through to decimal 126 (tilde) are safe when using the XML encoding. Where variables may contain values outside that range, e.g. from decimal zero (nul) to decimal 31 (unit separator) and from decimal 127 (del) through to decimal 255, the behaviour of the XML encoding is not fully defined. There are differences relating to the versions of XML (the library generates exclusively XML 1.0 encodings) and the XML parser in use. Note that the library uses the standard Python XML parser for input, but that other tools in a development environment will include their own parser components.

The bytes, Character and String types are best reserved for “printable” content. If there is explicit need for non-printable content then applications should use the JSON encoding.

Numbers And CPUs¶

The Integer, Unsigned and Float types facilitate the proper handling of the implied number types. The full names for these types include a suffix, e.g. Unsigned4, which refers to the number of bytes consumed by that type. The Python type system manages numbers in a different manner, i.e. without the same regard to portability as Ansar.

All type expressions involving numbers should use the Basic Python Types. The wider set of types offered by Ansar relate to the design of application data that must be portable across multiple programming languages and/or CPU architectures. By using the Basic Python Types, an application ensures that data is portable across Python implementations.

User Defined Objects¶

The proper type expression for a registered class looks like:

ar.UserDefined(Job)

The shorthand form Job is accepted. The expression is used to form the proper name-value pairs during storage and perform the proper member assignments during recovery.

The registration of Python classes combined with the UserDefined type expression provides the basis for recovery of fully-realized application types.

To express the concept of “any registered class”, use the following:

ar.Any

Refer to Polymorphic Persistence, in More About Types.

Object Pointers¶

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

ar.PointerTo(Job)

The library uses these “pointers” to manage a collection of shared objects, and to reconstruct references to those objects during a recover operation.

Internal Ansar Types¶

There are a small number of type expressions that exist for internal use. They have limited utility for an application. The Type and Word expressions are used in the implementation of both the Any feature and the Incognito class, the latter used to manage the recovery of unregistered classes.

The Type expression could be used in the following manner:

>>> f = ar.File('registered-class', ar.Type)
>>> f.store(Job)
>>>
>>> r, _ = f.recover()
>>> r
<class '__main__.Job'>

Note

The value being passed to the store() method is a Python class not an instance of that class.

Notes On Usage And Implementation¶

The library needs type expressions to be precise, meticulous and complete. Sustaining those standards at all times is difficult, so the library takes an active role by resolving a few common miscodings.

Using Python Types is Okay¶

Internally the library implements an abstract type system that has broader requirements than only meeting the needs of a Python application. This can be confusing and where there are no broader intentions - e.g. portability of stored materials across languages and CPUs - any such confusion is counter-productive. For this reason the library supports the use of Python types within type expressions. It immediately translates instances of Python types into their library equivalents. There is no runtime difference to the host application.

Type Expressions Are Values¶

There is a fairly subtle difference between what can seem to be a valid type expression and what a properly formed type expression actually needs to be. For this reason all type expressions passed to the library are put through a “clean-it-up” process that makes small adjustments. These are mostly to do with missing parentheses. Consider the type expression:

te = ar.MapOf(ar.Byte, ar.ArrayOf(ar.WorldTime, 4))

This expression is more correctly written as:

te = ar.MapOf(ar.Byte(), ar.ArrayOf(ar.WorldTime(), 4))

The MapOf and ArrayOf objects are expecting further objects as arguments, not the Byte and WorldTime classes that are being passed in the first version. These kinds of errors are insidious and machine-fixable at that point where the expression is presented.

Class Names Are Not Values¶

It is convenient and results in code clarity, but a registered class is not actually a type expression that can be used during operation of the library. Internally all references to registered classes are upgraded to instances of UserDefined. This code:

f = ar.File('job', Job)

Becomes this:

f = ar.File('job', ar.UserDefined(Job))

The library makes significant use of dispatching during its internal operations, based on an item of application data and its associated type expression. Dispatching is much more efficient if it is dealing with the single possibility of UserDefined rather than the list of all the classes that have been registered within the application.

Classes And Methods¶

Portable¶

Definition of the abstract type system.

NO_SUCH_ADDRESS - correct value for a null address
complete_list - a list containing every abstract type
complete_set - a set containing every abstract type

class ansar.encode.portable.Boolean¶: True or false.

class ansar.encode.portable.Byte¶: The smallest unit of data - 8 bit, unsigned integer.

class ansar.encode.portable.Character¶: A byte that more often contains a printable ASCII character, than not.

class ansar.encode.portable.Rune¶: A Unicode codepoint.

class ansar.encode.portable.Integer2¶: A 2-byte, signed integer.

class ansar.encode.portable.Integer4¶: A 4-byte, signed integer.

class ansar.encode.portable.Integer8¶: An 8-byte, signed integer.

class ansar.encode.portable.Unsigned2¶: A 2-byte, unsigned integer.

class ansar.encode.portable.Unsigned4¶: A 4-byte, unsigned integer.

class ansar.encode.portable.Unsigned8¶: An 8-byte, unsigned integer.

class ansar.encode.portable.Float4¶: A 4-byte, floating point number.

class ansar.encode.portable.Float8¶: An 8-byte, floating point number.

class ansar.encode.portable.Block¶: A sequence of Byte.

class ansar.encode.portable.String¶: A sequence of Characters.

class ansar.encode.portable.Unicode¶: A sequence of codepoints.

class ansar.encode.portable.Enumeration(**kv)¶

Integers that have names.

Parameters: kv (dict) – map of strings and their integer value.

to_name(v)¶

Accept an integer and return the related name (string).

Parameters: v (int) – previously registered number.
Returns: associated name.
Return type: str

to_number(k)¶

Accept a name and return the related number.

Parameters: k (str) – previously registered name.
Returns: associated number.
Return type: int

class ansar.encode.portable.ClockTime¶: The time on the wall clock as an epoch value; a float.

class ansar.encode.portable.TimeSpan¶: Difference between two ClockTime values; a float.

class ansar.encode.portable.WorldTime¶: The time at the Greenwich meridian; a datetime object.

class ansar.encode.portable.TimeDelta¶: Difference between two WorldTime values; a timedelta object.

class ansar.encode.portable.UUID¶: An RFC 4122 UUID (random); a uuid.UUID object.

class ansar.encode.portable.ArrayOf(element, size)¶

A fixed-length sequence of elements.

Parameters

element (type expression) – type of the content.
size (int) – fixed size.

class ansar.encode.portable.VectorOf(element)¶

A variable-length sequence of elements.

Parameters: element (type expression) – type of the content.

class ansar.encode.portable.SetOf(element)¶

A collection of unique elements.

Parameters: element (type expression) – type of the content, a hash-able value.

class ansar.encode.portable.MapOf(key, value)¶

A map of unique, key-value pairs.

Parameters

key (type expression) – type of the key, a hash-able value.
value (type expression) – type of the content.

class ansar.encode.portable.DequeOf(element)¶

A double-ended sequence of elements.

Parameters: element (type expression) – type of the content.

class ansar.encode.portable.UserDefined(element)¶

A structure of named elements.

Parameters: element (class) – registered class.

class ansar.encode.portable.Type¶: The unique, portable identity of a registered message.

class ansar.encode.portable.PointerTo(element)¶

An object that refers to another object.

Parameters: element (type expression) – type of the object being pointed to.

class ansar.encode.portable.TargetAddress¶: The address of a receiving object.

class ansar.encode.portable.Address¶: The address of a sending object.

class ansar.encode.portable.Word¶: A well-formed but untyped unit of data.

class ansar.encode.portable.Any(*possibles)¶: The combination of a Type and a Word.

ansar.encode.portable.is_portable(a)¶: Is object a an instance of one of the portable types.

ansar.encode.portable.is_container(a)¶: Is object a an instance of one of the portable container types.

ansar.encode.portable.is_portable_class(c)¶: Is object c one of the portable types.

ansar.encode.portable.is_container_class(c)¶: Is object c one of the portable container types.

ansar.encode.portable.is_address(a)¶: Is object a is a valid point address.

File¶

Storage and recovery of application data using system files.

Two primitives - write_to_file and read_from_file - and the File class to package the common usage patterns.

ansar.encode.file.write_to_file(a, name, expression=None, version=None, encoding=None, what=None, pretty_format=True, **kv)¶: Write a representation of the application date into the named file.

ansar.encode.file.read_from_file(expression, name, encoding=None, what=None, **kv)¶: Recover an application object from the representation loaded from the named file.

class ansar.encode.file.File(name, expression, encoding=None, create_default=False, pretty_format=True, decorate_names=True)¶

Store and recover application values using files.

Parameters

name (str) – name of the file
expression (type expression) – formal description of the content
encoding (class) – selection of representation, defaults to CodecJson
create_default (bool) – return default instance if file not found on read, defaults to False
pretty_format (bool) – generate human-readable file contents, defaults to True
decorate_names (bool) – auto-append an encoding-dependent extension to the file name, defaults to True

store(value, as_version=None, as_name=None, as_path=None)¶

Generate a representation of value and write to the saved name.

Parameters: value (matching the saved type expression) – any application value
Returns: none

recover(upgrade=None, migrate=False, *args, **kwargs)¶

Read from the saved name, parse and marshal into an application value.

Version handling is implemented through the optional upgrade and migrate parameters. These can be used to automate the runtime promotion of the decoded object from a specific previous version to the version current within the application. Refer to Versions, Upgrading And Migration for details.

The return value includes the version of the main decoded object, or None if the encoding and decoding applications are at the same version. This value is the mechanism by which applications can select different code-paths in support of older versions of encoded materials.

Parameters

upgrade (function) – promote decoded object
migrate (bool) – if true, store any upgraded object
args (tuple) – remaining positional parameters
kwargs (dict) – remaining named parameters

Returns

2-tuple of an application value and a version.

Return type

value matching the saved expression and a str

Exceptions raised by `File`¶

class ansar.encode.file.FileFailure(what, name, note, code)¶

Base exception for all file exceptions.

Parameters

what (str) – the failed operation
name (str) – the name of the file
note (str) – a short, helpful description
code (int) – the associated low-level, integer, error code

class ansar.encode.file.FileNotFound(what, name, note)¶: The named file did not exist.

class ansar.encode.file.FileNoAccess(what, name, note)¶: No access or a permissions problem.

class ansar.encode.file.FileNotAFile(what, name, note)¶: Refers to a folder or the path includes a non-folder.

class ansar.encode.file.FileIOFailure(what, name, note, code)¶: A device I/O operation failed.

class ansar.encode.file.FileEncoding(what, name, note)¶: File or object content problem, encoding or decoding failed.

Refer also to Codec exceptions

`Folder`¶

class ansar.encode.folder.Folder(path=None, te=None, re=None, encoding=None, pretty_format=True, decorate_names=True, create_default=False, keys_names=None, make_absolute=True, auto_create=True)¶

Create and manage a collection of application values, using a folder.

Parameters

path (str) – the location in the filesystem
te (type expression) – formal description of the content
re (a Python regular expression) – formal description of expected file names
encoding (class) – selection of representation, defaults to CodecJson
pretty_format (bool) – generate human-readable file contents, defaults to True
decorate_names (bool) – auto-append an encoding-dependent extension to the file name, defaults to True
keys_names (2-tuple of functions) – a key-composer function and a name-composer function
make_absolute (bool) – expand a relative path to be an absolute location, defaults to True
auto_create (bool) – create folders as necessary, defaults to True

folder(name, te=None, re=None, encoding=None, pretty_format=None, decorate_names=None, create_default=None, auto_create=None, keys_names=None)¶

Create a new Folder object representing a sub-folder at the current location.

Parameters

path (str) – the name to be added to the saved path
te (type expression) – formal description of the content
re (a Python regular expression) – formal description of expected file names
encoding (class) – selection of representation, defaults to CodecJson
pretty_format (bool) – generate human-readable file contents, defaults to True
decorate_names (bool) – auto-append an encoding-dependent extension to the file name, defaults to True
keys_names (2-tuple of functions) – a key-composer function and a name-composer function
make_absolute (bool) – expand a relative path to be an absolute location, defaults to True
auto_create (bool) – create folders as necessary, defaults to None

Returns

a new location in the filesystem

Return type

Folder

file(name, te, encoding=None, pretty_format=None, decorate_names=None, create_default=None)¶

Create a new File object representing a file at the current location.

Parameters

name (str) – the name to be added to the saved path
te (type expression) – formal description of the content
encoding (class) – selection of representation, defaults to CodecJson
pretty_format (bool) – generate human-readable file contents, defaults to True
decorate_names (bool) – auto-append an encoding-dependent extension to the file name, defaults to True
create_default (bool) – return default instance on file not found, defaults to False

Returns

a new file in the filesystem

Return type

File

matching()¶

Scan for files in the folder.

Returns: a sequence of filenames matching the Folder criteria.
Return type: str

each()¶

Process the files in the folder.

Returns: a sequence of File objects matching the Folder criteria.
Return type: File

store(values)¶

Store a dict of values as files in the folder.

Parameters: values (dict) – a collection of application values
Returns: None.

recover(upgrade=None, migrate=False, *args, **kwargs)¶

Recover application values from the files in the folder.

A generator function that yields a sequence of tuples that allow the caller to process an entire folder with a clean loop.

All arguments are forwarded to recover().

The return value includes the version of the main decoded object, or None if the encoding and decoding applications are at the same version. This value is the mechanism by which applications can select different code-paths in support of older versions of encoded materials.

Parameters

upgrade (function) – promote decoded object
migrate (bool) – if true, store any upgraded object
args (tuple) – remaining positional parameters
kwargs (dict) – remaining named parameters

Returns

a sequence of 3-tuples, 0) key, 1) the value and 2) a version tag or None

Return type

a 3-tuple

add(values, item)¶

Add a value, both to a dict of values and as a file in the folder.

Parameters

values (dict) – a collection of application values
item (refer to Folder.te) – the value to be added

update(values, item)¶

Update a value, both in a dict of values and as a file in the folder.

Parameters

values (dict) – a collection of application values
item (refer to Folder.te) – the value to be updated

remove(values, item)¶

Remove a value, both from a dict of values and as a file in the folder.

Parameters

values (dict) – a collection of application values
item (refer to Folder.te) – the value to be removed

clear(values)¶

Remove all values, both from a dict of values and as files in the folder.

Parameters: values (dict) – a collection of application values

erase(name)¶

Delete the named file from the folder.

Parameters: name (str) – a name of a file

exists(name=None)¶

Detect the named file, within the folder.

Parameters: name (str) – a name of a file
Returns: does the file exist
Return type: bool

key(item)¶

Generate the stable key for a given application value.

Parameters: item – an application value
Returns: the key
Return type: folder dependent

name(item)¶

Generate the stable filename for a given application value.

Parameters: item – an application value
Returns: the filename
Return type: str

Exceptions raised by `Folder`¶

Refer to File exceptions

`Codec`¶

class ansar.encode.json.CodecJson(return_proxy=None, local_termination=None, pretty_format=False, decorate_names=True)¶

Encoding and decoding of JSON representations.

This class is the default value for the encoding parameter, related to the various store and recover operations of the library. Refer to the base codec class for the significant methods.

class ansar.encode.xml.CodecXml(return_proxy=None, local_termination=None, pretty_format=False, decorate_names=True)¶: Encoding and decoding of XML representations.

class ansar.encode.codec.Codec(extension, w2t, t2w, return_proxy, local_termination, pretty_format, decorate_names)¶

Base class for all codecs, e.g. CodecJson.

encode(value, expression, version=None, space=None)¶

Encode an application value to its portable representation.

Parameters

value (a type consistent with the specified expression) – a runtime application value
expression (type expression) – a formal description of the value
version (string) – an explicit version override

Returns

a portable representation of the value

Return type

str

decode(representation, expression, version=None, space=None)¶

Decode a representation to its final application form.

Parameters

representation (str) – the result of a previous encode operation
expression (a type expression) – a formal description of portable

Returns

an application value

Exceptions raised by `Codec`¶

class ansar.encode.codec.CodecError(note)¶: Base exception for all codec exceptions.

class ansar.encode.codec.CodecUsage(note, *a)¶: Cannot proceed due to its supplied environment such as unusable parameters.

class ansar.encode.codec.CodecFailed(note, *a)¶: Failure during actual encoding or decoding, such as parsing.

`Message And Bind`¶

class ansar.encode.message.Message¶: Internal placeholder class used for dispatching.

class ansar.encode.message.Unknown¶: An abstract class used to indicate an unexpected message.

class ansar.encode.message.Incognito(type_name=None, decoded_word=None, saved_pointers=None)¶

A class that holds the recovered materials of an unregistered message.

Parameters

type_name (str) – portable identity of the associated word
decoded_word (word) – parsed but unmarshaled object

ansar.encode.message.default_byte()¶

Initialize the smallest, integer value, i.e. Byte.

Returns: byte
Return type: int

ansar.encode.message.default_character()¶

Initialize a single, printable character, i.e. Character.

Returns: character
Return type: bytes

ansar.encode.message.default_rune()¶

Initialize a single Unicode codepoint, i.e. Unicode.

Returns: codepoint
Return type: str

ansar.encode.message.default_block()¶

Initialize a sequence of the smallest integers, i.e. Block.

Returns: fresh instance of an empty block
Return type: bytearray

ansar.encode.message.default_string()¶

Initialize a sequence of printable characters, i.e. String.

Returns: an empty sequence of characters
Return type: bytes

ansar.encode.message.default_unicode()¶

Initialize a sequence of Unicode codepoints, i.e. Unicode.

Returns: empty sequence of codepoints
Return type: str

ansar.encode.message.default_world()¶

Initialize a date-and-time variable, i.e. WorldTime.

Returns: the beginning of time
Return type: datetime

ansar.encode.message.default_delta()¶

Initialize a date-and-time delta variable, i.e. TimeDelta.

Returns: no time
Return type: timedelta

ansar.encode.message.default_uuid()¶

Initialize a UUID variable.

Returns: a global, constant UUID value
Return type: uuid.UUID

ansar.encode.message.default_vector()¶

Initialize a vector variable.

Returns: a fresh, empty vector
Return type: list

ansar.encode.message.default_set()¶

Initialize a set variable.

Returns: a fresh, empty set
Return type: set

ansar.encode.message.default_map()¶

Initialize a map variable.

Returns: a fresh, empty map
Return type: dict

ansar.encode.message.default_deque()¶

Initialize a deque variable.

Returns: a fresh, empty double-ended queue
Return type: collections.deque

ansar.encode.message.make(e)¶

Initialize any variable using a type expression.

Parameters: te – see type expression
Returns: an item of application data

ansar.encode.message.make_self(a, schema)¶: Initialize all the members of an object that are not present or set to None, to a useful default.

ansar.encode.message.bind_message(message, object_schema=None, version_history=None, message_trail=True, execution_trace=True, copy_before_sending=True, not_portable=False)¶

Set the type information and runtime controls for the given message type.

Parameters

message (class) – a message class.
object_schema (a map of <name,portable declaration> pairs.) – application-supplied type information.
message_trail (bool) – log every time this message is sent.
version_history (a list of version changes.) – a version table.
execution_trace (bool) – log every time this message is received.
copy_before_sending (bool) – make a copy of the message before each send.
not_portable (bool) – prevent serialization/transfer, e.g. of a file handle.

Returns

nothing.

Values assigned in this function affect the behaviour for all instances of the given type.

Exceptions raised by `Message And Bind`¶

class ansar.encode.message.MessageError¶: Base exception for all message exceptions.

class ansar.encode.message.MessageRegistrationError(name, reason)¶

A request to register a class cannot be fulfilled.

Parameters

name (str) – the name of the class being registered
reason (str) – a short description

`Versioning and Releasing`¶

ansar.encode.release.released_document(doc)¶

Register an application object for saving to disk.

This function registers a document for the purposes of version support. Registered information is used during encoding to select the proper name slice.

Registered materials are also used during building and releasing to enforce the broader application versioning strategy.

Parameters: doc (a registered message type) – the base document type
Returns: None

`Conversions`¶

ansar.encode.convert.clock_to_text(t)¶: Convert host time value to standard clock-on-the-wall time representation. Return string.

ansar.encode.convert.text_to_clock(s)¶: Convert a standard clock-on-the-wall time string to a host time value. Return float.

ansar.encode.convert.span_to_text(s)¶: Convert a host timespan value to a standard text representation. Return string.

ansar.encode.convert.text_to_span(t)¶: Convert a standard text representation of a timespan to a host value. Return float.

ansar.encode.convert.span_break(s)¶: Break down a timespan value into standard quanta. Return tuple.

ansar.encode.convert.world_to_text(dt)¶: Convert datetime value to standard ISO 8601 time representation. Return string.

ansar.encode.convert.text_to_world(s)¶: Convert a standard ISO 8601 string to an application value. Return datetime.

ansar.encode.convert.delta_to_text(d)¶: Convert a TimeDelta value to its text representation. Return string.

ansar.encode.convert.text_to_delta(t)¶: Convert a standard text representation of a time delta to a host value. Return timedelta.

ansar.encode.convert.uuid_to_text(u)¶: Convert a host UUID value to a standard text representation. Return string.

ansar.encode.convert.text_to_uuid(t)¶: Convert a standard text representation to a host UUID value. Return UUID.

Exceptions raised by `Conversions`¶

class ansar.encode.convert.ConversionEncodeFailed(need, text)¶: Exception raised on failure of one of the convert encoding functions.

class ansar.encode.convert.ConversionDecodeFailed(need, text)¶: Exception raised on failure of one of the convert decoding functions.

ValueError

`Shorthands`¶

ansar.encode.convert.clock_now()¶: Query the platform for the current ClockTime epoch. Return float.

ansar.encode.convert.clock_at(year, month, day, hour=0, minute=0, second=0, millisecond=0, microsecond=0)¶: Convert the date and time arguments into a ClockTime epoch. Return float.

ansar.encode.convert.clock_break(t)¶

Break down a ClockTime value into standard quanta. Return a 10-tuple.

A microseconds value is appended to the standard time.struct_time 9-tuple. It is taken from the fractional part of the value returned by time epoch.

[0] Year [1] Month [2] Day of month [3] Hour [4] Minute [5] Second [6] Day of week [7] Day of year [8] Is daylight saving [9] Microseconds

The standard time.localtime function turns a float into Gregorian calendar information. Unfortunately it loses the fractional part of a time epoch along the way, making format conversions a lossy process. This is an implementation that preserves the fractional part but produces a tuple that cannot be presented to time.mktime. This function is retained for special uses and as a record.

ansar.encode.convert.clock_span(days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0)¶: Convert standard time quanta to a host time value. Return float.

ansar.encode.convert.world_now(tz=None)¶: Query the platform for the current WorldTime. Return datetime.

ansar.encode.convert.world_at(year, month, day, hour=0, minute=0, second=0, millisecond=0, microsecond=0, tz=None)¶: Convert the date, time and timezone arguments into a WorldTime. Return datetime.

ansar.encode.convert.world_break(w, tz=None)¶: Break down a WorldTime value into standard quanta. Return tuple.

ansar.encode.convert.world_delta(days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0)¶: Convert the days, hours, minutes and seconds into a TimeSpan epoch difference. Return float.

References¶

Type Expressions¶

Basic Python Types¶

The Ansar Types¶

Strings Of Things¶

Numbers And CPUs¶

User Defined Objects¶

Object Pointers¶

Internal Ansar Types¶

Notes On Usage And Implementation¶

Using Python Types is Okay¶

Type Expressions Are Values¶

Class Names Are Not Values¶

Classes And Methods¶

Portable¶

File¶

Exceptions raised by File¶

Folder¶

Exceptions raised by Folder¶

Codec¶

Exceptions raised by Codec¶

Message And Bind¶

Exceptions raised by Message And Bind¶

Versioning and Releasing¶

Conversions¶

Exceptions raised by Conversions¶

Shorthands¶

Exceptions raised by `File`¶

`Folder`¶

Exceptions raised by `Folder`¶

`Codec`¶

Exceptions raised by `Codec`¶

`Message And Bind`¶

Exceptions raised by `Message And Bind`¶

`Versioning and Releasing`¶

`Conversions`¶

Exceptions raised by `Conversions`¶

`Shorthands`¶