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.

namespace portions guidelines:
  • pure python, fully typed (PEP 526) and documented

  • 100 % test coverage

  • multi thread save

  • highly configurable logging

core helpers:
  • data processing and validation

  • file handling

  • i18n (localization)

  • configuration settings

  • console

  • logging

  • database access

  • networking

GUI helpers:
  • context help

  • app tours

  • user preferences (font size, color, theming)

  • QR code

  • sideloading

screenshots of apps developed with ae portions

root list of a dark themed kivy lisz app

Fig. 1 kivy lisz app root list

fruits sub-list of a dark themed kivy lisz app

Fig. 2 fruits sub-list

fruits sub-list of a light themed kivy lisz app

Fig. 3 using light theme

user preferences drop down

Fig. 4 lisz user preferences

kivy lisz color editor

Fig. 5 kivy lisz color editor

lisz app using bigger font size

Fig. 6 bigger font size

fruits sub-list of dark themed enaml lisz app

Fig. 7 enaml/qt lisz app

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

Fig. 8 light themed in landscape

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 register_portion.py, 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 https://gitlab.com/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 https://gitlab.com/ae-group/ae_<portion-name>.

Note

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 Gitlab.com at Settings/CI_CD/Variables).

Hint

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) has to be done here.

use the script portions_common_deploy.py to distribute any changes to all the portion repositories.

Note

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.

Hint

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.

ae.base

basic constants and helper functions

ae.deep

deep data structure search and replace

ae.droid

android constants and helper functions

ae.valid

data validation helper functions

ae.files

generic file object helpers

ae.paths

generic file path helpers

ae.core

application core constants, helper functions and base classes

ae.lockname

named threading locks

ae.inspector

inspection and debugging helper functions

ae.i18n

internationalization / localization helpers

ae.parse_date

parse date strings more flexible and less strict

ae.literal

literal type detection and evaluation

ae.progress

display progress of long running processes

ae.updater

application environment updater

ae.console

console application environment

ae.sys_core

dynamic system configuration, initialization and connection

ae.sys_data

external system data structures

ae.sys_core_sh

SiHOT PMS system core xml interface

ae.sys_data_sh

Sihot system data interface

ae.db_core

database connection and data manipulation base classes

ae.db_ora

database system core layer to access Oracle databases

ae.db_pg

postgres database layer

ae.transfer_service

transfer client and server services

ae.sideloading_server

sideloading server

ae.gui_app

base class for python applications with a graphical user interface

ae.gui_help

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

ae.lisz_app_data

Lisz Demo App

ae.kivy_glsl

add glsl shaders to your kivy widget

ae.kivy_auto_width

automatic width mix-in classes for kivy widgets

ae.kivy_dyn_chi

dynamic children mix-in for kivy container widgets

ae.kivy_relief_canvas

inner/outer elliptic/square reliefs for any kivy widget

ae.kivy_help

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

ae.kivy_app

main application classes and widgets for GUIApp-conform Kivy apps

ae.kivy_user_prefs

user preferences widgets for your kivy app

ae.kivy_file_chooser

extended kivy file chooser widget

ae.kivy_qr_displayer

qr code displayer widget

ae.kivy_iterable_displayer

iterable displayer widget

ae.kivy_sideloading

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

ae.enaml_app

enaml application widgets, helper functions and classes

ae.enaml_app.functions

enaml application helper functions.