ae-base 0.3.44__py3-none-any.whl → 0.3.46__py3-none-any.whl

ae/base.py

@@ -9,10 +9,10 @@ functions, useful classes and context managers.
 base constants
 --------------
 
-ISO format strings for `date` and `datetime` values are provided by the constants :data:`DATE_ISO` and
+ISO format strings for ``date`` and ``datetime`` values are provided by the constants :data:`DATE_ISO` and
 :data:`DATE_TIME_ISO`.
 
-the :data:`UNSET` constant is useful in cases where `None` is a valid data value and another special value is needed
+the :data:`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:
@@ -20,8 +20,8 @@ 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
+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
@@ -104,8 +104,8 @@ links to other android code and service examples and documentation:
     * `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
+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.
 
 
@@ -113,9 +113,9 @@ types, classes and mixins
 -------------------------
 
 the :class:`UnsetType` class can be used e.g. for the declaration of optional function and method parameters,
-allowing also `None` is an accepted argument value.
+allowing also ``None`` is an accepted argument value.
 
-to extend any class with an intelligent error message property, add the mixin :class:`ErrorMsgMixin` to it.
+to extend any class with an intelligent error message handling, add the mixin :class:`ErrorMsgMixin` to it.
 
 
 generic context manager
@@ -173,7 +173,7 @@ from types import ModuleType
 from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Tuple, Union, cast
 
 
-__version__ = '0.3.44'
+__version__ = '0.3.46'
 
 
 os_path_abspath = os.path.abspath
@@ -265,7 +265,7 @@ class UnsetType:
         return 0
 
 
-UNSET = UnsetType()     #: pseudo value used for attributes/arguments if `None` is needed as a valid value
+UNSET = UnsetType()     #: pseudo value used for attributes/arguments if ``None`` is needed as a valid value
 
 
 def app_name_guess() -> str:
@@ -363,9 +363,13 @@ ASCII_UNICODE = (
     ('%', '﹪'),     # U+FE6A: Small Percent Sign
     ('^', '＾'),     # U+FF3E: Fullwidth Circumflex Accent
     (',', '﹐'),     # U+FE50: Small Comma
-    (' ', '　'),     # U+3000: Ideographic Space; ' ' U+200A Hair Space; ' ' U+2007 Figure Space;
-                    # ' ' U+2009 Thin; ' ' U+2003 Em Space; ' ' U+2002 En Space; ' ' U+2008 Punctuation Space
-                    # ' ' U+00A0: No-Break Space (NBSP); ' ' U+202F: Narrow No-Break Space (NNBSP)
+    (' ', '␣'),     # U+2423: Open Box; more see underneath and https://unicode-explorer.com/articles/space-characters:
+                    # ' ' U+00A0: No-Break Space (NBSP); '?¿?' U+1680 Ogham Space Mark; ' ' U+2000 En Quad;
+                    # ' ' U+2001 Em Quad; ' ' U+2002 En Space; ' ' U+2003 Em Space; ' ' U+2004 Three-Per-Em
+                    # ' ' U+2005 Four-Per-Em; ' ' U+2006 Six-Per-Em; ' ' U+2007 Figure Space;
+                    # ' ' U+2008 Punctuation Space; ' ' U+2009 Thin; ' ' U+200A Hair Space;
+                    # ' ' U+202F: Narrow No-Break Space (NNBSP); ' ' U+205F Medium Mathematical Space;
+                    # '␠' U+2420 symbol for space; '␣' U+2423 Open Box; '　' U+3000: Ideographic Space
     (chr(127), '␡'),  # U+2421: DELETE SYMBOL
     # ('_', '𛲖'),     # U+1BC96: Duployan Affix Low Line; '＿' U+FF3F Fullwidth Low Line
 )
@@ -401,10 +405,11 @@ def defuse(value: str) -> str:
 
     the ASCII character range 0..31 gets converted to the Unicode range U+2400 + ord(char): 0==U+2400 ... 31==U+241F.
 
-    in *nix only / and \0 are not allowed characters in file names.
+    in most unix variants only the slash and the ASCII 0 characters are not allowed in file names.
 
-    in MS Windows are not allowed: ASCII 0...31): / | \\ : * ? ” % < > ( ). some blogs recommend to also not allow
+    in MS Windows are not allowed: ASCII 0..31 / | \\ : * ? ” % < > ( ). some blogs recommend to also not allow
     (convert) the characters # and '.
+
     only old POSIX seems to be even more restricted (only allowing alphanumeric characters plus . - and _).
 
     more on allowed characters in file names in the answers of RedGrittyBrick on https://superuser.com/questions/358855
@@ -412,7 +417,7 @@ def defuse(value: str) -> str:
 
     file name length is not restricted/shortened by this function, although the maximum is 255 characters on most OSs.
 
-    .. hint:: use :func:`dedefuse` to convert the defused string back to the corresponding URI/file-path.
+    .. hint:: use the :func:`dedefuse` function to convert the defused string back to the corresponding URI/file-path.
 
     """
     defused = ""
@@ -659,7 +664,7 @@ def module_file_path(local_object: Optional[Callable] = None) -> str:
 def module_name(*skip_modules: str, depth: int = 0) -> Optional[str]:
     """ find the first module in the call stack that is *not* in :paramref:`~module_name.skip_modules`.
 
-    :param skip_modules:        module names to skip (def=this ae.core module).
+    :param skip_modules:        module names to skip (def=this and other core modules, see :data:`SKIPPED_MODULES`).
     :param depth:               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
@@ -847,12 +852,11 @@ def parse_dotenv(file_path: str) -> Dict[str, str]:
             delimiter = None
         if delimiter != "'":
             for parts in _env_variable.findall(var_val):
-                if parts[0] == '\\':
-                    replace = "".join(parts[1:-1])          # don't replace escaped variables
-                else:
-                    # substitute variables in a value, replace it with the value from the environment
-                    replace = env_vars.get(parts[-1], os.environ.get(parts[-1], ""))
-                var_val = var_val.replace("".join(parts[0:-1]), replace)
+                # substitute env variables in a value with its value, if declared and not escaped
+                if parts[0] == '\\' or (replace := env_vars.get(parts[-1], os.environ.get(parts[-1], UNSET))) is UNSET:
+                    replace = "".join(parts[1:-1])  # don't replace escaped/undeclared vars to prevent value cut at '$'
+
+                var_val = var_val.replace("".join(parts[0:-1]), cast(str, replace))
 
         env_vars[var_nam] = var_val
 
@@ -897,8 +901,8 @@ def read_file(file_path: str, extra_mode: str = "", encoding: Optional[str] = No
                                 read the content of a binary file returned as bytes array. in binary mode the argument
                                 passed in :paramref:`~read_file.error_handling` will be ignored.
     :param encoding:            encoding used to load and convert/interpret the file content.
-    :param error_handling:      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
+    :param error_handling:      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
@@ -1092,7 +1096,8 @@ def utc_datetime() -> datetime.datetime:
     return datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
 
 
-def write_file(file_path: str, content: Union[str, bytes], extra_mode: str = "", encoding: Optional[str] = None):
+def write_file(file_path: str, content: Union[str, bytes],
+               extra_mode: str = "", encoding: Optional[str] = None, make_dirs: bool = False):
     """ (over)write the file specified by :paramref:`~write_file.file_path` with text or binary/bytes content.
 
     :param file_path:           file path/name to write the passed content into (overwriting any previous content!).
@@ -1105,21 +1110,26 @@ def write_file(file_path: str, content: Union[str, bytes], extra_mode: str = "",
                                 be automatically added to the `mode` argument of :func:`open` (if not already specified
                                 in this argument).
     :param encoding:            encoding used to write/convert/interpret the file content to write.
+    :param make_dirs:           pass True to automatically create not existing folders specified in
+                                :paramref:`~write_file.file_path`.
     :raises FileExistsError:    if file exists already and is write-protected.
     :raises FileNotFoundError:  if parts of the file path do not exist.
     :raises OSError:            if :paramref:`~write_file.file_path` is misspelled or contains invalid characters.
     :raises PermissionError:    if current OS user account lacks permissions to read the file content.
     :raises ValueError:         on decoding errors.
 
-    to extend this function for Android 14+ see https://github.com/beeware/toga/pull/1158#issuecomment-2254564657
-    and https://gist.github.com/neonankiti/05922cf0a44108a2e2732671ed9ef386
+    to extend this function for Android 14+ see `<https://github.com/beeware/toga/pull/1158#issuecomment-2254564657>`__
+    and `<https://gist.github.com/neonankiti/05922cf0a44108a2e2732671ed9ef386>`__
     Yes, to use ACTION_CREATE_DOCUMENT, you don't supply a URI in the intent. You wait for the intent result, and that
     will contain a URI which you can write to.
-    See #1158 (comment - https://github.com/beeware/toga/pull/1158#issuecomment-2254564657) for a link to a Java
-    example, and #1158 (comment - https://github.com/beeware/toga/pull/1158#issuecomment-1446196973) for how to wait
-    for an intent result.
-    Related german docs: https://developer.android.com/training/data-storage/shared/media?hl=de
+    See #1158 (comment - `<https://github.com/beeware/toga/pull/1158#issuecomment-2254564657>`__) for a link to a Java
+    example, and #1158 (comment - `<https://github.com/beeware/toga/pull/1158#issuecomment-1446196973>`__) for how to
+    wait for an intent result.
+    Related german docs: `<https://developer.android.com/training/data-storage/shared/media?hl=de>`__
     """
+    if make_dirs and (dir_path := os_path_dirname(file_path)):
+        os.makedirs(dir_path, exist_ok=True)
+
     if isinstance(content, bytes) and 'b' not in extra_mode:
         extra_mode += 'b'
 
@@ -1131,9 +1141,33 @@ def write_file(file_path: str, content: Union[str, bytes], extra_mode: str = "",
 
 
 class ErrorMsgMixin:
-    """ mixin class providing error message """
+    """ mixin class providing sophisticated error message handling. """
     _err_msg: str = ""
 
+    cae = None
+    po = print
+    dpo = print
+    vpo = print
+
+    def __init__(self):
+        try:
+            from ae.core import main_app_instance       # type: ignore
+
+            self.cae = cae = main_app_instance()
+            assert cae is not None, f"{self.__class__.__name__}.__init__() called too early; main app instance not"
+
+            self.po = cae.po
+            self.dpo = cae.dpo
+            self.vpo = cae.vpo
+
+        except (ImportError, AssertionError, Exception) as exc:
+            print(f"{self.__class__.__name__}.__init__() raised {exc}; using print() instead of main app error loggers")
+
+            # self.cae = None
+            # self.po = print
+            # self.dpo = print
+            # self.vpo = print
+
     @property
     def error_message(self) -> str:
         """ error message string if an error occurred or an empty string if not.
@@ -1147,14 +1181,19 @@ class ErrorMsgMixin:
     @error_message.setter
     def error_message(self, next_err_msg: str):
         if next_err_msg:
+            if "WARNING" in next_err_msg.upper():
+                self.vpo(f" .::. {next_err_msg}")
+            else:
+                self.dpo(f" .::. {next_err_msg}")
             self._err_msg += ("\n\n" if self._err_msg else "") + next_err_msg
         else:
             self._err_msg = ""
 
 
-PACKAGE_NAME = stack_var('__name__') or 'unspecified_package'
-PACKAGE_DOMAIN = 'org.test'
-PERMISSIONS = "INTERNET, VIBRATE, READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE"
+# 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),
@@ -1170,8 +1209,8 @@ elif os_platform == 'android':                                  # pragma: no cov
 
 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 functions are
-    # used by shutil.copy2/copy/copytree/move to copy OS-specific file attributes.
+    # 'android' (see # `<https://bugs.python.org/issue28141>`__ and `<https://bugs.python.org/issue32073>`__). these
+    # functions are used by shutil.copy2/copy/copytree/move to copy OS-specific file attributes.
     # although shutil.copytree() and shutil.move() are copying/moving the files correctly when the copy_function
     # arg is set to :func:`shutil.copyfile`, they will finally also crash afterward when they try to set the attributes
     # on the destination root directory.
@@ -1203,8 +1242,8 @@ if os_platform == 'android':                                    # pragma: no cov
         :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
+        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

{ae_base-0.3.44.dist-info → ae_base-0.3.46.dist-info}/LICENSE.md

@@ -1,4 +1,4 @@
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_project V0.3.31 -->
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_project V0.3.32 -->
 ### GNU GENERAL PUBLIC LICENSE
 
 Version 3, 29 June 2007

{ae_base-0.3.44.dist-info → ae_base-0.3.46.dist-info}/METADATA

@@ -1,11 +1,12 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.44
+Version: 0.3.46
 Summary: ae namespace module portion base: basic constants, helper functions and context manager
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
 Author-email: aecker2@gmail.com
 License: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Project-URL: Bug Tracker, https://gitlab.com/ae-group/ae_base/-/issues
 Project-URL: Documentation, https://ae.readthedocs.io/en/latest/_autosummary/ae.base.html
 Project-URL: Repository, https://gitlab.com/ae-group/ae_base
 Project-URL: Source, https://ae.readthedocs.io/en/latest/_modules/ae/base.html
@@ -22,11 +23,11 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Provides-Extra: dev
-Requires-Dist: aedev-tpl-project; extra == "dev"
-Requires-Dist: ae-ae; extra == "dev"
+Requires-Dist: aedev_tpl_project; extra == "dev"
+Requires-Dist: ae_ae; extra == "dev"
 Requires-Dist: anybadge; extra == "dev"
 Requires-Dist: coverage-badge; extra == "dev"
-Requires-Dist: aedev-git-repo-manager; extra == "dev"
+Requires-Dist: aedev_git_repo_manager; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pylint; extra == "dev"
@@ -41,7 +42,7 @@ Provides-Extra: docs
 Provides-Extra: tests
 Requires-Dist: anybadge; extra == "tests"
 Requires-Dist: coverage-badge; extra == "tests"
-Requires-Dist: aedev-git-repo-manager; extra == "tests"
+Requires-Dist: aedev_git_repo_manager; extra == "tests"
 Requires-Dist: flake8; extra == "tests"
 Requires-Dist: mypy; extra == "tests"
 Requires-Dist: pylint; extra == "tests"
@@ -53,19 +54,19 @@ Requires-Dist: types-setuptools; extra == "tests"
 Requires-Dist: wheel; extra == "tests"
 Requires-Dist: twine; extra == "tests"
 
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae V0.3.94 -->
+<!-- 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.44
+# base 0.3.46
 
 [![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.43?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.43)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.45?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.45)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.44.
+>ae_base module 0.3.46.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

ae_base-0.3.46.dist-info/RECORD

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

{ae_base-0.3.44.dist-info → ae_base-0.3.46.dist-info}/WHEEL

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

ae_base-0.3.44.dist-info/RECORD

@@ -1,7 +0,0 @@
-ae/base.py,sha256=QByzHC7yJb-vSrTfX0C1U5AQsQK0J105ZiclDnJTMzs,60890
-ae_base-0.3.44.dist-info/LICENSE.md,sha256=eHVr16LWo8bsm2NbdFOBcQp-F_3MUXo9I922sABpsMQ,35002
-ae_base-0.3.44.dist-info/METADATA,sha256=x5tlK4rJO-YdGoCtz1OyaELmV0k4CqBt3UHiZdo9TEQ,5311
-ae_base-0.3.44.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
-ae_base-0.3.44.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
-ae_base-0.3.44.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-ae_base-0.3.44.dist-info/RECORD,,