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

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,10 +24,16 @@ 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
 ---------------------
 
+: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.
 
@@ -40,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.
@@ -99,6 +108,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
 -----------------------
 
@@ -148,7 +166,7 @@ from types import ModuleType
 from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Tuple, Union, cast
 
 
-__version__ = '0.3.39'
+__version__ = '0.3.41'
 
 
 DOCS_FOLDER = 'docs'                            #: project documentation root folder name
@@ -202,7 +220,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',
@@ -338,6 +358,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.
 
@@ -612,9 +643,9 @@ 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))
+    return utc_datetime().strftime(NOW_STR_FORMAT.format(sep=sep))
 
 
 def os_host_name() -> str:
@@ -969,19 +1000,20 @@ 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):

{ae_base-0.3.39.dist-info → ae_base-0.3.41.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.39.dist-info → ae_base-0.3.41.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.39
+Version: 0.3.41
 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.39
+# base 0.3.41
 
 [![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.38?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.38)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.40?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.40)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.39.
+>ae_base module 0.3.41.
 
 [![Coverage](https://ae-group.gitlab.io/ae_base/coverage.svg)](
     https://ae-group.gitlab.io/ae_base/coverage/index.html)

ae_base-0.3.41.dist-info/RECORD

@@ -0,0 +1,7 @@
+ae/base.py,sha256=9qixFzNhWVcGztz9Y7zv7vsQL485LEXH-IsfF61yo_M,56696
+ae_base-0.3.41.dist-info/LICENSE.md,sha256=eHVr16LWo8bsm2NbdFOBcQp-F_3MUXo9I922sABpsMQ,35002
+ae_base-0.3.41.dist-info/METADATA,sha256=pr0WsX0BOV067Vj5cxyfuWPNtr0rTHURIlRoacPaZe0,5311
+ae_base-0.3.41.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+ae_base-0.3.41.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
+ae_base-0.3.41.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ae_base-0.3.41.dist-info/RECORD,,

{ae_base-0.3.39.dist-info → ae_base-0.3.41.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.39.dist-info/RECORD

@@ -1,7 +0,0 @@
-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,,