README — summer 0.7.4 documentation

# README

                         _____________________________

                                   README.TXT

                          martinslouf@sourceforge.net
                         _____________________________

    Table of Contents
    _________________

    1 Description
    2 Installation
    .. 2.1 Installing from PyPI (Python Package Index)
    .. 2.2 Installing from source distribution
    .. 2.3 Setting up a development/runtime environment on Debian GNU/Linux
    3 Files and Directories
    4 Documentation
    .. 4.1 Examples
    .. 4.2 Test suite
    5 Release notes
    .. 5.1 0.7.2
    .. 5.2 0.7.1
    .. 5.3 0.7.0
    .. 5.4 0.6.2
    .. 5.5 0.6.1
    .. 5.6 0.6.0
    .. 5.7 0.5.2
    .. 5.8 0.5.1
    .. 5.9 0.5.0
    .. 5.10 0.4.0
    .. 5.11 0.3.0
    .. 5.12 0.2.2
    .. 5.13 0.2.1
    .. 5.14 0.2.0
    .. 5.15 0.1.1
    .. 5.16 0.1.0
    6 TODO Todo list [1/6]

    1 Description
    =============

      Summer is light weight Python 3 application framework to support
      generic application development.  It provides support for business
      object management, ORM (mapping, declarative transactions), LDAP and
      localization.  Inspired by famous Java Spring application framework.

      Since 0.5.2 Python 3 is required.

      Project web page: [http://py-summer.sourceforge.net/].

    2 Installation
    ==============

    2.1 Installing from PyPI (Python Package Index)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      ,----
      | pip install summer
      `----

    2.2 Installing from source distribution
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      Installation uses Python /setuptools/ -- just run from distribution
      top dir:

      ,----
      | python setup.py install
      `----

      or you may prefer

      ,----
      | python setup.py install --prefix=/usr/local/
      `----

      This will copy the package into appropriate directory for third-party
      modules of your Python installation.

    2.3 Setting up a development/runtime environment on Debian GNU/Linux
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      ,----
      | # install base python packages from your distribution repo
      | apt-get install gettext sqlite3 git build-essential python3 python3-dev python3-venv
      | # install those dependencies in order to compile required native
      | # Python packages for your platform
      | apt-get install libpq-dev
      |
      | # crate virtual environment with Python 3 interpreter
      | target=~/.virtualenvs/p3-summer
      | python3 -m venv $target
      | cd $target
      | source bin/activate
      |
      | # clone the mcc repo to the directory of your choice
      | git clone git://git.code.sf.net/p/py-summer/code summer
      | cd summer
      |
      | # install mcc requirements (see setup.py)
      | pip install -e .
      |
      | # install additional packages to ease development (if required)
      | pip install wheel
      | pip install -r requirements-dev.txt
      |
      | # run tests
      | make clean tests
      `----

    3 Files and Directories
    =======================

      ,----
      | # tree --charset ascii --dirsfirst -L 1 -F
      | .
      | |-- doc/               ... documentation (including release notes and examples)
      | |-- summer/            ... source code
      | |-- summer.egg-info/   ... PyPI info
      | |-- COPYING            ... GPL copy
      | |-- COPYING.LESSER     ... LGPL copy
      | |-- README.txt         ... this README document
      | `-- setup.py           ... Python distutils file
      `----

    4 Documentation
    ===============

      Reference documentation can be generated by /sphinx/ tool from source
      tree and placed in [file:doc/html/index.html].  It is also accessible
      through project web page: [http://py-summer.sourceforge.net/].

    4.1 Examples
    ~~~~~~~~~~~~

      Pack of commented examples is in [file:summer/tests/examples]
      directory.  Accessible once you download the source.

    4.2 Test suite
    ~~~~~~~~~~~~~~

      Once you checked out the sources, you can run tests from within the
      top directory:

      ,----
      | git clone git://git.code.sf.net/p/py-summer/code summer
      | cd summer
      | make clean tests
      `----

      Commands above will clone official Git repository and execute popular
      Python test runner `nosetests'.

    5 Release notes
    ===============

    5.1 0.7.2
    ~~~~~~~~~

      - producer/consumer refactor (producer/consumer/mediator)
      - update copyright info
      - fix rollback for nested @transactional decorators (original
        exception is not consumed anymore)

    5.2 0.7.1
    ~~~~~~~~~

      - upgrade dependencies (ldap3)
      - specify minimum requirements in setup.py
      - tested on Python 3.5+
      - update Copyright information

    5.3 0.7.0
    ~~~~~~~~~

      - change summer configuration from text to Python config
      - AOP implemntation redesign
      - extensive use of @property annotation
      - support for single SessionFactory and LdapSessionFactory (force
        singleton)

    5.4 0.6.2
    ~~~~~~~~~

      - support for direct access of database connection
      - virtual attributes can be accessed via getters (improves integration
        with IDE that can leverage Python 3 type declarations)
      - some doc fixes

    5.5 0.6.1
    ~~~~~~~~~

      - fix package homepage url ([https://py-summer.sourceforge.net/] ->
        [http://py-summer.sourceforge.net/])

    5.6 0.6.0
    ~~~~~~~~~

      - Python 3 type annotations added
      - setup.py changes according to
        [https://packaging.python.org/en/latest/distributing.html]
      - Minor change in orm initialization (Context.orm_init() method)
      - Generic Producer/Consumer framework
      - New target (doc) to generate nice html documentation from source.
      - Registered on PyPI

    5.7 0.5.2
    ~~~~~~~~~

      - migration to Python 3
      - sources restructured to follow best practices of project layout
      - source code formatting according to PEP 8
      - broken compatibility in ldap removed base attribute in LDAP DAO
        session object (ie. self.session.base no longer works) added virtual
        attribute to LDAP DAO self.base instead of self.session.base

    5.8 0.5.1
    ~~~~~~~~~

      - Documentation update
      - SourceForge.net release automation

    5.9 0.5.0
    ~~~~~~~~~

      - migration from subversion to git, thanks to great
        [http://danielpocock.com/migrating-a-sourceforge-project-from-subversion-to-git]
      - several bug fixes
      - improved logging

    5.10 0.4.0
    ~~~~~~~~~~

      - Source documentation revisited.
      - New unit tests added.
      - Support for paging results using Filter domain object.
      - (Ldap)Dao refactoring (new dao base class to support Dao without an
        entity).
      - New utility class Printable for object pretty printing.

    5.11 0.3.0
    ~~~~~~~~~~

      - some minor fixes (DaoSupport.query attribute, export of
        DaoException, ...)
      - compatibility issues with SQLAlchemy 0.5, this is now the required
        version
      - testing with real-world projects => first Beta release!

      - known problems -- AOP -- calling proxied method (ie. decorated) from
        a non-proxy 'self' object (ie. calling private proxy method from
        non-proxied public method of the same object) does not invoke an
        advice

        workaround -- mark all your public methods with an annotation, do
        not rely on annotating private methods

        fix -- though possible, ugly; i will try to think up something
        better

      - added assert module for various tests/checks -- ass.py
      - utility method for exception stacktrace pretty printing -- even from
        aop code

    5.12 0.2.2
    ~~~~~~~~~~

      - fix with DaoSupport.query attribute

    5.13 0.2.1
    ~~~~~~~~~~

      - packaging bug fix regarding example 02_template_project
      - dao support extended with more utility methods

    5.14 0.2.0
    ~~~~~~~~~~

      - LDAP support added based on simillar concepts as SQL support
        (@ldapaop decorator, LDAP proxies)
      - comprehensive example 02_template_project created

    5.15 0.1.1
    ~~~~~~~~~~

      Just a minor release.  Added admin functionality to automate the
      sourceforge release process + all the files where it makes sense now
      include subversion 'Id' keyword.

    5.16 0.1.0
    ~~~~~~~~~~

      This is initial release.  Contains no overall documentation, but one
      commented example showing creation of application context, declarative
      transactions and presents some basic hints and ideas.

      It is a standard Python source distribution, so just unpack and
      install with:

      python setup.py install

    6 TODO Todo list [1/6]
    ======================

      - [X] for nested transaction, there is double rollback -- and
        transaction is internally marked as not active, which causes the
        real exception to be hidden behind assert

      - [ ] intelligent context -- context that would inspect an object
        (@component annotation), auto-create proxy and auto-inject
        dependency (@inject annotation)
      - [ ] livecycle callbacks

      ,----
      | ContextListener:
      |     def context_initialized(context): pass
      |     def context_destroyed(context): pass
      |
      | ComponentListener:
      |     def component_deployed(context): pass
      |     def component_undeployed(context): pass
      `----

      - [ ] improve PCG -- it accepts an iterable and starts multiple
        threads to process it.  It can return an iterable (preserving
        the element order) of the results
      - [ ] reimplement PC (and PCG) with multiprocessing support to
        side-step the GIL
      - [ ] maybe use Python queue type instead of custom shared buffer?