ae.base
basic constants, helper functions and context manager
this module is pure python, has no external dependencies, and is providing base constants, common helper functions and context managers.
base constants
ISO format strings for date and datetime values are provided by the constants DATE_ISO and
DATE_TIME_ISO.
the UNSET constant is useful in cases where None is a valid data value and another special value is needed
to specify that e.g. an argument or attribute has no (valid) value or did not get specified/passed.
default values to compile file and folder names for a package or an app project are provided by the constants:
DOCS_FOLDER, TESTS_FOLDER, TEMPLATES_FOLDER, BUILD_CONFIG_FILE,
PACKAGE_INCLUDE_FILES_PREFIX, PY_EXT, PY_INIT, PY_MAIN, CFG_EXT
and INI_EXT.
the constants PACKAGE_NAME, PACKAGE_DOMAIN and PERMISSIONS are mainly used for apps running
on mobile devices. to avoid redundancies, these values get loaded from the
build config file - if it exists in the current working directory.
base helper functions
to write more compact and readable code for the most common file I/O operations, the helper functions read_file()
and write_file() are wrapping Python’s built-in open() function and its context manager.
the function duplicates() returns the duplicates of an iterable type.
norm_line_sep() is converting any combination of line separators of a string to a single new-line character.
norm_name() converts any string into a name that can be used e.g. as file name or as method/attribute name.
to normalize a file path, in order to remove ., .. placeholders, to resolve symbolic links or to make it relative or
absolute, call the function norm_path().
camel_to_snake() and snake_to_camel() providing name conversions of class and method names.
to encode unicode strings to other codecs the functions force_encoding() and to_ascii() can be used.
the round_traditional() function get provided by this module for traditional rounding of float values. the
function signature is fully compatible to Python’s round() function.
the function instantiate_config_parser() ensures that the ConfigParser instance is
correctly configured, e.g. to support case-sensitive config variable names and to use ExtendedInterpolation for
the interpolation argument.
app_name_guess() guesses the name of o running Python application from the application environment, with the help
of build_config_variable_values(), which determines config-variable-values from the build spec file of an app
project.
operating system constants and helpers
the string os_platform provides the OS where your app is running, extending Python’s sys.platform()
for mobile platforms like Android and iOS.
os_host_name(), os_local_ip() and os_user_name() are determining machine and user information from
the OS.
use env_str() to determine the value of an OS environment variable with automatic variable name conversion. other
helper functions provided by this namespace portion to determine the values of the most important system environment
variables for your application are sys_env_dict() and sys_env_text().
android-specific constants and helper functions
some helper functions of this module are provided to be used for the Android OS.
the helper function start_app_service() is starting a service in its own, separate thread.
with the function request_app_permissions() you can ensure that all your Android permissions will be
requested. the module ae.kivy.apps does this automatically on app startup. on other platforms than
Android it will have no effect to call these functions.
Note
importing this module on an Android OS, it is monkey patching the shutil module to prevent crashes.
links to other android code and service examples and documentation:
big thanks to Robert Flatt for his investigations, findings and documentations to code and build Kivy apps for the Android OS, and to Gabriel Pettier for his service osc example.
generic context manager
the context manager in_wd() allows to switch the current working directory temporarily. the following
example demonstrates a typical usage, together with a temporary path, created with the help of Pythons
TemporaryDirectory class:
with tempfile.TemporaryDirectory() as tmp_dir, in_wd(tmp_dir):
# within the context the tmp_dir is set as the current working directory
assert os.getcwd() == tmp_dir
# current working directory set back to the original path and the temporary directory got removed
call stack inspection
module_attr() dynamically determines a reference to an attribute (variable, function, class, …) in a module.
module_name(), stack_frames(), stack_var() and stack_vars() are inspecting the call stack frames
to determine e.g. variable values of the callers of a function/method.
Hint
the AppBase class uses these helper functions to determine the version and
title of an application, if these values are not specified in the instance initializer.
another useful helper function provided by this portion to inspect and debug your code is full_stack_trace().
Module Attributes
project documentation root folder name |
|
name of project folder to store unit/integration tests |
|
template folder name, used in template and namespace root projects to maintain and provide common file templates |
|
gui app build config file |
|
file/folder names prefix included into setup package_data/ae_updater |
|
python cache folder name |
|
file extension for modules and hooks |
|
init-module file name of a python package |
|
main-module file name of a python executable |
|
CFG config file extension |
|
INI config file extension |
|
ISO string format for date values (e.g. |
|
ISO string format for datetime values |
|
default encode error handling for UnicodeEncodeErrors |
|
encoding for |
|
name parts separator character, e.g. |
|
skipped modules used as default by |
|
pseudo value used for attributes/arguments if None is needed as a valid value |
|
operating system / platform string (see |
Functions
guess/try to determine the name of the currently running app (w/o assessing not yet initialized app instance). |
|
|
determine build config variable values from the |
|
convert name from CamelCase to snake_case. |
|
update the optionally nested data dict in-place with the items and sub-items from the update dict. |
|
null function accepting any arguments and returning None. |
|
determine all duplicates in the iterable specified in the |
|
determine the string value of an OS environment variable, optionally preventing invalid variable name. |
|
force/ensure the encoding of text (str or bytes) without any UnicodeDecodeError/UnicodeEncodeError. |
|
get full stack trace from an exception. |
|
search, import and execute a Python module dynamically without adding it to sys.modules. |
|
context manager to temporary switch the current working directory / cwd. |
instantiate and prepare config file parser. |
|
|
determine tuple of supported main/version file name path part tuples. |
|
determine dynamically a reference to a module or to any attribute (variable/func/class) declared in the module. |
|
determine the absolute path of the module from which this function got called. |
|
find the first module in the call stack that is not in |
|
convert any combination of line separators in the |
|
normalize name to start with a letter/alphabetic/underscore and to contain only alphanumeric/underscore chars. |
|
normalize path, replacing ../. parts or the tilde character (for home folder) and transform to relative/abs. |
|
return the current timestamp as string (to use as suffix for file and variable/attribute names). |
determine the operating system host/machine name. |
|
determine ip address of this system/machine in the local network (LAN or WLAN). |
|
determine the operating system username. |
|
|
determine the main module file path of a project package, containing the project __version__ module variable. |
|
returning content of the text/binary file specified by file_path argument as string. |
|
null function accepting any arguments and returning None. |
|
round numeric value traditional. |
|
convert name from snake_case to CamelCase. |
|
generator returning the call stack frame from the level given in |
|
determine variable value in calling stack/frames. |
|
determine all global and local variables in a calling stack/frames. |
|
null function accepting any arguments and returning None. |
returns dict with python system run-time environment values. |
|
|
compile formatted text block with system environment info. |
|
converts unicode string into ascii representation. |
|
(over)write the file specified by |
Classes
(singleton) UNSET (type) object class. |
- DOCS_FOLDER = 'docs'
project documentation root folder name
- TESTS_FOLDER = 'tests'
name of project folder to store unit/integration tests
- TEMPLATES_FOLDER = 'templates'
template folder name, used in template and namespace root projects to maintain and provide common file templates
- BUILD_CONFIG_FILE = 'buildozer.spec'
gui app build config file
- PACKAGE_INCLUDE_FILES_PREFIX = 'ae_'
file/folder names prefix included into setup package_data/ae_updater
- PY_CACHE_FOLDER = '__pycache__'
python cache folder name
- PY_EXT = '.py'
file extension for modules and hooks
- PY_INIT = '__init__.py'
init-module file name of a python package
- PY_MAIN = '__main__.py'
main-module file name of a python executable
- CFG_EXT = '.cfg'
CFG config file extension
- INI_EXT = '.ini'
INI config file extension
- DATE_ISO = '%Y-%m-%d'
ISO string format for date values (e.g. in config files/variables)
- DATE_TIME_ISO = '%Y-%m-%d %H:%M:%S.%f'
ISO string format for datetime values
- DEF_ENCODE_ERRORS = 'backslashreplace'
default encode error handling for UnicodeEncodeErrors
- DEF_ENCODING = 'ascii'
encoding for
force_encoding()that will always work independent from destination (console, file sys, …).
- NAME_PARTS_SEP = '_'
name parts separator character, e.g. for
norm_name()
- SKIPPED_MODULES = ('ae.base', 'ae.paths', 'ae.dynamicod', 'ae.core', 'ae.console', 'ae.gui_app', 'ae.gui_help', 'ae.kivy', 'ae.kivy.apps', 'ae.kivy.behaviors', 'ae.kivy.i18n', 'ae.kivy.tours', 'ae.kivy.widgets', 'ae.enaml_app', 'ae.beeware_app', 'ae.pyglet_app', 'ae.pygobject_app', 'ae.dabo_app', 'ae.qpython_app', 'ae.appjar_app', 'importlib._bootstrap', 'importlib._bootstrap_external')
skipped modules used as default by
module_name(),stack_var()andstack_vars()
- UNSET = <ae.base.UnsetType object>
pseudo value used for attributes/arguments if None is needed as a valid value
- app_name_guess()[source]
guess/try to determine the name of the currently running app (w/o assessing not yet initialized app instance).
- Return type:
- Returns:
application name/id or “unguessable” if not guessable.
- build_config_variable_values(*names_defaults, section='app')[source]
determine build config variable values from the
buildozer.specfile in the current directory.- Parameters:
- Return type:
- Returns:
tuple of build config variable values (using the passed default value if not specified in the
BUILD_CONFIG_FILEspec file or if the spec file does not exist in cwd).
- deep_dict_update(data, update)[source]
update the optionally nested data dict in-place with the items and sub-items from the update dict.
- Parameters:
Hint
the module/portion
ae.deepis providing more deep update helper functions.
- dummy_function(*_args, **_kwargs)[source]
null function accepting any arguments and returning None.
- duplicates(values)[source]
determine all duplicates in the iterable specified in the
valuesargument.inspired by Ritesh Kumars answer to https://stackoverflow.com/questions/9835762.
- env_str(name, convert_name=False)[source]
determine the string value of an OS environment variable, optionally preventing invalid variable name.
- Parameters:
- Return type:
- Returns:
string value of OS environment variable if found, else None.
- force_encoding(text, encoding='ascii', errors='backslashreplace')[source]
force/ensure the encoding of text (str or bytes) without any UnicodeDecodeError/UnicodeEncodeError.
- import_module(import_name, path=<ae.base.UnsetType object>)[source]
search, import and execute a Python module dynamically without adding it to sys.modules.
- Parameters:
- Return type:
- Returns:
a reference to the loaded module or
Noneif module could not be imported.
- main_file_paths_parts(portion_name)[source]
determine tuple of supported main/version file name path part tuples.
- module_attr(import_name, attr_name='')[source]
determine dynamically a reference to a module or to any attribute (variable/func/class) declared in the module.
- Parameters:
- Return type:
- Returns:
module instance or module attribute value or None if module not found or UNSET if module attribute doesn’t exist.
Note
a previously not imported module will not be added to sys.modules by this function.
- module_file_path(local_object=None)[source]
determine the absolute path of the module from which this function got called.
- Parameters:
local_object¶ (
Optional[Callable]) – optional local module, class, method, function, traceback, frame, or code object of the calling module (passing lambda: 0 also works). omit to use instead the __file__ module variable (which will not work if the module is frozen bypy2exeorPyInstaller).- Return type:
- Returns:
module path (inclusive module file name) or empty string if path not found/determinable.
- module_name(*skip_modules, depth=0)[source]
find the first module in the call stack that is not in
skip_modules.- Parameters:
skip_modules¶ (
str) – module names to skip (def=this ae.core module).depth¶ (
int) – the calling level from which on to search. the default value 0 refers the frame and the module of the caller of this function. pass 1 or an even higher value if you want to get the module name of a function/method in a deeper level in the call stack.
- Return type:
- Returns:
the module name of the call stack level specified by
depth.
- norm_line_sep(text)[source]
convert any combination of line separators in the
textarg to new-line characters.
- norm_name(name, allow_num_prefix=False)[source]
normalize name to start with a letter/alphabetic/underscore and to contain only alphanumeric/underscore chars.
- norm_path(path, make_absolute=True, remove_base_path='', remove_dots=True, resolve_sym_links=True)[source]
normalize path, replacing ../. parts or the tilde character (for home folder) and transform to relative/abs.
- Parameters:
make_absolute¶ (
bool) – pass False to not convert path to an absolute path.remove_base_path¶ (
str) – pass a valid base path to return a relative path, even if the argument values ofmake_absoluteorresolve_sym_linksare True.remove_dots¶ (
bool) – pass False to not replace/remove the . and .. placeholders.resolve_sym_links¶ (
bool) – pass False to not resolve symbolic links, passing True implies a True value also for themake_absoluteargument.
- Return type:
- Returns:
normalized path string: absolute if
remove_base_pathis empty and eithermake_absoluteorresolve_sym_linksis True; relative ifremove_base_pathis a base path ofpathor ifpathgot specified as relative path and neithermake_absolutenorresolve_sym_linksis True.
Hint
the
normalize()function additionally replacesPATH_PLACEHOLDERS.
- now_str(sep='')[source]
return the current timestamp as string (to use as suffix for file and variable/attribute names).
- os_host_name()[source]
determine the operating system host/machine name.
- Return type:
- Returns:
machine name string.
- os_local_ip()[source]
determine ip address of this system/machine in the local network (LAN or WLAN).
inspired by answers of SO users @dml and @fatal_error to the question: https://stackoverflow.com/questions/166506.
- Return type:
- Returns:
ip address of this machine in the local network (WLAN or LAN/ethernet) or empty string if this machine is not connected to any network.
- _os_platform()[source]
determine the operating system where this code is running (used to initialize the
os_platformvariable).- Return type:
- Returns:
operating system (extension) as string:
’android’ for all Android systems.
’cygwin’ for MS Windows with an installed Cygwin extension.
’darwin’ for all Apple Mac OS X systems.
’freebsd’ for all other BSD-based unix systems.
’ios’ for all Apple iOS systems.
’linux’ for all other unix systems (like Arch, Debian/Ubuntu, Suse, …).
’win32’ for MS Windows systems (w/o the Cygwin extension).
- os_platform = 'linux'
operating system / platform string (see
_os_platform()).this string value gets determined for most of the operating systems with the help of Python’s
sys.platform()function and additionally detects the operating systems iOS and Android (not supported by Python).
- os_user_name()[source]
determine the operating system username.
- Return type:
- Returns:
username string.
- project_main_file(import_name, project_path='')[source]
determine the main module file path of a project package, containing the project __version__ module variable.
- Parameters:
import_name¶ (
str) – import name of the module/package (including namespace prefixes for namespace packages).project_path¶ (
str) – optional path where the project of the package/module is situated. not needed if the current working directory is the root folder of either the import_name project or of a sister project (under the same project parent folder).
- Return type:
- Returns:
absolute file path/name of main module or empty string if no main/version file found.
- read_file(file_path, extra_mode='', encoding=None, error_handling='ignore')[source]
returning content of the text/binary file specified by file_path argument as string.
- Parameters:
file_path¶ (
str) – file path/name to load into a string or a bytes array.extra_mode¶ (
str) – extra open mode flag characters appended to “r” onto open() mode argument. pass “b” to read the content of a binary file returned as bytes array. in binary mode the argument passed inerror_handlingwill be ignored.encoding¶ (
Optional[str]) – encoding used to load and convert/interpret the file content.error_handling¶ (
str) – for files opened in text mode pass ‘strict’ or None to return None (instead of an empty string) for the cases where either a decoding ValueError exception or any OSError, FileNotFoundError or PermissionError exception got raised. the default value ‘ignore’ will ignore any decoding errors (missing some characters) and will return an empty string on any file/os exception. this parameter will be ignored if theextra_modeargument contains the ‘b’ character (to read the file content as binary/bytes-array).
- Return type:
- Returns:
file content string or bytes array.
- Raises:
FileNotFoundError – if file does not exist.
OSError – if
file_pathis misspelled or contains invalid characters.PermissionError – if current OS user account lacks permissions to read the file content.
ValueError – on decoding errors.
- round_traditional(num_value, num_digits=0)[source]
round numeric value traditional.
needed because python round() is working differently, e.g. round(0.075, 2) == 0.07 instead of 0.08 inspired by https://stackoverflow.com/questions/31818050/python-2-7-round-number-to-nearest-integer.
- snake_to_camel(name, back_convertible=False)[source]
convert name from snake_case to CamelCase.
- Parameters:
name¶ (
str) – name string composed of parts separated by an underscore character (NAME_PARTS_SEP).back_convertible¶ (
bool) – pass True to get the first character of the returned name in lower-case if the snake name has no leading underscore character (and to allow the conversion between snake and camel case without information loss).
- Return type:
- Returns:
name in camel case.
- stack_frames(depth=1)[source]
generator returning the call stack frame from the level given in
depth.- Parameters:
depth¶ (
int) – the stack level to start; the first returned frame by this generator. the default value (1) refers the next deeper stack frame, respectively the one of the caller of this function. pass 2 or a higher value if you want to start with an even deeper frame/level.- Return type:
- Returns:
generated frames of the call stack.
- stack_var(name, *skip_modules, scope='', depth=1)[source]
determine variable value in calling stack/frames.
- Parameters:
name¶ (
str) – variable name to search in the calling stack frames.skip_modules¶ (
str) – module names to skip (def=seeSKIPPED_MODULESmodule constant).scope¶ (
str) – pass ‘locals’ to only check for local variables (ignoring globals) or ‘globals’ to only check for global variables (ignoring locals). the default value (an empty string) will not restrict the scope, returning either a local or global value.depth¶ (
int) – the calling level from which on to search. the default value (1) refers the next deeper stack frame, which is the caller of the function. pass 2 or an even higher value if you want to start the variable search from a deeper level in the call stack.
- Return type:
- Returns:
the variable value of a deeper level within the call stack or UNSET if the variable was not found.
- stack_vars(*skip_modules, find_name='', min_depth=1, max_depth=0, scope='')[source]
determine all global and local variables in a calling stack/frames.
- Parameters:
skip_modules¶ (
str) – module names to skip (def=seeSKIPPED_MODULESmodule constant).find_name¶ (
str) – if passed then the returned stack frame must contain a variable with the passed name.scope¶ (
str) – scope to search the variable name passed viafind_name. pass ‘locals’ to only search for local variables (ignoring globals) or ‘globals’ to only check for global variables (ignoring locals). passing an empty string will find the variable within either locals and globals.min_depth¶ (
int) – the call stack level from which on to search. the default value (1) refers the next deeper stack frame, respectively to the caller of this function. pass 2 or a higher value if you want to get the variables from a deeper level in the call stack.max_depth¶ (
int) – the maximum depth in the call stack from which to return the variables. if the specified argument is not zero and noskip_modulesare specified then the first deeper stack frame that is not within the defaultSKIPPED_MODULESwill be returned. if this argument andfind_nameget not passed then the variables of the top stack frame will be returned.
- Return type:
- Returns:
tuple of the global and local variable dicts and the depth in the call stack.
- sys_env_text(ind_ch=' ', ind_len=12, key_ch='=', key_len=15, extra_sys_env_dict=None)[source]
compile formatted text block with system environment info.
- to_ascii(unicode_str)[source]
converts unicode string into ascii representation.
useful for fuzzy string compare; inspired by MiniQuark’s answer in: https://stackoverflow.com/questions/517923/what-is-the-best-way-to-remove-accents-in-a-python-unicode-string
- write_file(file_path, content, extra_mode='', encoding=None)[source]
(over)write the file specified by
file_pathwith text or binary/bytes content.- Parameters:
file_path¶ (
str) – file path/name to write the passed content into (overwriting any previous content!).content¶ (
Union[str,bytes]) – new file content either passed as string or list of line strings (will be concatenated with the line separator of the current OS: os.linesep).extra_mode¶ (
str) – open mode flag characters. passed unchanged to the mode argument ofopen()if this argument starts with ‘a’, else this argument value will be appended to ‘w’.encoding¶ (
Optional[str]) – encoding used to write/convert/interpret the file content to write.
- Raises:
FileExistsError – if file exists already and is write-protected.
FileNotFoundError – if parts of the file path do not exist.
OSError – if
file_pathis misspelled or contains invalid characters.PermissionError – if current OS user account lacks permissions to read the file content.
ValueError – on decoding errors.