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.1
.. 5.2 0.7.0
.. 5.3 0.6.2
.. 5.4 0.6.1
.. 5.5 0.6.0
.. 5.6 0.5.2
.. 5.7 0.5.1
.. 5.8 0.5.0
.. 5.9 0.4.0
.. 5.10 0.3.0
.. 5.11 0.2.2
.. 5.12 0.2.1
.. 5.13 0.2.0
.. 5.14 0.1.1
.. 5.15 0.1.0
6 TODO Todo list [0/4]





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 python3-sphinx python3-sphinx-rtd-theme
  | # 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 -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.1
~~~~~~~~~

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


5.2 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.3 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.4 0.6.1
~~~~~~~~~

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


5.5 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.6 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.7 0.5.1
~~~~~~~~~

  - Documentation update
  - SourceForge.net release automation


5.8 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.9 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.10 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.11 0.2.2
~~~~~~~~~~

  - fix with DaoSupport.query attribute


5.12 0.2.1
~~~~~~~~~~

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


5.13 0.2.0
~~~~~~~~~~

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


5.14 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.15 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 [0/4]
======================

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