summer Code
Summer is light weight Python 3 application framework
Status: Beta
Brought to you by:
martinslouf
Menu
▾
▴
Tree [bb4c80] master / History
Read Me
# -*- mode: org -*-
# Time-stamp: < README.org (2020-08-25 21:48) >
#+TITLE: README.txt
#+AUTHOR: martinslouf@sourceforge.net
#+OPTIONS: ^:nil
#+LANGUAGE: en
* 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/.
* Git Structure
Project follows this Git branching model:
https://nvie.com/posts/a-successful-git-branching-model/.
STARnet branches: [[./README-git.png]]
#+BEGIN_SRC dot :file README-git.png :cmdline -Tpng
# dot -Tpng <input.dot> -o <output.png>
digraph "STARnet git branches" {
master [style="filled", label="master"];
develop [style="filled", label="develop"];
feature [label="feature/*"];
hotfix [label="hotfix/*"];
master -> {develop, hotfix, feature} [color="coral"];
hotfix -> master [label="merge to (once ready)", color="gold", style="dashed"];
feature -> develop [label="merge to (once ready)", color="gold", style="dashed"]
feature -> master [label="backport", color="gold"]
develop -> master [label="release", color="gold"]
}
#+END_SRC
* Installation
** Installing from PyPI (Python Package Index)
#+BEGIN_SRC sh
pip install summer
#+END_SRC
** Installing from source distribution
Installation uses Python /setuptools/ -- just run from distribution top
dir:
#+BEGIN_SRC sh
python setup.py install
#+END_SRC
or you may prefer
#+BEGIN_SRC sh
python setup.py install --prefix=/usr/local/
#+END_SRC
This will copy the package into appropriate directory for third-party
modules of your Python installation.
** Setting up a development/runtime environment on Debian GNU/Linux
#+BEGIN_SRC sh
# 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
#+END_SRC
* Files and Directories
#+BEGIN_EXAMPLE
# 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
#+END_EXAMPLE
* 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/.
** Examples
Pack of commented examples is in [[file:summer/tests/examples]] directory.
Accessible once you download the source.
** Test suite
Once you checked out the sources, you can run tests from within the top
directory:
#+BEGIN_SRC sh
git clone git://git.code.sf.net/p/py-summer/code summer
cd summer
make clean tests
#+END_SRC
Commands above will clone official Git repository and execute popular
Python test runner ~nosetests~.
* Release notes
** 0.7.5.1
- slightly change behaviour of `Dao.get` method
** 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)
** 0.7.4.4.1
- hotfix for exception in __str__() method
** 0.7.4.4
- improve exception __str__ method
** 0.7.4.3
- Entity dao now supports domain classes derived from summer Entity and/or
sqlalchemy declarative base
** 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
** 0.7.4.1
- fix access to local bound connection -- use the connection of the
underlying session, not a new connection from engine
** 0.7.4
- support for mixing declarative and classical SQLAlchemy mapping
- fix LDAP tests
** 0.7.3
- fix requirements specification
** 0.7.2
- producer/consumer refactor (producer/consumer/mediator)
- update copyright info
- fix rollback for nested @transactional decorators (original exception is
not consumed anymore)
** 0.7.1
- upgrade dependencies (ldap3)
- specify minimum requirements in setup.py
- tested on Python 3.5+
- update Copyright information
** 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)
** 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
** 0.6.1
- fix package homepage url (https://py-summer.sourceforge.net/ -> http://py-summer.sourceforge.net/)
** 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
** 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
** 0.5.1
- Documentation update
- SourceForge.net release automation
** 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
** 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.
** 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
** 0.2.2
- fix with DaoSupport.query attribute
** 0.2.1
- packaging bug fix regarding example 02_template_project
- dao support extended with more utility methods
** 0.2.0
- LDAP support added based on simillar concepts as
SQL support (@ldapaop decorator, LDAP proxies)
- comprehensive example 02_template_project created
** 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.
** 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
* SourceForge notes :noexport:
** Git
Project follows guidelines described in
http://nvie.com/posts/a-successful-git-branching-model/.
There 2 main branches:
1. /master/ holds current stable code
2. /develop/ for current development
All the development is done in /develop/ which is (once stable) merged to
/master/ -- usually just before release.
There is also a tag for each release.
Other (feature/hotfix) branches are being made as required.
** Project Web Site
- see [[file:Makefile]] target /sf-web-upload/
- web site is published automatically during release
- for manual publishing, execute:
#+BEGIN_SRC sh
SF_USERNAME=martinslouf make sf-web-upload
#+END_SRC
- there is also PyPI documentation page (http://pythonhosted.org/summer)
that redirects to SourceForge, the page has been registered at PyPI
manually (file:doc/pypi/index.html)
** Making a new release
*** Conventions
Early releases have been named by the date -- ~YYYY.MM.DD~ -- which was
cancelled -- releases are named by the version of the software.
Software version uses Python convention of ~MAJOR.MINOR.PATCH~.
*** During the release
- decide the release name (same as software version -- so nothing to decide :-)
- check/upgrade version as it is defined in
- file:setup.py
- file:summer/__init__.py
- file:sphinx/source/conf.py (not anymore -- imported from summer)
- create release notes (new subsection in README.org)
- refresh documentation (this file =M-x org-ascii-export-to-ascii=)
- if everything seems fine:
- merge with master
- create a tag in SCM (git) for that release
- publish to ~sf.net~ and /PyPI/
- switch back to /develop/ branch
*** Automated process
There is an automated process for this -- the 'release' target of the
Makefile. Executed from current branch, it:
1. runs clean & test
2. packages the project into Python source distribution
It also performs remote actions (confirmation is required):
3. creates a tag in SCM repository
4. uploads dist archive file via rsync to SourceForge FSR
5. uploads REAMDE.txt to SourceForge FSR
6. uploads web site via rsync to SourceForge WEB
7. registers new version at PyPI
Execute ~make release~ with:
#+BEGIN_SRC sh
VERSION=0.7.4.2 SF_USERNAME=martinslouf make release
#+END_SRC
** Project shell
#+BEGIN_SRC sh
# 1st create an instance
SF_USERNAME=martinslouf ssh $SF_USERNAME,py-summer@shell.sourceforge.net create
# 2nd login
SF_USERNAME=martinslouf ssh $SF_USERNAME,py-summer@shell.sourceforge.net
#+END_SRC
* TODO Todo list [2/9]
- [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
#+BEGIN_SRC python
ContextListener:
def context_initialized(context): pass
def context_destroyed(context): pass
ComponentListener:
def component_deployed(context): pass
def component_undeployed(context): pass
#+END_SRC
- [ ] 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?
