Core modules

ex – exception definitions

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

exception summer.ex.ApplicationException(message: str=None, **kwargs)[source]

Bases: Exception

Base class for exceptions. Suited for custom subclassing.

__init__(message: str=None, **kwargs)[source]

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.
__weakref__

list of weak references to the object (if defined)

exception summer.ex.SummerException(message: str=None, **kwargs)[source]

Bases: summer.ex.ApplicationException

Base summer framework exception.

exception summer.ex.SummerConfigurationException(message: str=None, **kwargs)[source]

Bases: summer.ex.SummerException

Raised when summer configuration is broken.

exception summer.ex.NoObjectFoundException(message: str=None, **kwargs)[source]

Bases: summer.ex.SummerException

Raised when required object is not found in context.

summer.ex.exception_to_str()[source]

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

Returns:the formatted unicode string containing the last exception info.
Return type:str

aop – aspect oriented programming

Provides basic AOP functionality.

AbstractMethodAdvice provides base class for advices (before, after, around advice). Subclass AroundMethodAdvice to implement around advice by overriding AroundMethodAdvice.__call__() to provide desired behaviour before and/or after the call.

Intended implementation of AOP is through method decorators. Support for such an implementation is provided in Proxy, ie. proxy class can intercept calls and can implement special actions before/after/around a call while accessing target object’s methods (or attributes).

See summer.txaop and summer.lxaop modules for implementation of transactional and ldap session proxy with accompanying advice and decorator.

class summer.aop.AbstractMethodAdvice(method: method)[source]

Bases: summer.utils.Printable

Base class for method advice.

If one wants to use the advice (ie. apply an aspect), the trick is to use the proxy class, that adds another layer of indirection.

Proxy delegates access to all the attributes to the target object. If the attribute is not decorated, proxy will accesses the attribute directly, if not, proxy will invoke and advice before and/or after accessing the attribute (usually method call).

Current implementation supports the creation of an advice in the proxy object by searching for a decoration – if the attribute (method) is decorated by particular decorator, new attribute with the same name is created on the proxy instance (of the type :py:class`AbstractMethodAdvice`) and it gets called instead, doing anything the aspect requires (doing some stuff and than delegating the call to target object).

__init__(method: method)[source]
Parameters:method (types.MethodType) – method to be adviced
before(*args, **kwargs) → object[source]

Called before actual method invocation takes place.

Any arguments provided are forwarded to proxy.

Returns:whatever the target returns.
Return type:object
after(*args, **kwargs) → object[source]

Called after actual method invocation takes place.

Any arguments provided are forwarded to proxy.

Returns:whatever the target returns.
Return type:object
around(*args, **kwargs) → object[source]

Called around actual method invocation. Probably most usefull kind of advice; sure the most powerful.

Any arguments provided are forwarded to proxy.

Returns:whatever the target returns.
Return type:object
__call__(*args, **kwargs) → object[source]

This should delegate the call to before(), after() or around() method. Implemented in subclasses.

Any arguments provided are forwarded to proxy.

Returns:whatever the target returns.
Return type:object
class summer.aop.AroundMethodAdvice(method: method)[source]

Bases: summer.aop.AbstractMethodAdvice

Around method advice.

__call__(*args, **kwargs) → object[source]

Delegates method call to AbstractMethodAdvice.around() method.

Any arguments provided are forwarded to proxy.

Returns:whatever the target returns.
Return type:object
class summer.aop.Proxy(target: object)[source]

Bases: object

Generic proxy object proxies the target’s method calls by applying an advice – and so implementing an aspect.

__init__(target: object)[source]
Parameters:target (object) – object to be peroxied.
__getattr__(name: str) → object[source]

Delegates the attribute access to itself and than to target object if not found.

Proxied (adviced) attributes (AbstractMethodAdvice instances) has the same name as their decorated counterparts in the target object. In such a case, they gets called instead of the target object methods.

Parameters:name (str) – attribute name to return.
Returns:Any value store in attribute.
Return type:object
_get_decorated_methods(decorator_name: str) → list[source]

Gets methods decorated by decorator_name in the self.target. Decorated methods can be proxied.

It is very handy to implement aspects using decorators – with just a method decoration one can mark that method for the proxy as a target method for applying an advice – and so implementing an aspect. This method seres as a helper to decide which methods of the target object should be adviced.

Parameters:decorator_name (str) – name of the decorator to look for.
Returns:List of method objects decorated by decorator.
Return type:list
__weakref__

list of weak references to the object (if defined)

domain – domain model

Basic support for domain classes, including persistent domain classes.

class summer.domain.Domain[source]

Bases: summer.utils.Printable

Suitable class for generic domain objects.

class summer.domain.Filter(page: int=1, max_results: int=-1)[source]

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)[source]
Parameters:
  • page (int) – page in collection
  • max_results (int) –
static get_default()[source]
Returns:default filter instance, set for single page without limit per page (will show all the results)
Return type:Filter
get_offset() → int[source]

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

Returns:offset
Return type:int
get_max_results() → int[source]

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)[source]

Copy the page and max_results to self.

Parameters:other (Filter) – filter object to be copied
class summer.domain.Entity[source]

Bases: summer.domain.Domain

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

__eq__(other)[source]

Equality is based on the id attribute.

__hash__()[source]

Hash is based on the id attribute.

class summer.domain.CodeEntity[source]

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.

class summer.domain.LdapEntity[source]

Bases: summer.domain.Domain

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

__eq__(other)[source]

Equality is based on the dn attribute.

__hash__()[source]

Hash is based on the dn attribute.

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(path_to_module: str, customcfg: str=None, summercfg: str='summer.cfg')[source]

Bases: object

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

It is responsible for:

  1. summer framework initialization (reading config files)
  2. instantiating your business classes with their interdependencies
  3. proxy creation

It uses convention over configuration approach, so it supposes specific config file names etc, though much of it may be overwritten.

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.

__init__(path_to_module: str, customcfg: str=None, summercfg: str='summer.cfg')[source]

Context initialization is separated into several steps:

  1. call core_init() (not indended to be overriden) which parses config files and creates core objects managing key resources (sql database, ldap server, localization)
  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
Parameters:
  • path_to_module (str) – path to module, usually pass __file__ built-in. It will look for config files up to several directories levels up.
  • customcfg (str) – name of custom config file
  • summercfg (str) – name of summer config file
__del__()[source]

Calls context_shutdown() to properly shutdown the context.

core_init()[source]

Initializes core objects based on summer_config.

_create_session_factory()[source]

Can be overriden by subclasses (if ORM is in use). Creates session factory.

Returns:summer.sf.SessionFactory instance.
Return type:SessionFactory
_create_ldap_session_factory()[source]

Can be overriden by subclasses (if LDAP is in use). Creates ldap session factory.

Returns:summer.lsf.LdapSessionFactory instance.
Return type:LdapSessionFactory
_create_l10n()[source]

Can be overriden by subclasses (if localization is in use). Creates l10n.

Returns:summer.l10n.Localization instance.
Return type:Localization
orm_init()[source]

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.set_table_definitions(TableDefinitions())
self.session_factory.set_class_mappings(ClassMappings())
context_init()[source]

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 attributes:

  • summer_config – Python’s configparser.SafeConfigParser instance of the summer framework itself
  • config – Python’s configparser.SafeConfigParser of your custom config (if provided)
  • l10nsummer.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 provided in summer framework config (summer_config attribute)
  • session_factorysummer.sf.SessionFactory instance, which provides thread-safe access to sqlalchemy.session – any data aware object (ie. each DAO at least) should have access to it. By convention, name all the references to this object as session_factory. AOP depends on this. You can override it, but why would you do it? Remember: convention over configuration.
  • 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, again, convention dictates to name reference to this object as ldap_session_factory. AOP depends on this.
context_shutdown()[source]

Handles context shutdown. Called from __del__().

__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)[source]

Bases: object

Provides localization (l10n) services. If properly configured in summer configuration file, it loads all the defined languages and installs gettext._() function into global namespace.

__init__(domain: str, l10n_dir: str, languages: list)[source]

Creates Localization instance.

Parameters:
  • domain – gettext domain
  • l10n_dir – directory path for gettext compiled data
  • languages – list of supported languages
__weakref__

list of weak references to the object (if defined)