sol.models – SQLAlchemy modelization — SoL 3 developers documentation

### Navigation

- index
- modules |
- next |
- previous |
- Dev's documentation »
- SoL modules »

# `sol.models` – SQLAlchemy modelization

The application’s model objects

class `sol.models.` `AbstractBase`

  Abstract base entity class.

  `caption`(html=None, localized=True)

    Return an Unicode, possibly HTML-decorated, caption of the entity.

    Parameters: | html – either `None` (the default) or a boolean value localized – a boolean value, `True` by default

    If html is `None` or `True` then the result may be an HTML representation of the entity, otherwise it is plain text.

    If localized is `False` then the localization is turned off.

  classmethod `check_insert`(klass, session, fields)

    Perform any check before an new instance is inserted

  `check_update`(fields)

    Perform any check before updating the instance.

    Parameters: | fields – a mapping containing `fieldname -> value` associations

    This implementation does nothing, but subclasses can override it at will, either to adapt incoming values or to check their validity, raising an exception if something is wrong.

  `delete`()

    Delete this instance from the database.

  `update`(data, missing_only=False)

    Update entity with given data.

    Parameters: | data – a mapping kind of container missing_only – a boolean flag, `False` by default
    Return type: | mapping
    Returns: | a dictionary containing a tuple `(oldvalue, newvalue)` for each modified field

    First call `check_update()` to assert the validity of incoming data, then update the instance fields.

    If missing_only is `True` then only the fields that are currently empty (that is, their value is either `None` or an empty string) are updated. Note that in this case an exception is made for `bool` fields: since in SoL they always have a value (i.e. they are never missing), they are always updated.

class `sol.models.` `GloballyUnique`

  Mixin class for globally unique identified entities.

  `modified` = Column(None, DateTime(), table=None, nullable=False, server_default=DefaultClause(<sqlalchemy.sql.functions.now at 0x7fe428e6cf90; now>, for_update=False))

    Last update timestamp.

## Entities

- Clubs
- Championships
- Competitors
- Matches
- Merged players
- Players
- Tourneys
- Ratings
- Rates

## 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 instead, by default compressing the outcome with gzip.

`sol.models.bio.` `save_changes`(sasess, request, modified, deleted)

  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
  Return type: | a tuple of 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)

  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
  Return type: | a buffer containing the ZIP archive

  This function builds a `ZIP` archive containing both a standard `.sol` dump made with `dump_sol()` named `everything.sol` with all registered tourneys and all registered players (that is, not just those who actually played) and two subdirectories `portraits` and `emblems`, respectively containing the images associated to the players and to the clubs.

  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.

`sol.models.bio.` `restore`(sasess, pdir=None, edir=None, url=None, content=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
  Return type: | a sequence
  Returns: | the list of loaded tourney instances

  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)

  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
  Return type: | a sequence
  Returns: | the list of loaded tourney instances

  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)

  Dump tourneys as a YAML document.

  Parameters: | tourneys – the sequence of tourneys to dump gzipped – a boolean indicating whether the output will be compressed with `gzip`
  Return type: | a YAML formatted string

class `sol.models.bio.` `Serializer`

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

## Utilities

Simple helper functions.

`sol.models.utils.` `asunicode`(s)

  Force a string to be a unicode instance.

  Parameters: | s – any value
  Return type: | str

  If s is not already an unicode string, it is assumed it’s an `utf-8` encoded string, a thus converted to unicode and returned. Otherwise s is returned as is:

      >>> assert asunicode(None) is None
      >>> assert not isinstance(asunicode(b'ascii'), bytes)

`sol.models.utils.` `normalize`(s, title=None)

  Normalize the case of a string, removing spurious spaces.

  Parameters: | s – a string title – if True always titleize the string, if False never do that, if None (default) only when the input string is all lower case or all upper case
  Return type: | unicode

      >>> assert normalize(None) is None
      >>> print(normalize('lele gaifax'))
      Lele Gaifax
      >>> print(normalize('LELE'))
      Lele
      >>> print(normalize('LeLe', title=False))
      LeLe

`sol.models.utils.` `njoin`(elts, stringify=<function asunicode at 0x7fe428d93b90>, localized=True)

  Given a sequence of items, concatenate them in a nice way.

  Parameters: | elts – a sequence of elements stringify – the stringification function applied to all elements, by default coerced to unicode localized – a boolean flag to disable the translation of the final ‘and’
  Return type: | unicode

  If elts is empty returns an empty unicode string; if it contains a single element, returns the stringified element; otherwise returns a unicode string composed by all but the last elements stringified and joined by a comma, followed by the localized version of and followed by the last element stringified:

      >>> print(njoin([1,2,3]))
      1, 2 and 3
      >>> print(njoin([1,2]))
      1 and 2
      >>> print(njoin([1]))
      1
      >>> assert njoin([]) == ''
      >>> print(njoin([1,2], stringify=lambda x: str(x*10)))
      10 and 20

`sol.models.utils.` `entity_from_primary_key`(pkname)

  Given the name of a primary key, return the mapped entity.

  Parameters: | pkname – the name of a primary key
  Return type: | a mapped class

`sol.models.utils.` `table_from_primary_key`(pkname)

  Given the name of a primary key, return the related table.

  Parameters: | pkname – the name of a primary key
  Return type: | a SQLAlchemy table

### Navigation

- index
- modules |
- next |
- previous |
- Dev's documentation »
- SoL modules »