ae-base 0.3.47__py3-none-any.whl → 0.3.49__py3-none-any.whl

ae/base.py

@@ -5,6 +5,11 @@ basic constants, helper functions and context manager
 this module is pure python, has no external dependencies, and is providing base constants, common helper
 functions, useful classes and context managers.
 
+.. note::
+    on import of this module, while running on Android OS, it will monkey patch the :mod:`shutil` module
+    to allow to use them on Android devices. therefore the import of this module should be one of the first ones
+    in your app's main module.
+
 
 base constants
 --------------
@@ -20,10 +25,6 @@ default values to compile file and folder names for a package or an app project
 :data:`PACKAGE_INCLUDE_FILES_PREFIX`, :data:`PY_EXT`, :data:`PY_INIT`, :data:`PY_MAIN`, :data:`CFG_EXT`
 and :data:`INI_EXT`.
 
-the constants :data:`PACKAGE_NAME`, :data:`PACKAGE_DOMAIN` and :data:`PERMISSIONS` are mainly
-used for apps running on mobile devices. to avoid redundancies, these values get loaded from the
-:data:`build config file <BUILD_CONFIG_FILE>` - if it exists in the current working directory.
-
 with the help of the format string constant :data:`NOW_STR_FORMAT` and the function :func:`now_str` you can create a
 sortable and compact string from a timestamp.
 
@@ -82,31 +83,13 @@ variables for your application are :func:`sys_env_dict` and :func:`sys_env_text`
 to integrate system environment variables from ``.env`` files into :data:`os.environ` the helper functions
 :func:parse_dotenv`, :func:`load_env_var_defaults` and :func:`load_dotenvs` are provided.
 
+the :mod:`ae.core` portion is providing more OS-specific constants and helper functions, like e.g.
+:func:`start_app_service` and :func:`request_app_permissions`.
 
-android-specific constants and helper functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-some helper functions of this module are provided to be used for the Android OS.
-
-the helper function :func:`start_app_service` is starting a service in its own, separate thread.
-with the function :func:`request_app_permissions` you can ensure that all your Android permissions will be
-requested. the module :mod:`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 :mod:`shutil` module to prevent crashes.
-
-links to other android code and service examples and documentation:
-
-    * `https://python-for-android.readthedocs.io/en/latest/`__
-    * `https://github.com/kivy/python-for-android/tree/develop/pythonforandroid/recipes/android/src/android`__
-    * `https://github.com/tshirtman/kivy_service_osc/blob/master/src/main.py`__
-    * `https://blog.kivy.org/2014/01/building-a-background-application-on-android-with-kivy/`__
-    * `https://github.com/Android-for-Python/Android-for-Python-Users`__
-    * `https://github.com/Android-for-Python/INDEX-of-Examples`__
-
-big thanks to `Robert Flatt <https://github.com/RobertFlatt>`__ for his investigations, findings and documentations to
-code and build Kivy apps for the Android OS, and to `Gabriel Pettier <https://github.com/tshirtman>`__ for his service
-osc example.
+.. note::
+    on import of this module, while running on Android OS, it will monkey patch the :mod:`shutil` module to allow to
+    use them on Android devices, and on first app start request the permissions of your app. therefore to prevent
+    permission errors, the import of this module should be the first statement in the main module of your app.
 
 
 types, classes and mixins
@@ -117,6 +100,9 @@ allowing also ``None`` is an accepted argument value.
 
 to extend any class with an intelligent error message handling, add the mixin :class:`ErrorMsgMixin` to it.
 
+the classes :class:`UnformattedValue` and :class:`GivenFormatter` can be used to format strings with placeholders
+enclosed in curly brackets. the function :func:`format_given` is using them to format templates with placeholders.
+
 
 generic context manager
 -----------------------
@@ -149,7 +135,7 @@ another useful helper function provided by this portion to inspect and debug you
 os.path shortcuts
 -----------------
 
-the following data items are pointers to shortcut the lookup to their related functions in the
+the following data items are pointers to shortcut at runtime the lookup to their related functions in the
 Python module :mod:`os.path`:
 """
 import datetime
@@ -161,6 +147,7 @@ import platform
 import re
 import shutil
 import socket
+import string
 import sys
 import unicodedata
 import warnings
@@ -173,7 +160,7 @@ from types import ModuleType
 from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Tuple, Union, cast
 
 
-__version__ = '0.3.47'
+__version__ = '0.3.49'
 
 
 os_path_abspath = os.path.abspath
@@ -248,8 +235,7 @@ NOW_STR_FORMAT = "{sep}%Y%m%d{sep}%H%M%S{sep}%f"    #: timestamp format of :func
 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',   # removed in V 0.1.4: 'ae.lisz_app_data',
-                   'importlib._bootstrap', 'importlib._bootstrap_external')
+                   'ae.qpython_app', 'ae.appjar_app', 'importlib._bootstrap', 'importlib._bootstrap_external')
 """ skipped modules used as default by :func:`module_name`, :func:`stack_var` and :func:`stack_vars` """
 
 
@@ -487,6 +473,50 @@ def force_encoding(text: Union[str, bytes], encoding: str = DEF_ENCODING, errors
     return enc_str.decode(encoding=encoding)
 
 
+class UnformattedValue:
+    """ helper class for :func:`~ae.base.format_given` to keep placeholder with format unchanged if not found. """
+    def __init__(self, key: str):
+        self.key = key
+
+    def __format__(self, format_spec: str):
+        """ overriding Python object class method to return placeholder unchanged including the curly brackets. """
+        return "{{{}{}}}".format(self.key, ":" + format_spec if format_spec else "")
+
+
+class GivenFormatter(string.Formatter):
+    """ helper class for :func:`~ae.base.format_given` to keep placeholder with format unchanged if not found. """
+    def get_value(self, key, args, kwargs):
+        """ overriding to keep placeholder unchanged if not found """
+        try:
+            return super().get_value(key, args, kwargs)
+        except KeyError:
+            return UnformattedValue(key)
+
+
+def format_given(text: str, placeholder_map: dict[str, Any], strict: bool = False):
+    """ replacement for Python's str.format_map(), keeping intact placeholders that are not in the specified mapping.
+
+    :param text:                text/template in which the given/specified placeholders will get replaced. in contrary
+                                to str.format_map() no KeyError will be raised for placeholders not specified in
+                                :paramref:`~format_given.placeholder_map`.
+    :param placeholder_map:     dict with placeholder keys to be replaced in :paramref:`~format_given.text` argument.
+    :param strict:              pass True to raise error for text templates containing unpaired curly brackets.
+    :return:                    the specified :paramref:`~format_given.text` with only the placeholders specified in
+                                :paramref:`~format_given.placeholder_map` replaced with their respective map value.
+                                additionally any ValueError that would be thrown by str.format_map(), e.g. if the
+
+
+    inspired by the answer of CodeManX in `https://stackoverflow.com/questions/3536303`__
+    """
+    formatter = GivenFormatter()
+    try:
+        return formatter.vformat(text, (), placeholder_map)
+    except (ValueError, Exception) as ex:
+        if strict:
+            raise ex
+        return text
+
+
 def full_stack_trace(ex: Exception) -> str:
     """ get full stack trace from an exception.
 
@@ -758,7 +788,7 @@ def os_host_name() -> str:
 
     :return:                    machine name string.
     """
-    return defuse(platform.node()) or "undeterminableHostName"
+    return defuse(platform.node()) or "indeterminableHostName"
 
 
 def os_local_ip() -> str:
@@ -1190,23 +1220,6 @@ class ErrorMsgMixin:
             self._err_msg = ""
 
 
-# package and permissions handling defaults for all other platforms and frameworks
-PACKAGE_NAME = stack_var('__name__') or 'unspecified_package'                       #: package name default
-PACKAGE_DOMAIN = 'org.test'                                                         #: package domain default
-PERMISSIONS = "INTERNET, VIBRATE, READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE"    #: permissions default
-if os_path_isfile(BUILD_CONFIG_FILE):                           # pragma: no cover
-    PACKAGE_NAME, PACKAGE_DOMAIN, PERMISSIONS = build_config_variable_values(
-        ('package.name', PACKAGE_NAME),
-        ('package.domain', PACKAGE_DOMAIN),
-        ('android.permissions', PERMISSIONS))
-elif os_platform == 'android':                                  # pragma: no cover
-    _importing_package = norm_path(stack_var('__file__') or 'empty_package' + PY_EXT)
-    if os_path_basename(_importing_package) in (PY_INIT, PY_MAIN):
-        _importing_package = os_path_dirname(_importing_package)
-    _importing_package = os_path_splitext(os_path_basename(_importing_package))[0]
-    write_file(f'{_importing_package}_debug.log', f"{BUILD_CONFIG_FILE} not bundled - using defaults\n", extra_mode='a')
-
-
 if os_platform == 'android':                                    # pragma: no cover
     # monkey patch the :func:`shutil.copystat` and :func:`shutil.copymode` helper functions, which are crashing on
     # 'android' (see # `<https://bugs.python.org/issue28141>`__ and `<https://bugs.python.org/issue32073>`__). these
@@ -1216,41 +1229,3 @@ if os_platform == 'android':                                    # pragma: no cov
     # on the destination root directory.
     shutil.copymode = dummy_function
     shutil.copystat = dummy_function
-
-    # import permissions module from python-for-android (recipes/android/src/android/permissions.py)
-    # noinspection PyUnresolvedReferences
-    from android.permissions import request_permissions, Permission     # type: ignore # pylint: disable=import-error
-    from jnius import autoclass                                         # type: ignore
-
-    def request_app_permissions(callback: Optional[Callable[[List[Permission], List[bool]], None]] = None):
-        """ request app/service permissions on Android OS.
-
-        :param callback:        optional callback receiving two list arguments with identical length,
-                                the 1st with the requested permissions and
-                                the 2nd with booleans stating if the permission got granted (True) or rejected (False).
-        """
-        permissions = []
-        for permission_str in PERMISSIONS.split(','):
-            permission = getattr(Permission, permission_str.strip(), None)
-            if permission:
-                permissions.append(permission)
-        request_permissions(permissions, callback=callback)
-
-    def start_app_service(service_arg: str = "") -> Any:
-        """ start service.
-
-        :param service_arg:     string value to be assigned to environment variable PYTHON_SERVICE_ARGUMENT on start.
-        :return:                service instance.
-
-        see `<https://github.com/tshirtman/kivy_service_osc/blob/master/src/main.py>`__
-        and `<https://python-for-android.readthedocs.io/en/latest/services/#arbitrary-scripts-services>`__
-        """
-        service_instance = autoclass(f"{PACKAGE_DOMAIN}.{PACKAGE_NAME}.Service{PACKAGE_NAME.capitalize()}")
-        activity = autoclass('org.kivy.android.PythonActivity').mActivity
-        service_instance.start(activity, service_arg)        # service_arg will be in env var PYTHON_SERVICE_ARGUMENT
-
-        return service_instance
-
-else:
-    request_app_permissions = dummy_function
-    start_app_service = dummy_function

{ae_base-0.3.47.dist-info → ae_base-0.3.49.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: ae_base
-Version: 0.3.47
+Version: 0.3.49
 Summary: ae namespace module portion base: basic constants, helper functions and context manager
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -53,20 +53,32 @@ Requires-Dist: typing; extra == "tests"
 Requires-Dist: types-setuptools; extra == "tests"
 Requires-Dist: wheel; extra == "tests"
 Requires-Dist: twine; extra == "tests"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
 
 <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae V0.3.95 -->
 <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.47
+# base 0.3.49
 
 [![GitLab develop](https://img.shields.io/gitlab/pipeline/ae-group/ae_base/develop?logo=python)](
     https://gitlab.com/ae-group/ae_base)
 [![LatestPyPIrelease](
-    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.46?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.46)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.48?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.48)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.47.
+>ae_base module 0.3.49.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

ae_base-0.3.49.dist-info/RECORD

@@ -0,0 +1,7 @@
+ae/base.py,sha256=V0wU87UunINFILcnar0HlBvF6gB8nLnj1tfQ-uXoCiY,61257
+ae_base-0.3.49.dist-info/LICENSE.md,sha256=uoIIfORuk4V8ZeNh6SN0EUhiU79RC-indIMFqePKVhY,35002
+ae_base-0.3.49.dist-info/METADATA,sha256=Ezl-iNQcsr9r0ssjPJAVgVTvZcQZDbHIqno7of0zTos,5636
+ae_base-0.3.49.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+ae_base-0.3.49.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
+ae_base-0.3.49.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ae_base-0.3.49.dist-info/RECORD,,

{ae_base-0.3.47.dist-info → ae_base-0.3.49.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

ae_base-0.3.47.dist-info/RECORD

@@ -1,7 +0,0 @@
-ae/base.py,sha256=MYA5vcALiaubDxxDLDUywjXwMldKpijjN6LPoixWIto,63016
-ae_base-0.3.47.dist-info/LICENSE.md,sha256=uoIIfORuk4V8ZeNh6SN0EUhiU79RC-indIMFqePKVhY,35002
-ae_base-0.3.47.dist-info/METADATA,sha256=TF_qiiV2cvZ1dHeZrCSV1M_QKYgvTv-aKzlL9nxttYQ,5382
-ae_base-0.3.47.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-ae_base-0.3.47.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
-ae_base-0.3.47.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-ae_base-0.3.47.dist-info/RECORD,,