_____________________________
README.TXT
martinslouf@sourceforge.net
_____________________________
Table of Contents
_________________
1. Description
2. Git Structure
3. Installation
.. 1. Installing from PyPI (Python Package Index)
.. 2. Installing from source distribution
.. 3. Setting up a development/runtime environment on Debian GNU/Linux
4. Files and Directories
5. Documentation
.. 1. Examples
.. 2. Test suite
6. Release notes
.. 1. 0.7.8.1
.. 2. 0.7.8
.. 3. 0.7.7
.. 4. 0.7.6.2
.. 5. 0.7.6.1
.. 6. 0.7.6
.. 7. 0.7.5.1
.. 8. 0.7.5
.. 9. 0.7.4.4.1
.. 10. 0.7.4.4
.. 11. 0.7.4.3
.. 12. 0.7.4.2
.. 13. 0.7.4.1
.. 14. 0.7.4
.. 15. 0.7.3
.. 16. 0.7.2
.. 17. 0.7.1
.. 18. 0.7.0
.. 19. 0.6.2
.. 20. 0.6.1
.. 21. 0.6.0
.. 22. 0.5.2
.. 23. 0.5.1
.. 24. 0.5.0
.. 25. 0.4.0
.. 26. 0.3.0
.. 27. 0.2.2
.. 28. 0.2.1
.. 29. 0.2.0
.. 30. 0.1.1
.. 31. 0.1.0
7. TODO Todo list [2/11]
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. Tested for latest Python 3.7 and
Python 3.9.
Project web page <https://gitlab.com/martin.slouf/py-summer>.
Old project web page: <http://py-summer.sourceforge.net/>.
2 Git Structure
===============
Project follows this Git branching model:
<https://nvie.com/posts/a-successful-git-branching-model/>.
STARnet branches: <./README-git.png>
<file:README-git.png>
3 Installation
==============
3.1 Installing from PyPI (Python Package Index)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
,----
| pip install summer
| pip install summer[sqlalchemy] # with SQLAlchemy support
| pip install summer[sqlalchemy,ldap] # with SQLAlchemy & LDAP support
`----
3.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.
3.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
|
| # clone the summer repo to the directory of your choice
| git clone git@gitlab.com:martin.slouf/py-summer.git summer
| cd summer
|
| # create virtual environment with Python 3 interpreter and wheel
| python3 -m venv .venv && . .venv/bin/activate && pip install wheel
|
| # install dev requirements (see setup.py)
| pip install -r requirements-dev.txt
|
| # run tests
| make clean test
`----
4 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
`----
5 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/>.
5.1 Examples
~~~~~~~~~~~~
Pack of commented examples is in <file:summer/tests/examples>
directory. Accessible once you download the source.
5.2 Test suite
~~~~~~~~~~~~~~
Once you checked out the sources, you can run tests from within the
top directory:
,----
| git clone git@gitlab.com:martin.slouf/py-summer.git summer
| cd summer
| make clean test
`----
Commands above will clone official Git repository and execute popular
Python test runner `nosetests'.
6 Release notes
===============
6.1 0.7.8.1
~~~~~~~~~~~
- fix summer import in case no LDAP, no ORM is required and extra
libraries are missing
6.2 0.7.8
~~~~~~~~~
- remove un-necessary engine reference from `SessionFactory.Local`
6.3 0.7.7
~~~~~~~~~
- improve @session_scoped implementation so it not only closes
(close()) the sqlalchemy session, but also deletes it (del) so any
resources used are released and new access will produce new object
6.4 0.7.6.2
~~~~~~~~~~~
- improve AOP implementation to allow decorator chaining (if required)
- unfortunately, still using global namespace
6.5 0.7.6.1
~~~~~~~~~~~
- fix doc build
6.6 0.7.6
~~~~~~~~~
- upgrade libs to latest minor versions (ldap + sqlalchemy)
- review development dependencies (requirements-dev.txt)
- follow source code layout guidelines at <https://www.pypa.io/>,
discussed <https://blog.ionelmc.ro/2014/05/25/python-packaging/>
- improve resource management
6.7 0.7.5.1
~~~~~~~~~~~
- slightly change behaviour of `Dao.get` method
6.8 0.7.5
~~~~~~~~~
- support for pytest framework
- migration to GitLab.com from SourceForge.net (still on SourceForge,
but start using GitLab GIT as primary repo)
- ldap3 and sqlalchemy made optional deps (though using sqlalchemy
unlocks most usefull features)
6.9 0.7.4.4.1
~~~~~~~~~~~~~
- hotfix for exception in __str__() method
6.10 0.7.4.4
~~~~~~~~~~~~
- improve exception __str__ method
6.11 0.7.4.3
~~~~~~~~~~~~
- Entity dao now supports domain classes derived from summer Entity
and/or sqlalchemy declarative base
6.12 0.7.4.2
~~~~~~~~~~~~
- add generic engine_kwargs to session provider that are passed to
engine when created, one can manage pool size more easily for
example
- removed default settings to engine 'pool_recycle=3600' -- use
generic engine_kwargs to tune engine settings
6.13 0.7.4.1
~~~~~~~~~~~~
- fix access to local bound connection -- use the connection of the
underlying session, not a new connection from engine
6.14 0.7.4
~~~~~~~~~~
- support for mixing declarative and classical SQLAlchemy mapping
- fix LDAP tests
6.15 0.7.3
~~~~~~~~~~
- fix requirements specification
6.16 0.7.2
~~~~~~~~~~
- producer/consumer refactor (producer/consumer/mediator)
- update copyright info
- fix rollback for nested @transactional decorators (original
exception is not consumed anymore)
6.17 0.7.1
~~~~~~~~~~
- upgrade dependencies (ldap3)
- specify minimum requirements in setup.py
- tested on Python 3.5+
- update Copyright information
6.18 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)
6.19 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
6.20 0.6.1
~~~~~~~~~~
- fix package homepage url (<https://py-summer.sourceforge.net/> ->
<http://py-summer.sourceforge.net/>)
6.21 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
6.22 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
6.23 0.5.1
~~~~~~~~~~
- Documentation update
- SourceForge.net release automation
6.24 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
6.25 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.
6.26 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
6.27 0.2.2
~~~~~~~~~~
- fix with DaoSupport.query attribute
6.28 0.2.1
~~~~~~~~~~
- packaging bug fix regarding example 02_template_project
- dao support extended with more utility methods
6.29 0.2.0
~~~~~~~~~~
- LDAP support added based on simillar concepts as SQL support
(@ldapaop decorator, LDAP proxies)
- comprehensive example 02_template_project created
6.30 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.
6.31 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
7 TODO Todo list [2/11]
=======================
- [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
- [X] review LDAP tests
- [ ] use twine to upload to PyPI
- [ ] migrate from sourceforge.net to gitlab.com
- git migrated
- [ ] follow guidelines:
- <https://docs.pytest.org/en/latest/goodpractices.html#test-discovery>
- <https://blog.ionelmc.ro/2014/05/25/python-packaging/>
- [ ] intelligent context -- context that would inspect an object
(@component annotation), auto-create proxy and auto-inject
dependency (@inject annotation)
- [ ] lifecycle 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?
- [ ] consider: discard sqlalchemy session on rollback?