sol.models.bio – Batched I/O

This module implements some utilities, mainly related to importing and exporting tourneys data in a portable format.

Scarry used an INI file and we had several drawbacks with it, mainly because sending them with e-mail would result in data corruption.

SoL uses YAML or JSON instead, by default compressing the outcome with gzip.

sol.models.bio.save_changes(sasess, request, modified, deleted, clogger=<Logger sol.models.bio.changes (WARNING)>)

Save insertions, changes and deletions to the database.

Parameters:
  • sasess – the SQLAlchemy session
  • request – the Pyramid web request
  • modified – a sequence of record changes, each represented by a tuple of two items, the PK name and a dictionary with the modified fields; if the value of the PK field is null or 0 then the record is considered new and will be inserted instead of updated
  • deleted – a sequence of deletions, each represented by a tuple of two items, the PK name and the ID of the record to be removed
  • clogger – where to log applied changes
Return type:

tuple
Returns:

three lists, respectively inserted, modified and deleted record IDs, grouped in a dictionary keyed on PK name
sol.models.bio.backup(sasess, pdir, edir, location=None, keep_only_if_changed=True, only_played_tourneys=False, serialization_format='yaml', native_when_possible=False)

Dump almost everything in a ZIP file.

Parameters:
  • sasess – a SQLAlchemy session
  • pdir – the base path of the portrait images, sol.portraits_dir
  • edir – the base path of the emblem images, sol.emblems_dir
  • location – either None or a string
  • keep_only_if_changed – a boolean flag
  • only_played_tourneys – a boolean flag
  • serialization_format – a string, either yaml or json
  • native_when_possible – if True, use the native interface to perform the backup
Return type:

bytes
Returns:

the ZIP archive

This function builds a ZIP archive containing a database dump and two subdirectories portraits and emblems, respectively containing the images associated to the players and to the clubs. When native_when_possible is True and the underlying system permits it the dump is a complete backup of the database, otherwise it is a standard .sol dump made with dump_sol() named everything.sol with all tourneys and all players (that is, not just those who actually played).

If location is given, it may be either the full path name of the output file where the backup will be written or the path of a directory. In the latter case the file name will be automatically computed using current time, giving something like sol-backup_2014-02-03T14:35:12.zip.

When keep_only_if_changed is ``True` (the default) and location is a directory, the newly generated backup will be compared with the previous one (if there is at least one, of course) and if nothing has changed it will be removed.

When only_played_tourneys is True (the default is False), the tourneys “in preparation” (that is, those without played matches) are ignored and not included in the dump.

sol.models.bio.restore(sasess, pdir=None, edir=None, url=None, content=None, idowner=None)

Restore everything from a backup.

Parameters:
  • sasess – a SQLAlchemy session
  • pdir – the base path of the portrait images, sol.portraits_dir
  • edir – the base path of the emblem images, sol.emblems_dir
  • url – the URL of the file containing the archive, or None
  • content – the content of the archive
  • idowner – the ID of the responsible for newly created instances
Return type:

tuple
Returns:

the list of loaded tourney instances and the number of skipped tourneys

This reads the ZIP created by backup() and loads its content into the database, writing the images in the right place (pre-existing images won’t be overwritten, though).

sol.models.bio.load_sol(sasess, url=None, content=None, restore=False, idowner=None)

Load the archive exported from SoL.

Parameters:
  • sasess – a SQLAlchemy session
  • url – the URL of the .sol (or .sol.gz) file
  • content – the content of a .sol (or .sol.gz) file
  • restore – whether this is a restore, False by default
  • idowner – the ID of the responsible for newly created instances
Return type:

tuple
Returns:

the list of loaded tourney instances and number of skipped tournaments

If content is not specified, it will be loaded with urlopen() from the given url.

Normally only missing data is updated, except when restore is True.

sol.models.bio.dump_sol(tourneys, gzipped=False, serialization_format='yaml')

Dump tourneys as a YAML or JSON document.

Parameters:
  • tourneys – the sequence of tourneys to dump
  • gzipped – a boolean indicating whether the output will be compressed with gzip
  • serialization_format – a string, either yaml or json
Return type:

bytes
Returns:

the YAML/JSON document, possibly gzipped
class sol.models.bio.Serializer

Serialize some SoL entities as flat dictionaries.

addChampionship(championship)

Serialize a championship, if not already done.

Parameters:club – a Championship instance
Return type:int
Returns:an integer marker that identify the given championship
addClub(club)

Serialize a club, if not already done.

Parameters:club – a Club instance
Return type:int
Returns:an integer marker that identify the given club
addPlayer(player)

Serialize a player, if not already done.

Parameters:player – a Player instance
Return type:int
Returns:an integer marker that identify the given player
addRate(rate)

Serialize a rate, if not already done.

Parameters:rate – a Rate instance
Return type:int
Returns:an integer marker that identify the given rate
addRating(rating)

Serialize a rating, if not already done.

Parameters:rating – a Rating instance
Return type:int
Returns:an integer marker that identify the given rating
addTourney(tourney)

Serialize a tourney, if not already done.

Parameters:tourney – a Tourney instance
Return type:int
Returns:an integer marker that identify the given tourney
addUser(user)

Serialize a user, if not already done.

Parameters:user – a User instance
Return type:int
Returns:an integer marker that identify the given user
championships = None

A list of serialized championships

clubs = None

A list of serialized clubs

id_map = None

An hash mapping a particular instance to its serial marker

modified = None

Most recent modification timestamp of any serialized entity

players = None

A list of serialized players

rates = None

A list of serialized rates

ratings = None

A list of serialized ratings

tourneys = None

A list of serialized tourneys

users = None

A list of serialized users

class sol.models.bio.Deserializer(session, idowner, update_only_missing_fields)

Deserialize a flat representation of some SoL entities.

addChampionship(schampionship)

Deserialize a Championship.

Parameters:schampionship – a dictionary containing the flatified representation
Return type:Championship
Returns:either an existing or a new instance
addClub(sclub)

Deserialize a Club.

Parameters:sclub – a dictionary containing the flatified representation
Return type:Club
Returns:either an existing or a new instance
addPlayer(splayer)

Deserialize a Player.

Parameters:splayer – a dictionary containing the flatified representation
Return type:Player
Returns:either an existing or a new instance
addRate(srate)

Deserialize a Rate.

Parameters:srate – a dictionary containing the flatified representation
Return type:Rate
Returns:either an existing or a new instance
addRating(srating)

Deserialize a Rating.

Parameters:srating – a dictionary containing the flatified representation
Return type:Rating
Returns:either an existing or a new instance
addTourney(stourney)

Deserialize a Tourney.

Parameters:stourney – a dictionary containing the flatified representation
Return type:Tourney
Returns:either an existing or a new instance
addUser(suser)

Deserialize a User.

Parameters:suser – a dictionary containing the flatified representation
Return type:User
Returns:either an existing or a new instance
championships = None

A list of championships instances.

clubs = None

A list of clubs instances.

idowner = None

The ID of the owner of newly created instances.

players = None

A list of players instances.

rates = None

A list of rates instances.

ratings = None

A list of ratings instances.

session = None

The SQLAlchemy session.

skipped = None

The number of skipped tournaments, because already present.

tourneys = None

A list of tourneys instances.

update_only_missing_fields = None

A boolean flag, whether only missing fields will be updated.

users = None

A list of users instances.