versionedobj package

Submodules

versionedobj.exceptions module

exception versionedobj.exceptions.InputValidationError

Bases: Exception

Exception raised whenever validation of a serialized object fails

exception versionedobj.exceptions.InvalidFilterError

Bases: Exception

Exception raised whenever ‘only’ and ‘ignore’ filters are used at the same time

exception versionedobj.exceptions.InvalidVersionAttributeError

Bases: Exception

Exception raised whenever a nested VersionedObject has a ‘version’ attribute

exception versionedobj.exceptions.LoadObjectError

Bases: Exception

Exception raised whenever saved object data cannot be loaded because of a JSON parser error

versionedobj.object module

class versionedobj.object.CustomValue

Bases: object

Abstract class that can be sub-classed if you want to serialize/deserialize a custom class that the standard JSON parser is not handling the way you want

from_dict(attrs)

Load this object instance with values from a dict returned by json.load

Parameters:

attrs (dict) – object instance data

to_dict()

Convert this object instance to something that is suitable for json.dump

Returns:

object instance data as a dict, or a single value

Return type:

any object

class versionedobj.object.MigrationResult(old_version, target_version, version_reached, success)

Bases: object

Value returned by Serializer.from_dict, Serializer.from_file, and Serializer.from_json methods, if a successful or partial object migration was performed.

Variables:

• old_version – the object version before migration was attempted

• target_version – the target version of the migration (current version)

• version_reached – the actual object version after migration (this should match target_version after a successful migration)

• success (bool) – True if migration was successful, false otherwise

__init__(old_version, target_version, version_reached, success)

class versionedobj.object.VersionedObject(initial_values={})

Bases: object

Versioned object class supporting saving/loading to/from JSON files, and migrating older files to the current version

__init__(initial_values={})

Parameters:

dict – map of initial values. Keys are the field name, and values are the initial values to set.

versionedobj.object.add_migration(migration_func, cls, from_version, to_version)

Add a migration function to an object class. Use this function to register a migration function that should be used for migrating an object from one version to another. This is an equivalent alternative to the versionedobj.objbect.migration decorator.

Parameters:

• migration_func (callable) – Function to call to perform the migration

• cls – Class object to add migration to

• from_version – Version to migrate from. If you are migrating an object that previously had no version number, use ‘None’ here.

• to_version – Version to migrate to

versionedobj.object.migration(cls, from_version, to_version)

Decorator for adding a migration function to an object class. Use this decorator on any function or method that should be used for migrating an object from one version to another. This is an equivalent alternative to the versionedobject.object.add_migration function.

Parameters:

• cls – Class object to add migration to

• from_version – Version to migrate from. If you are migrating an object that previously had no version number, use ‘None’ here.

• to_version – Version to migrate to

versionedobj.serializer module

class versionedobj.serializer.FileLoader(instance_or_class, filename)

Bases: object

Context manager for modifying object data saved to a JSON file. Deserializes the object on entry, if it exists, allowing you to modify the deserialized object, and serializes the changed object data back to the same file on exit.

__init__(instance_or_class, filename)

class versionedobj.serializer.Serializer(obj=None)

Bases: object

Class for serializing/deserializing any VersionedObject types

__init__(obj=None)

from_dict(attrs, obj=None, validate=True, only=[], ignore=[])

Populate instance attributes of a VersionedObjbect instance, with object data from a dict.

Parameters:

• attrs (dict) – dict containing object data

• obj – VersionedObject instance to populate. If unset, object passed to __init__ will be used instead

• validate (bool) – If false, pre-validation will be skipped for the input data. This may be useful if you want to load a partial object that is missing some fields, and don’t want to mess with filtering.

• only (list) – Whitelist of field names to load (cannot be used with blacklist)

• ignore (list) – Blacklist of field names to ignore (cannot be used with whitelist)

Raises:

• versionedobj.exceptions.InputValidationError – if validation of input data fails.

• versionedobj.exceptions.InvalidFilterError – if both ‘only’ and ‘ignore’ are provided.

Returns:

MigrationResult object describing the object migration that was peformed, or None if no object migrations were required

Return type:

MigrationResult

from_file(filename, obj=None, validate=True, only=[], ignore=[])

Populate instance attributes of a VersionedObject instance with object data from a JSON file.

Parameters:

• filename (str) – Name of file to load

• obj – VersionedObject instance to populate. If unset, object passed to __init__ will be used instead

• validate (bool) – If false, pre-validation will be skipped for the input data. This may be useful if you want to load a partial object that is missing some fields, and don’t want to mess with filtering.

• only (list) – Whitelist of field names to load (cannot be used with blacklist)

• ignore (list) – Blacklist of field names to ignore (cannot be used with whitelist)

Raises:

• versionedobj.exceptions.InputValidationError – if validation of input data fails.

• versionedobj.exceptions.LoadObjectError – if JSON parsing fails

• versionedobj.exceptions.InvalidFilterError – if both ‘only’ and ‘ignore’ are provided.

Returns:

MigrationResult object describing the object migration that was peformed, or None if no object migrations were required

Return type:

MigrationResult

from_json(jsonstr, obj=None, validate=True, only=[], ignore=[])

Populate instance attributes of a VersionedObject instance with object data from a JSON string.

Parameters:

• jsonstr (str) – JSON string to load

• obj – VersionedObject instance to populate. If unset, object passed to __init__ will be used instead

• validate (bool) – If false, pre-validation will be skipped for the input data. This may be useful if you want to load a partial object that is missing some fields, and don’t want to mess with filtering.

• only (list) – Whitelist of field names to load (cannot be used with blacklist)

• ignore (list) – Blacklist of field names to ignore (cannot be used with whitelist)

Raises:

• versionedobj.exceptions.InputValidationError – if validation of input data fails.

• versionedobj.exceptions.LoadObjectError – if JSON parsing fails

• versionedobj.exceptions.InvalidFilterError – if both ‘only’ and ‘ignore’ are provided.

Returns:

MigrationResult object describing the object migration that was peformed, or None if no object migrations were required

Return type:

MigrationResult

reset_to_defaults(obj=None)

Resets instance attribute values of a VersionedObject instance back to the default values defined in the matching class attributes.

Parameters:

obj – VersionedObject instance to reset. If unset, object passed to __init__ will be used instead

to_dict(obj=None, only=[], ignore=[])

Convert object to a dict, suitable for passing to the json library

Parameters:

• obj – VersionedObject instance to convert

• only (list) – Whitelist of field names to serialize (cannot be used with blacklist)

• ignore (list) – Blacklist of field names to ignore (cannot be used with whitelist)

Returns:

object data as a dict

Return type:

dict

to_file(filename, obj=None, indent=None, only=[], ignore=[])

Save VersionedObject instance data to a JSON file

Parameters:

• filename (str) – Name of file to write

• obj – VersionedObject instance to serialize. If unset, object passed to __init__ will be used instead.

• indent (int) – Indentation level to use, in columns. If None, everything will be on one line.

• only (list) – Whitelist of field names to serialize (cannot be used with blacklist)

• ignore (list) – Blacklist of field names to ignore (cannot be used with whitelist)

to_json(obj=None, indent=None, only=[], ignore=[])

Generate a JSON string containing all data from a VersionedObject instance

Parameters:

• indent (int) – Indentation level to use, in columns. If None, everything will be on one line.

• obj – VersionedObject instance to serialize. If unset, object passed to __init__ will be used instead

• only (list) – Whitelist of field names to serialize (cannot be used with blacklist)

• ignore (list) – Blacklist of field names to ignore (cannot be used with whitelist)

Returns:

Object data as a JSON string

Return type:

str

validate_dict(attrs, obj=None, only=[], ignore=[])

Validate a versioned object in dict form.

Parameters:

• attrs (dict) – dict to validate

• obj – VersionedObject instance you want to validate the dict against. If unset, object passed to __init__ will be used instead

• only (list) – Whitelist of attribute names to validate (cannot be used with ‘ignore’)

• ignore (list) – Blacklist of attribute names to exclude from validation (cannot be used with ‘only’)

Raises:

• versionedobj.exceptions.InputValidationError – if the dict contains fields that are not found in this object, or if the dict is missing fields that are found in this object.

• versionedobj.exceptions.InvalidFilterError – if both ‘only’ and ‘ignore’ are provided.

versionedobj.types module

class versionedobj.types.ListField(arg)

Bases: CustomValue

List class that allows putting a sequence of VersionedObject instances in a single VersionedObject field. Behaves like a regular python list, except that it can only contain VersionedObject instances, and can only contain instances of the same VersionedObject class.

__init__(arg)

append(v)

Append a value to the list

Parameters:

v (versionedobj.VersionedObject) – value to append

Raises:

ValueError – if v is not an instance of a VersionedObject

from_dict(attrs)

Populate the list with data from a dict

insert(i, v)

Insert a value at a specific position in the list

Parameters:

• i (int) – list position to insert new item at

• v (versionedobj.VersionedObject) – value to insert

Raises:

• ValueError – if v is not an instance of a VersionedObject

• IndexError – if i is not a valid index in the list

to_dict()

Convert the list to JSON-serializable dict

Returns:

serialized dict

versionedobj.utils module

Module contents