application environment for python

welcome to the ae namespace documentation.

the portions (modules and sub-packages) of this freely extendable namespace (PEP 420) are providing helper functions and classes for your python application, resulting in less code for you to write and maintain, in the areas/domains:

* data processing/validation
* file handling
* i18n (localization)
* configuration settings
* console
* logging
* database access
* networking
* multi-platform/-OS
* context help
* app tours
* user preferences (font size, color, theming, ...)
* QR codes
* sideloading

screenshots of apps developed with ae portions


Fig. 1 GlslTest app demo

root list of a dark themed kivy lisz app

Fig. 2 kivy lisz app root list

fruits sub-list of a dark themed kivy lisz app

Fig. 3 fruits sub-list

fruits sub-list of a light themed kivy lisz app

Fig. 4 using light theme

user preferences drop down

Fig. 5 lisz user preferences

kivy lisz color editor

Fig. 6 kivy lisz color editor

lisz app using bigger font size

Fig. 7 bigger font size

fruits sub-list of dark themed enaml lisz app

Fig. 8 enaml/qt lisz app

fruits sub-list of a light themed enaml lisz app in landscape

Fig. 9 light themed in landscape

code maintenance guidelines

portions code requirements

  • pure python

  • fully typed (PEP 526)

  • fully documented

  • 100 % test coverage

  • multi thread save

  • code checks (using pylint and flake8)

design pattern and software principles


we want to make it as easy and fun as possible for you to contribute to this namespace.

reporting bugs

before you create a new issue, please check to see if you are using the latest portion version; the bug may already be resolved.

also search for similar problems in the issue tracker; it may already be an identified problem.

include as much information as possible into the issue description, at least:

  1. version numbers of Python, the namespace portion and any involved packages

  2. small self-contained code example that reproduces the bug

  3. steps to reproduce the error

  4. any traceback/error/log messages shown

requesting new features

  1. provide a clear and detailed explanation of the feature you want and why it’s important to add.

  2. if you are able to implement the feature yourself (refer to the contribution steps section below).

contribution steps

  1. make sure you have a GitLab account to be able to fork this repository.

  2. clone your forked repo as origin remote to your computer, and add an upstream remote for the destination repo:

    git clone<YourGitLabUserName>/<ThisRepositoryName>.git
    git remote add upstream<ThisRepositoryName>.git
  3. checkout out a new local feature branch and update it to the latest version of the develop branch:

    git checkout -b feature-xxx develop
    git pull --rebase upstream develop
    please keep your code clean by staying current with the
    ``develop`` branch, where code will be merged. if you find
    another bug, please fix it in a separated branch instead.
  4. push the branch to your fork. treat it as a backup:

    git push origin feature-xxx
  5. code

    implement the new feature or the bug fix; include tests, and ensure they pass.

  6. commit

    for every commit please write a short (max 72 characters) summary in the first line followed with a blank line and then more detailed descriptions of the change. use Markdown syntax for simple styling. please include any issue number (in the format #nnn) in your summary:

    git commit -m "issue #123: put change summary here (can be a issue title)"

    never leave the commit message blank! provide a detailed, clear, and complete description of your commit!

  7. prepare a Merge Request

    before submitting a merge request, update your branch to the latest code:

    git pull --rebase upstream develop

    if you have made many commits, we ask you to squash them into atomic units of work. most issues should have one commit only, especially bug fixes, which makes them easier to back port:

    git checkout develop
    git pull --rebase upstream develop
    git checkout feature-xxx
    git rebase -i develop

    push changes to your fork:

    git push -f
  8. issue/make a GitLab Merge Request:

    • navigate to your fork where you just pushed to

    • click Merge Request

    • in the branch field write your feature branch name (this is filled with your default branch name)

    • click Update Commit Range

    • ensure the changes you implemented are included in the Commits tab

    • ensure that the Files Changed tab incorporate all of your changes

    • fill in some details about your potential patch including a meaningful title

    • click New merge request.


the steps 4 to 7 may be repeated, and could alternatively be automated with the helper script of the namespace root package. this script also allows to manage feature branches which are including changes on multiple portions of this namespace.

thanks for your contribution – we’ll get your merge request reviewed. you should also review other merge requests, just like other developers will review yours and comment on them. based on the comments, you should address them. once the reviewers approve, the maintainers will merge the code.

add new namespace portion

follow the steps underneath to add a new portion to the ae namespace. the steps 7 to 9 can be realized by the script, which can also be used or adopted to migrate an existing packages from other projects into this namespace:

  1. choose a not-existing/unique name for the new portion (referred as <portion-name> in the next steps).

  2. create a new project folder ae_<portion-name> in the source code directory of your local machine.

  3. in the new project folder create/prepare a local virtual environment with pyenv.

  4. create new test module in the tests folder within the new code project folder and then code your unit tests.

  5. create the ae namespace sub-folder within the new code project folder.

  6. within the ae folder create new module or sub-package, implement the new portion and set the __version__ variable to ‘0.0.1’.

  7. copy all files from the folder portions_common_root of this package into the new code project folder.

  8. init a new git repository on your local machine and add all files.

  9. create new project/repository with the name ae_<portion-name> (in the GitLab group ae-group

  10. hack/test/fix/commit until all tests succeed.

  11. complete type annotations and the docstrings to properly document the new portion.

  12. finally push the new namespace portion repository onto<portion-name>.


if you want to put the portion separately into your own repository (see step 11 above) then you also have to add two protected vars PYPI_USERNAME and PYPI_PASSWORD (mark also as masked) and provide the user name and password of your PYPI account (on at Settings/CI_CD/Variables).


with the push to GitLab (done in step 12 above) the CI jobs will automatically run all tests and then publish the new portion onto PYPI.

to request the registration of the new portion to one of the ae namespace maintainers - this way the new portion will be included into the ae namespace package documentation on ReadTheDocs.

change common files of all portions

any change on one of the common files (situated in the portions_common_root folder of this repository) and to the common base files of this namespace have to be done from/via this namespace root package.

use the script to distribute changes of your local portions or of the common portion files.


all changes to the common files of this root package have first to be pushed to the public git repository before they can be distributed to the namespace portion packages.

registered namespace package portions

the following list contains all registered portions of the ae namespace. most portions are single module files, some of them are sub-packages.


portions with no dependencies are at the begin of the following list. the portions that are depending on other portions of the ae namespace are listed more to the end.


basic constants and helper functions


deep data structure search and replace


android constants and helper functions


data validation helper functions


generic file object helpers


generic file path helpers


application core constants, helper functions and base classes


named threading locks


inspection and debugging helper functions


internationalization / localization helpers


parse date strings more flexible and less strict


literal type detection and evaluation


display progress of long running processes


application environment updater


console application environment


dynamic system configuration, initialization and connection


external system data structures


SiHOT PMS system core xml interface


Sihot system data interface


database connection and data manipulation base classes


database system core layer to access Oracle databases


postgres database layer


transfer client and server services


sideloading server


base class for python applications with a graphical user interface


main app base class with context help for flow and app state changes


Lisz Demo App


add glsl shaders to your kivy widget


automatic width mix-in classes for kivy widgets


dynamic children mix-in for kivy container widgets


inner/outer elliptic/square reliefs for any kivy widget


enhance your app with context help, user onboarding, product tours, walkthroughs and tutorials


main application classes and widgets for GUIApp-conform Kivy apps


user preferences widgets for your kivy app


extended kivy file chooser widget


qr code displayer widget


iterable displayer widget


kivy mixin and widgets to integrate a sideloading server in your app


enaml application widgets, helper functions and classes


enaml application helper functions.