ae-base 0.3.37__py3-none-any.whl → 0.3.39__py3-none-any.whl

ae/base.py

@@ -42,7 +42,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.
@@ -137,6 +137,7 @@ import shutil
 import socket
 import sys
 import unicodedata
+import urllib.parse
 import warnings
 
 from configparser import ConfigParser, ExtendedInterpolation
@@ -146,7 +147,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.37'
+
+__version__ = '0.3.39'
 
 
 DOCS_FOLDER = 'docs'                            #: project documentation root folder name
@@ -435,7 +437,8 @@ def load_dotenvs():
     .. hint:: call from main module of project/app in order to also load ``.env`` files in/above the project folder.
     """
     load_env_var_defaults(os.getcwd())
-    load_env_var_defaults(os.path.dirname(stack_var('__file__', depth=2)))
+    if file_name := stack_var('__file__'):
+        load_env_var_defaults(os.path.dirname(os.path.abspath(file_name)))
 
 
 def load_env_var_defaults(start_dir: str):
@@ -920,7 +923,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).
@@ -939,7 +942,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
@@ -951,6 +954,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.
 
@@ -965,11 +998,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.37.dist-info → ae_base-0.3.39.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.37
+Version: 0.3.39
 Summary: ae namespace module portion base: basic constants, helper functions and context manager
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -22,48 +22,48 @@ 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: anybadge ; extra == 'dev'
-Requires-Dist: coverage-badge ; 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'
-Requires-Dist: pytest ; extra == 'dev'
-Requires-Dist: pytest-cov ; extra == 'dev'
-Requires-Dist: typing ; extra == 'dev'
-Requires-Dist: types-setuptools ; extra == 'dev'
-Requires-Dist: wheel ; extra == 'dev'
-Requires-Dist: twine ; 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: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: typing; extra == "dev"
+Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: twine; extra == "dev"
 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: flake8 ; extra == 'tests'
-Requires-Dist: mypy ; extra == 'tests'
-Requires-Dist: pylint ; extra == 'tests'
-Requires-Dist: pytest ; extra == 'tests'
-Requires-Dist: pytest-cov ; extra == 'tests'
-Requires-Dist: typing ; extra == 'tests'
-Requires-Dist: types-setuptools ; extra == 'tests'
-Requires-Dist: wheel ; extra == 'tests'
-Requires-Dist: twine ; extra == 'tests'
+Requires-Dist: anybadge; extra == "tests"
+Requires-Dist: coverage-badge; 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"
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: typing; extra == "tests"
+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 aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.37
+# base 0.3.39
 
 [![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.36?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.36)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.38?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.38)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.37.
+>ae_base module 0.3.39.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

ae_base-0.3.39.dist-info/RECORD

@@ -0,0 +1,7 @@
+ae/base.py,sha256=aA_qa4s-17EzXKjN9wwfya688eGnFNJP0EglSLeYJjw,55182
+ae_base-0.3.39.dist-info/LICENSE.md,sha256=3X7IwvwQFt4PqRHb7mV8qoJjQ1E-HmcGioyT4Y6-6c8,35002
+ae_base-0.3.39.dist-info/METADATA,sha256=YPZbM4qKqfaO-3WvDLvV77O9WNWOfxg6uxhkO7nu0vA,5219
+ae_base-0.3.39.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+ae_base-0.3.39.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
+ae_base-0.3.39.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ae_base-0.3.39.dist-info/RECORD,,

{ae_base-0.3.37.dist-info → ae_base-0.3.39.dist-info}/WHEEL

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

ae_base-0.3.37.dist-info/RECORD

@@ -1,7 +0,0 @@
-ae/base.py,sha256=Jb4C0-uyu40_vK0dQZnHHR2hTwDILzaGpS7ecp-0BQs,52008
-ae_base-0.3.37.dist-info/LICENSE.md,sha256=3X7IwvwQFt4PqRHb7mV8qoJjQ1E-HmcGioyT4Y6-6c8,35002
-ae_base-0.3.37.dist-info/METADATA,sha256=2wTlS7GMWnV1vuGdsuMb1z_KWr-y2KwUsLcesuWYVMw,5245
-ae_base-0.3.37.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-ae_base-0.3.37.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
-ae_base-0.3.37.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-ae_base-0.3.37.dist-info/RECORD,,