Core modules — summer 0.7.4 documentation

# Core modules

## ex – exception definitions

Exception classes used in summer framework. Some are suitable for inheritance.

exception `summer.ex.` `ApplicationException`(message: str = None, **kwargs)

  Bases: `Exception`

  Base class for exceptions. Suited for custom subclassing.

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

  `__str__`()

    Return str(self).

  `__weakref__`

    list of weak references to the object (if defined)

exception `summer.ex.` `AbstractMethodException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `UnsupportedMethodException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `NotImplementedException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `UnknownAttributeException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `IllegalArgumentException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `ResourceNotFoundException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `SummerException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  Base summer framework exception.

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `SummerConfigurationException`(message: str = None, **kwargs)

  Bases: `summer.ex.SummerException`

  Raised when summer configuration is broken.

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

exception `summer.ex.` `NoObjectFoundException`(message: str = None, **kwargs)

  Bases: `summer.ex.SummerException`

  Raised when required object is not found in context.

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

`summer.ex.` `exception_to_str`()

  Convert exception to stack trace. Uses thread safe `sys.exc_info()`.

  Returns

    the formatted unicode string containing the last exception

      info.

  Return type

    str

## domain – domain model

Basic support for domain classes, including persistent domain classes.

class `summer.domain.` `Domain`

  Bases: `summer.utils.Printable`

  Suitable class for generic domain objects.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

class `summer.domain.` `Filter`(page: int = 1, max_results: int = -1)

  Bases: `summer.domain.Domain`

  Base class for filters – ie. classes that support paging through a collection. Used for example in `summer.dao.EntityDao.find()`

  - `page` sets the page of the result set, starting at 1 (ie. first page)

  - `max_results` sets the page limit (entities per page)

  Use `Filter.get_offset()` to obtain the first record of the result set. Use `Filter.get_max_results()` to obtain the last record of the result set.

  `__init__`(page: int = 1, max_results: int = -1)
    Parameters

      - page (int) – page in collection

      - max_results (int) –

  static `get_default`()
    Returns

      default filter instance, set for single page without limit per page (will show all the results)

    Return type

      Filter

  `get_offset`() → int

    Computes the order of the first record, ie. the offset.

    Returns

      offset

    Return type

      int

  `get_max_results`() → int

    Computes the order of the potential last record, ie. the max_results.

    Returns

      maximum number of results per page

    Return type

      int

  `copy_limits`(other)

    Copy the `page` and `max_results` to `self`.

    Parameters

      other (Filter) – filter object to be copied

class `summer.domain.` `Entity`

  Bases: `summer.domain.Domain`

  Suitable base class for SqlAlchemy persistent classes; defines the integer `id` attribute.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `__eq__`(other)

    Equality is based on the `id` attribute.

  `__hash__`()

    Hash is based on the `id` attribute.

  `__str__`()

    Return printable object string representation in unicode.

class `summer.domain.` `CodeEntity`

  Bases: `summer.domain.Entity`

  Suitable base class for SqlAlchemy persistent classes that have a unique string code attribute (ie. usually catalogs). This `code` attribute should be considered as a string representation of an object, its natural id, not necessarily human friendly value.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `__str__`()

    Return printable object string representation in unicode.

class `summer.domain.` `LdapEntity`

  Bases: `summer.domain.Domain`

  Suiable base class for LDAP persistent classes. Defines the unique string `dn` attribute.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `__eq__`(other)

    Equality is based on the `dn` attribute.

  `__hash__`()

    Hash is based on the `dn` attribute.

  `__str__`()

    Return printable object string representation in unicode.

## context – summer object container

Module `context` defines an application context (`Context` class)– a container for (business) objects, that should be available throughout the application, application layer or module.

class `summer.context.` `Context`(session_provider: summer.sf.SessionProvider = None, ldap_connection_provider: summer.lsf.LdapConnectionProvider = None, localization: summer.l10n.Localization = None)

  Bases: `object`

  Context is intelligent container for your business objects, it is a core of summer framework.

  It is responsible for:

  1. summer framework initialization

  2. instantiating your business classes with their interdependencies

  3. aop configuration

  Emulates mapping type, so you can access business objects by their name if required.

  Usually in medium sized applications, you define single global context somewhere in main entry point of your program. Preferred approach is to define top level module attribute, see accompanying examples.

  Initialization of context is thread safe.

  `__init__`(session_provider: summer.sf.SessionProvider = None, ldap_connection_provider: summer.lsf.LdapConnectionProvider = None, localization: summer.l10n.Localization = None)

    Creates and initializes context instance. See `init()` for more information.

    Parameters

      - session_provider (sf.SessionProvider) – object that provides SQLAlchemy sessions when requested

      - ldap_connection_provider (lsf.LdapConnectionProvider) – object that provides LDAP connections when requested

      - localization (l10n.Localization) – localization object

  `__del__`()

    Calls `shutdown()` to properly shutdown the context.

  property `session_factory`

    Each context may have up to one instance of session factory – access to your database connections.

    Returns

      session factory instance.

    Return type

      sf.SessionFactory

  property `ldap_session_factory`

    Each context may have up to one instance of LDAP session factory – access to your LDAP connections.

    Returns

      LDAP session factory instance.

    Return type

      lsf.LdapSessionFactory

  property `l10n`

    Each context may have up to one instance of `l10n.Localization`. You usually do not need to access it.

    Returns

      localization instance.

    Return type

      l10n.Localization

  `init`()

    Main context initialization method.

    Context initialization is executed from constructor; it is separated into several steps:

    1. call `core_init()` (not indended to be overriden) which initializes core objects and internal AOP features

    2. call `orm_init()` (intended to be overriden) which initializes ORM

    3. call `context_init()` (intended to be overriden) – a place to define your business beans

  `core_init`()

    Initializes core objects.

  `orm_init`()

    Should be overriden by subclasses to initialize ORM managed tables and class mappings.

    You should define your custom table definitions based on `summer.sf.AbstractTableDefinitions` and mappings based on `summer.sf.AbstractClassMappings`.

    Usually you have just those lines there:

        self.session_factory.table_definitions = MyTableDefinitions()
        self.session_factory.set_class_mappings = MyClassMappings()

  `context_init`()

    Should be overriden by subclasses to initialize custom objects in context.

    This is the last stage of context initialization, this method gets called after

    1. `core_init()`

    2. `orm_init()`

    are called. You can safely access those properties:

    - `session_factory` (`summer.sf.SessionFactory` instance) which provides thread-safe access to `sqlalchemy.session` – any data aware object (ie. each DAO at least) should probably have access to it – at least those derived from `dao.Dao` reference it.

    - `ldap_session_factory` (`summer.lsf.LdapSessionFactory` instance) which provides thread-safe access to `summer.lsf.LdapSessionFactory.Local` instance – a simple wrapper around actual `ldap3.Connection`

    - `l10n` (`summer.l10n.Localization`) instance, not very interesting in itself, but summer’s localization module installs the famous `_()` gettext function into global namespace (as normal gettext module does) and configures your localization based on whatever you have provided

  `shutdown`()

    Handles context shutdown. Called from `__del__()`. Can be overriden.

  `__weakref__`

    list of weak references to the object (if defined)

## l10n – localization

Based on Python’s `gettext` module.

class `summer.l10n.` `Localization`(domain: str, l10n_dir: str, languages: list)

  Bases: `object`

  Provides localization (l10n) services.

  If instance is provided to `summer.context.Context`, context will load all the defined languages and will install `gettext._()` function into global namespace.

  `__init__`(domain: str, l10n_dir: str, languages: list)

    Creates `Localization` instance.

    Parameters

      - domain – gettext domain

      - l10n_dir – directory path for gettext compiled data

      - languages – list of supported languages

  `init`()

    Installs defined languages.

  `__weakref__`

    list of weak references to the object (if defined)