ae-base 0.3.40__py3-none-any.whl → 0.3.42__py3-none-any.whl

ae/base.py

@@ -31,6 +31,9 @@ sortable and compact string from a timestamp.
 base helper functions
 ---------------------
 
+:func:`now_str` creates a timestamp string with the actual UTC date and time. the :func:`utc_datetime` provides the
+actual UTC date and time as datetime object.
+
 to write more compact and readable code for the most common file I/O operations, the helper functions :func:`read_file`
 and :func:`write_file` are wrapping Python's built-in :func:`open` function and its context manager.
 
@@ -43,6 +46,9 @@ the function :func:`duplicates` returns the duplicates of an iterable type.
 to normalize a file path, in order to remove `.`, `..` placeholders, to resolve symbolic links or to make it relative or
 absolute, call the function :func:`norm_path`.
 
+:func:`uri2filename` converts special characters of a URI/URL resulting in a string that can be used as a file name.
+use the function :func:`filename2uri` to convert this string back to the corresponding URL/URI.
+
 :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.
@@ -137,6 +143,13 @@ to determine e.g. variable values of the callers of a function/method.
     :attr:`title <AppBase.app_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 :func:`full_stack_trace`.
+
+
+os.path shortcuts
+-----------------
+
+the following data items are pointers to shortcut the lookup to their related functions in the
+Python module :mod:`os.path`:
 """
 import datetime
 import getpass
@@ -160,7 +173,21 @@ from types import ModuleType
 from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Tuple, Union, cast
 
 
-__version__ = '0.3.40'
+__version__ = '0.3.42'
+
+
+os_path_abspath = os.path.abspath
+os_path_basename = os.path.basename
+os_path_dirname = os.path.dirname
+os_path_expanduser = os.path.expanduser
+os_path_isdir = os.path.isdir
+os_path_isfile = os.path.isfile
+os_path_join = os.path.join
+os_path_normpath = os.path.normpath
+os_path_realpath = os.path.realpath
+os_path_relpath = os.path.relpath
+os_path_sep = os.path.sep
+os_path_splitext = os.path.splitext
 
 
 DOCS_FOLDER = 'docs'                            #: project documentation root folder name
@@ -250,10 +277,10 @@ def app_name_guess() -> str:
     if not app_name:
         unspecified_app_names = ('ae_base', 'app', '_jb_pytest_runner', 'main', '__main__', 'pydevconsole', 'src')
         path = sys.argv[0]
-        app_name = os.path.splitext(os.path.basename(path))[0]
+        app_name = os_path_splitext(os_path_basename(path))[0]
         if app_name.lower() in unspecified_app_names:
             path = os.getcwd()
-            app_name = os.path.basename(path)
+            app_name = os_path_basename(path)
             if app_name.lower() in unspecified_app_names:
                 app_name = "unguessable"
     return app_name
@@ -267,7 +294,7 @@ def build_config_variable_values(*names_defaults: Tuple[str, Any], section: str
     :return:                    tuple of build config variable values (using the passed default value if not specified
                                 in the :data:`BUILD_CONFIG_FILE` spec file or if the spec file does not exist in cwd).
     """
-    if not os.path.exists(BUILD_CONFIG_FILE):
+    if not os_path_isfile(BUILD_CONFIG_FILE):
         return tuple(def_val for name, def_val in names_defaults)
 
     config = instantiate_config_parser()
@@ -352,6 +379,17 @@ def env_str(name: str, convert_name: bool = False) -> Optional[str]:
     return os.environ.get(name)
 
 
+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.
+
+    .. hint:: to ensure proper conversion the specified file name has to be created by :func:`uri2filename`.
+    """
+    return urllib.parse.unquote(file_name)
+
+
 def force_encoding(text: Union[str, bytes], encoding: str = DEF_ENCODING, errors: str = DEF_ENCODE_ERRORS) -> str:
     """ force/ensure the encoding of text (str or bytes) without any UnicodeDecodeError/UnicodeEncodeError.
 
@@ -400,8 +438,8 @@ def import_module(import_name: str, path: Optional[Union[str, UnsetType]] = UNSE
     :return:                    a reference to the loaded module or ``None`` if module could not be imported.
     """
     if path is UNSET:
-        path = import_name.replace('.', os.path.sep)
-        path += PY_EXT if os.path.isfile(path + PY_EXT) else os.path.sep + PY_INIT
+        path = import_name.replace('.', os_path_sep)
+        path += PY_EXT if os_path_isfile(path + PY_EXT) else os_path_sep + PY_INIT
     mod_ref = None
 
     spec = importlib.util.spec_from_file_location(import_name, path)    # type: ignore # silly mypy
@@ -452,7 +490,7 @@ def load_dotenvs():
     """
     load_env_var_defaults(os.getcwd())
     if file_name := stack_var('__file__'):
-        load_env_var_defaults(os.path.dirname(os.path.abspath(file_name)))
+        load_env_var_defaults(os_path_dirname(os_path_abspath(file_name)))
 
 
 def load_env_var_defaults(start_dir: str):
@@ -468,18 +506,18 @@ def load_env_var_defaults(start_dir: str):
         only variables that are not declared in :data:`os.environ` will be added (with the
         value specified in the ``.env`` file to be loaded).
     """
-    file_path = os.path.abspath(os.path.join(start_dir, DOTENV_FILE_NAME))
-    if not os.path.isfile(file_path):
-        file_path = os.path.join(os.path.dirname(start_dir), DOTENV_FILE_NAME)
+    file_path = os_path_abspath(os_path_join(start_dir, DOTENV_FILE_NAME))
+    if not os_path_isfile(file_path):
+        file_path = os_path_join(os_path_dirname(start_dir), DOTENV_FILE_NAME)
 
-    while os.path.isfile(file_path):
+    while os_path_isfile(file_path):
         for var_nam, var_val in parse_dotenv(file_path).items():
             if var_nam not in os.environ:
                 os.environ[var_nam] = var_val
 
         if os.sep not in file_path:
             break           # pragma: no cover # prevent endless-loop for ``.env`` file in root dir (os.sep == '/')
-        file_path = os.path.join(os.path.dirname(os.path.dirname(file_path)), DOTENV_FILE_NAME)
+        file_path = os_path_join(os_path_dirname(os_path_dirname(file_path)), DOTENV_FILE_NAME)
 
 
 def main_file_paths_parts(portion_name: str) -> Tuple[Tuple[str, ...], ...]:
@@ -603,20 +641,20 @@ def norm_path(path: str, make_absolute: bool = True, remove_base_path: str = "",
     """
     path = path or "."
     if path[0] == "~":
-        path = os.path.expanduser(path)
+        path = os_path_expanduser(path)
 
     if remove_dots:
-        path = os.path.normpath(path)
+        path = os_path_normpath(path)
 
     if resolve_sym_links:
-        path = os.path.realpath(path)
+        path = os_path_realpath(path)
     elif make_absolute:
-        path = os.path.abspath(path)
+        path = os_path_abspath(path)
 
     if remove_base_path:
         if remove_base_path[0] == "~":
-            remove_base_path = os.path.expanduser(remove_base_path)
-        path = os.path.relpath(path, remove_base_path)
+            remove_base_path = os_path_expanduser(remove_base_path)
+        path = os_path_relpath(path, remove_base_path)
 
     return path
 
@@ -628,10 +666,7 @@ def now_str(sep: str = "") -> str:
                                 the seconds from the microseconds).
     :return:                    naive UTC timestamp (without timezone info) as string (length=20 + 3 * len(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))
+    return utc_datetime().strftime(NOW_STR_FORMAT.format(sep=sep))
 
 
 def os_host_name() -> str:
@@ -754,23 +789,22 @@ def project_main_file(import_name: str, project_path: str = "") -> str:
                                 sister project (under the same project parent folder).
     :return:                    absolute file path/name of main module or empty string if no main/version file found.
     """
-    join = os.path.join
     *namespace_dirs, portion_name = import_name.split('.')
     project_name = ('_'.join(namespace_dirs) + '_' if namespace_dirs else "") + portion_name
     paths_parts = main_file_paths_parts(portion_name)
 
     project_path = norm_path(project_path)
     module_paths = []
-    if os.path.basename(project_path) != project_name:
-        module_paths.append(join(os.path.dirname(project_path), project_name, *namespace_dirs))
+    if os_path_basename(project_path) != project_name:
+        module_paths.append(os_path_join(os_path_dirname(project_path), project_name, *namespace_dirs))
     if namespace_dirs:
-        module_paths.append(join(project_path, *namespace_dirs))
+        module_paths.append(os_path_join(project_path, *namespace_dirs))
     module_paths.append(project_path)
 
     for module_path in module_paths:
         for path_parts in paths_parts:
-            main_file = join(module_path, *path_parts)
-            if os.path.isfile(main_file):
+            main_file = os_path_join(module_path, *path_parts)
+            if os_path_isfile(main_file):
                 return main_file
     return ""
 
@@ -885,7 +919,7 @@ def stack_vars(*skip_modules: str,
     :param max_depth:           the maximum depth in the call stack from which to return the variables. if the specified
                                 argument is not zero and no :paramref:`~stack_vars.skip_modules` are specified then the
                                 first deeper stack frame that is not within the default :data:`SKIPPED_MODULES` will be
-                                returned. if this argument and :paramref:`~stack_var.find_name` get not passed then the
+                                returned. if this argument and :paramref:`~stack_vars.find_name` get not passed then the
                                 variables of the top stack frame will be returned.
     :return:                    tuple of the global and local variable dicts and the depth in the call stack.
     """
@@ -986,33 +1020,38 @@ def uri2filename(uri: str) -> str:
 
     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.
+
+    .. hint:: use :func:`filename2uri` to convert the resulting file name back to the corresponding URO
     """
     # 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
+def utc_datetime() -> datetime.datetime:
+    """ return the current UTC timestamp as string (to use as suffix for file and variable/attribute names).
 
-    :param file_name:           name of the file/folder to convert back to its URI representation.
-    :return:                    URI string.
+    :return:                    timestamp string of the actual UTC date and time.
     """
-    return urllib.parse.unquote(file_name)
+    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):
     """ (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!).
-    :param content:             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).
-    :param extra_mode:          open mode flag characters. passed unchanged to the `mode` argument of :func:`open` if
-                                this argument starts with 'a', else this argument value will be appended to 'w'.
+    :param content:             new file content passed either as string or bytes array. if a bytes array get passed
+                                then this method will automatically write the content as binary.
+    :param extra_mode:          additional open mode flag characters. passed to the `mode` argument of :func:`open` if
+                                this argument starts with 'a' or 'w', else this argument value will be appended to 'w'
+                                before it get passed to the `mode` argument of :func:`open`.
+                                if the :paramref:`~write_file.content` is a bytes array, then a 'b' character will
+                                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.
     :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:`~read_file.file_path` is misspelled or contains invalid characters.
+    :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.
 
@@ -1025,7 +1064,13 @@ def write_file(file_path: str, content: Union[str, bytes], extra_mode: str = "",
     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:
+    if isinstance(content, bytes) and 'b' not in extra_mode:
+        extra_mode += 'b'
+
+    if extra_mode == '' or extra_mode[0] not in ('a', 'w'):
+        extra_mode = 'w' + extra_mode
+
+    with open(file_path, mode=extra_mode, encoding=encoding) as file_handle:
         file_handle.write(content)
 
 
@@ -1054,16 +1099,16 @@ class ErrorMsgMixin:
 PACKAGE_NAME = stack_var('__name__') or 'unspecified_package'
 PACKAGE_DOMAIN = 'org.test'
 PERMISSIONS = "INTERNET, VIBRATE, READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE"
-if os.path.exists(BUILD_CONFIG_FILE):                           # pragma: no cover
+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]
+    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')
 
 

{ae_base-0.3.40.dist-info → ae_base-0.3.42.dist-info}/LICENSE.md

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

{ae_base-0.3.40.dist-info → ae_base-0.3.42.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.40
+Version: 0.3.42
 Summary: ae namespace module portion base: basic constants, helper functions and context manager
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -32,6 +32,7 @@ Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pylint; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-django; extra == "dev"
 Requires-Dist: typing; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
@@ -46,6 +47,7 @@ Requires-Dist: mypy; extra == "tests"
 Requires-Dist: pylint; extra == "tests"
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-django; extra == "tests"
 Requires-Dist: typing; extra == "tests"
 Requires-Dist: types-setuptools; extra == "tests"
 Requires-Dist: wheel; extra == "tests"
@@ -53,17 +55,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.40
+# base 0.3.42
 
 [![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.39?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.39)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.41?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.41)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.40.
+>ae_base module 0.3.42.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

ae_base-0.3.42.dist-info/RECORD

@@ -0,0 +1,7 @@
+ae/base.py,sha256=cvkGRht-0pQXaokHocJ0h6P5mZOpkUR3JjG357rxyJU,57805
+ae_base-0.3.42.dist-info/LICENSE.md,sha256=eHVr16LWo8bsm2NbdFOBcQp-F_3MUXo9I922sABpsMQ,35002
+ae_base-0.3.42.dist-info/METADATA,sha256=ceQT7h6abqzZYIuaNnIY3EREiZ8rOlpR4qFiX-bn2EI,5311
+ae_base-0.3.42.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+ae_base-0.3.42.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
+ae_base-0.3.42.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ae_base-0.3.42.dist-info/RECORD,,

{ae_base-0.3.40.dist-info → ae_base-0.3.42.dist-info}/WHEEL

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

ae_base-0.3.40.dist-info/RECORD

@@ -1,7 +0,0 @@
-ae/base.py,sha256=-_eBIIgBgO1opcu_GlqDB1qQOU0qzuUvKUd1YM0hT5c,55971
-ae_base-0.3.40.dist-info/LICENSE.md,sha256=3X7IwvwQFt4PqRHb7mV8qoJjQ1E-HmcGioyT4Y6-6c8,35002
-ae_base-0.3.40.dist-info/METADATA,sha256=Mvak-VG2CUOXlP0lNF5wi2UuQSSkdPm8WdS5FsUwL5g,5219
-ae_base-0.3.40.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-ae_base-0.3.40.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
-ae_base-0.3.40.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-ae_base-0.3.40.dist-info/RECORD,,