ae-base 0.3.38__tar.gz → 0.3.40__tar.gz

{ae_base-0.3.38/ae_base.egg-info → ae_base-0.3.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.38
+Version: 0.3.40
 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,17 +53,17 @@ 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 aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.38
+# base 0.3.40
 
 [![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.37?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.37)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.39?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.39)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.38.
+>ae_base module 0.3.40.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

{ae_base-0.3.38 → ae_base-0.3.40}/README.md

@@ -1,16 +1,16 @@
 <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae V0.3.94 -->
 <!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.38
+# base 0.3.40
 
 [![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.37?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.37)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.39?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.39)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.38.
+>ae_base module 0.3.40.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

{ae_base-0.3.38 → ae_base-0.3.40}/ae/base.py

@@ -3,7 +3,7 @@ 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.
+functions, useful classes and context managers.
 
 
 base constants
@@ -24,6 +24,9 @@ the constants :data:`PACKAGE_NAME`, :data:`PACKAGE_DOMAIN` and :data:`PERMISSION
 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.
+
 
 base helper functions
 ---------------------
@@ -42,7 +45,7 @@ absolute, call the function :func:`norm_path`.
 
 :func:`camel_to_snake` and :func:`snake_to_camel` providing name conversions of class and method names.
 
-to encode unicode strings to other codecs the functions :func:`force_encoding` and :func:`to_ascii` can be used.
+to encode Unicode strings to other codecs the functions :func:`force_encoding` and :func:`to_ascii` can be used.
 
 the :func:`round_traditional` function get provided by this module for traditional rounding of float values. the
 function signature is fully compatible to Python's :func:`round` function.
@@ -99,6 +102,15 @@ code and build Kivy apps for the Android OS, and to `Gabriel Pettier <https://gi
 osc example.
 
 
+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.
+
+to extend any class with an intelligent error message property, add the mixin :class:`ErrorMsgMixin` to it.
+
+
 generic context manager
 -----------------------
 
@@ -137,6 +149,7 @@ import shutil
 import socket
 import sys
 import unicodedata
+import urllib.parse
 import warnings
 
 from configparser import ConfigParser, ExtendedInterpolation
@@ -146,7 +159,8 @@ from inspect import getinnerframes, getouterframes, getsourcefile
 from types import ModuleType
 from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Tuple, Union, cast
 
-__version__ = '0.3.38'
+
+__version__ = '0.3.40'
 
 
 DOCS_FOLDER = 'docs'                            #: project documentation root folder name
@@ -200,7 +214,9 @@ _env_variable = re.compile(r"""
     """, re.IGNORECASE | re.VERBOSE)
 
 
-NAME_PARTS_SEP = '_'                            #: name parts separator character, e.g. for :func:`norm_name`
+NAME_PARTS_SEP = '_'                                #: name parts separator character, e.g. for :func:`norm_name`
+
+NOW_STR_FORMAT = "{sep}%Y%m%d{sep}%H%M%S{sep}%f"    #: timestamp format of :func:`now_str`
 
 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',
@@ -610,9 +626,12 @@ def now_str(sep: str = "") -> str:
 
     :param sep:                 optional prefix and separator character (separating date from time and in time part
                                 the seconds from the microseconds).
-    :return:                    UTC timestamp as string (length=20 + 3 * len(sep)).
+    :return:                    naive UTC timestamp (without timezone info) as string (length=20 + 3 * len(sep)).
     """
-    return datetime.datetime.utcnow().strftime("{sep}%Y%m%d{sep}%H%M%S{sep}%f".format(sep=sep))
+    # if sys.version_info >= (3, 12):
+    return datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None).strftime(NOW_STR_FORMAT.format(sep=sep))
+    # else:
+    #     return datetime.datetime.utcnow().strftime(NOW_STR_FORMAT.format(sep=sep))
 
 
 def os_host_name() -> str:
@@ -921,7 +940,7 @@ def sys_env_text(ind_ch: str = " ", ind_len: int = 12, key_ch: str = "=", key_le
                  extra_sys_env_dict: Optional[Dict[str, str]] = None) -> str:
     """ compile formatted text block with system environment info.
 
-    :param ind_ch:              indent character (default=" ").
+    :param ind_ch:              indent character (defaults to " ").
     :param ind_len:             indent depths (default=12 characters).
     :param key_ch:              key-value separator character (default="=").
     :param key_len:             key-name minimum length (default=15 characters).
@@ -940,7 +959,7 @@ def sys_env_text(ind_ch: str = " ", ind_len: int = 12, key_ch: str = "=", key_le
 
 
 def to_ascii(unicode_str: str) -> str:
-    """ converts unicode string into ascii representation.
+    """ 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
@@ -952,6 +971,36 @@ def to_ascii(unicode_str: str) -> str:
     return "".join([c for c in nfkd_form if not unicodedata.combining(c)]).replace('ß', "ss").replace('€', "Euro")
 
 
+def uri2filename(uri: str) -> str:
+    """ convert a URI to be usable as name of a file or folder
+
+    :param uri:                 URI to convert to a corresponding file name, that will be revertible back to this URI.
+    :return:                    name of a file/folder representing the specified URI.
+
+    in *nix only / and \0 are not allowed characters in file names.
+    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 _).
+
+    file name length is not restricted/shortened by this function, although the maximum is 255 characters on most OSs.
+
+    more on allowed characters in file names in the answers of RedGrittyBrick on https://superuser.com/questions/358855
+    and of Christopher Oezbek on https://stackoverflow.com/questions/1976007.
+    """
+    # using urllib.parse.quote(uri, safe="") instead would convert also any non-ascii (e.g. umlaut) characters into hex
+    # added [] to str.join() argument because List comprehensions are faster than generator expressions
+    return "".join([f"%{hex(ord(_))[2:].upper()}" if _ in '/|\\:*?"<>%' else _ for _ in uri])
+
+
+def filename2uri(file_name: str) -> str:
+    """ convert a file name converted by :func:`uri2filename` back to its representation as a URI
+
+    :param file_name:           name of the file/folder to convert back to its URI representation.
+    :return:                    URI string.
+    """
+    return urllib.parse.unquote(file_name)
+
+
 def write_file(file_path: str, content: Union[str, bytes], extra_mode: str = "", encoding: Optional[str] = None):
     """ (over)write the file specified by :paramref:`~write_file.file_path` with text or binary/bytes content.
 
@@ -966,11 +1015,42 @@ def write_file(file_path: str, content: Union[str, bytes], extra_mode: str = "",
     :raises OSError:            if :paramref:`~read_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
+    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
     """
     with open(file_path, ('' if extra_mode.startswith('a') else 'w') + extra_mode, encoding=encoding) as file_handle:
         file_handle.write(content)
 
 
+class ErrorMsgMixin:
+    """ mixin class providing error message """
+    _err_msg: str = ""
+
+    @property
+    def error_message(self) -> str:
+        """ error message string if an error occurred or an empty string if not.
+
+        :getter:                return the accumulated error message of the recently occurred error(s).
+        :setter:                any assigned error message will be accumulated to recent error messages.
+                                pass an empty string to reset the error message.
+        """
+        return self._err_msg
+
+    @error_message.setter
+    def error_message(self, next_err_msg: str):
+        if 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"

{ae_base-0.3.38 → ae_base-0.3.40/ae_base.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.38
+Version: 0.3.40
 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,17 +53,17 @@ 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 aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.38
+# base 0.3.40
 
 [![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.37?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.37)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.39?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.39)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.38.
+>ae_base module 0.3.40.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

{ae_base-0.3.38 → ae_base-0.3.40}/tests/test_base.py

@@ -20,9 +20,12 @@ from ae.base import (
     load_env_var_defaults, load_dotenvs, main_file_paths_parts, module_attr, module_file_path, module_name,
     norm_line_sep, norm_name, norm_path, now_str, os_host_name, os_local_ip, _os_platform, os_user_name,
     parse_dotenv, project_main_file, read_file, round_traditional, snake_to_camel, stack_frames, stack_var, stack_vars,
-    sys_env_dict, sys_env_text, to_ascii, write_file)
+    sys_env_dict, sys_env_text, to_ascii, filename2uri, uri2filename, write_file, ErrorMsgMixin)
 
 
+tst_uri1 = "schema://user:pwd@domain/path_root/path_sub\\path+file% Üml?ä|ït.path_ext*\"<>"
+tst_fna1 = "schema%3A%2F%2Fuser%3Apwd@domain%2Fpath_root%2Fpath_sub%5Cpath+file%25 Üml%3Fä%7Cït.path_ext%2A%22%3C%3E"
+
 env_var_name = 'env_var_nam1'
 env_var_val = 'value of env var'
 folder_name = 'fdr'
@@ -60,6 +63,27 @@ def test_unset_null_length():
     assert len(UNSET) == 0
 
 
+class TestErrorMsgMixin:
+    def test_instantiation(self):
+        assert ErrorMsgMixin()
+
+    def test_error_message_property(self):
+        ins = ErrorMsgMixin()
+        assert ins.error_message == ""
+
+        err_msg = "set new error message"
+        ins.error_message = err_msg
+        assert ins.error_message == err_msg
+
+        err_msg2 = "added error message"
+        ins.error_message = err_msg2
+        assert err_msg in ins.error_message
+        assert err_msg2 in ins.error_message
+
+        ins.error_message = ""
+        assert ins.error_message == ""
+
+
 class TestBaseHelpers:
     def test_app_name_guess(self):
         assert app_name_guess()     # app.exe name in pytest returning '_jb_pytest_runner'(PyCharm)/'__main__'(console)
@@ -678,6 +702,21 @@ class TestBaseHelpers:
         assert to_ascii('ß') == 'ss'
         assert to_ascii('€') == 'Euro'
 
+    def test_filename2uri(self):
+        assert filename2uri(tst_fna1) == tst_uri1
+        assert uri2filename(filename2uri(tst_fna1)) == tst_fna1
+
+    def test_uri2filename(self):
+        assert uri2filename(tst_uri1) == tst_fna1
+        assert filename2uri(uri2filename(tst_uri1)) == tst_uri1
+
+    def test_uri_file_name(self):
+        try:
+            write_file(tst_fna1, "tst uri file content")
+        finally:
+            if os.path.exists(tst_fna1):
+                os.remove(tst_fna1)
+
     def test_write_file_as_text(self):
         test_file = os.path.join(TESTS_FOLDER, 'tst_file_written.ext')
         content = "any content"