ae-base 0.3.42__tar.gz → 0.3.44__tar.gz

{ae_base-0.3.42/ae_base.egg-info → ae_base-0.3.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.42
+Version: 0.3.44
 Summary: ae namespace module portion base: basic constants, helper functions and context manager
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -55,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.42
+# base 0.3.44
 
 [![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.41?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.41)
+    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)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.42.
+>ae_base module 0.3.44.
 
 [![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 → ae_base-0.3.44}/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.42
+# base 0.3.44
 
 [![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.41?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.41)
+    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)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.42.
+>ae_base module 0.3.44.
 
 [![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 → ae_base-0.3.44}/ae/base.py

@@ -46,8 +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:`defuse` converts special characters of a URI/URL or a file path string, resulting in a string that can be used
+either as a URL slug or as a file name. use the function :func:`dedefuse` to convert this string back to the
+corresponding URL/URI or file path.
 
 :func:`camel_to_snake` and :func:`snake_to_camel` providing name conversions of class and method names.
 
@@ -162,7 +163,6 @@ import shutil
 import socket
 import sys
 import unicodedata
-import urllib.parse
 import warnings
 
 from configparser import ConfigParser, ExtendedInterpolation
@@ -173,7 +173,7 @@ from types import ModuleType
 from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Tuple, Union, cast
 
 
-__version__ = '0.3.42'
+__version__ = '0.3.44'
 
 
 os_path_abspath = os.path.abspath
@@ -336,6 +336,96 @@ def deep_dict_update(data: dict, update: dict):
             data[upd_key] = upd_val
 
 
+URI_SEP_CHAR = '⫻'  # U+2AFB: TRIPLE SOLIDUS BINARY RELATION
+ASCII_UNICODE = (
+    ('/', '⁄'),     # U+2044: Fraction Slash; '∕' U+2215: Division Slash; '⧸' U+29F8: Big Solidus
+                    # ; '╱' U+FF0F: Fullwidth Solidus; '╱' U+2571: Box Drawings Light Diagonal Upper Right to Lower Left
+    ('|', '।'),     # U+0964: Devanagari Danda
+    ('\\', '﹨'),    # U+FE68: SMALL REVERSE SOLIDUS; '⑊' U+244A OCR DOUBLE BACKSLASH; '⧵' U+29F5 REV. SOLIDUS OPERATOR
+    (':', '﹕'),     # U+FE55: Small Colon
+    ('*', '﹡'),     # U+FE61: Small Asterisk
+    ('?', '﹖'),     # U+FE56: Small Question Mark
+    ('"', '＂'),     # U+FF02: Fullwidth Quotation Mark
+    ("'", '‘'),     # U+2018: Left Single; '’' U+2019: Right Single; '‛' U+201B: Single High-Reversed-9 Quotation Mark
+    ('<', '⟨'),     # U+27E8: LEFT ANGLE BRACKET; '‹' U+2039: Single Left-Pointing Angle Quotation Mark
+    ('>', '⟩'),     # U+27E9: RIGHT ANGLE BRACKET; '›' U+203A: Single Right-Pointing Angle Quotation Mark
+    ('(', '⟮'),     # U+27EE: MATHEMATICAL LEFT FLATTENED PARENTHESIS
+    (')', '⟯'),     # U+27EF: MATHEMATICAL RIGHT FLATTENED PARENTHESIS
+    ('[', '⟦'),     # U+27E6: MATHEMATICAL LEFT WHITE SQUARE BRACKET
+    (']', '⟧'),     # U+27E7: MATHEMATICAL RIGHT WHITE SQUARE BRACKET
+    ('#', '﹟'),     # U+FE5F: Small Number Sign
+    (';', '﹔'),     # U+FE54: Small Semicolon
+    ('@', '﹫'),     # U+FE6B: Small Commercial At
+    ('&', '﹠'),     # U+FE60: Small Ampersand
+    ('=', '﹦'),     # U+FE66: Small Equals Sign
+    ('+', '﹢'),     # U+FE62: Small Plus Sign
+    ('$', '﹩'),     # U+FE69: Small Dollar Sign
+    ('%', '﹪'),     # 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)
+    (chr(127), '␡'),  # U+2421: DELETE SYMBOL
+    # ('_', '𛲖'),     # U+1BC96: Duployan Affix Low Line; '＿' U+FF3F Fullwidth Low Line
+)
+""" transformation table of special ASCII to Unicode alternative character,
+see https://www.compart.com/en/unicode/category/Po and https://xahlee.info/comp/unicode_naming_slash.html (http!) """
+
+ASCII_TO_UNICODE = dict(ASCII_UNICODE)  #: map to convert ASCII to an alternative defused Unicode character
+UNICODE_TO_ASCII = {unicode_char: ascii_char for ascii_char, unicode_char in ASCII_UNICODE}     #: Unicode to ASCII map
+
+
+def dedefuse(value: str) -> str:
+    """ convert a string that got defused with :func:`defuse` back to its original form.
+
+    :param value:               string defused with the function :func:`defuse`.
+    :return:                    re-activated form of the string (with all ASCII special characters recovered).
+    """
+    original = ""
+    for char in value:
+        if char in UNICODE_TO_ASCII:
+            char = UNICODE_TO_ASCII[char]
+        elif 0x2400 <= (code := ord(char)) <= 0x241F:
+            char = chr(code - 0x2400)
+        original += char
+
+    return original.replace(URI_SEP_CHAR, '://')
+
+
+def defuse(value: str) -> str:
+    """ convert a file path or a URI into a defused/presentational form to be usable as URL slug or file/folder name.
+
+    :param value:               any string to defuse (replace special chars with Unicode alternatives).
+    :return:                    string with its special characters replaced by its pure presentational alternatives.
+
+    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 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
+    and of Christopher Oezbek on https://stackoverflow.com/questions/1976007.
+
+    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.
+
+    """
+    defused = ""
+    value = value.replace('://', URI_SEP_CHAR)  # make URIs shorter
+    for char in value:
+        if char in ASCII_TO_UNICODE:
+            char = ASCII_TO_UNICODE[char]
+        elif (code := ord(char)) <= 31:
+            char = chr(0x2400 + code)
+        defused += char
+    return defused
+
+
 def dummy_function(*_args, **_kwargs):
     """ null function accepting any arguments and returning None.
 
@@ -379,17 +469,6 @@ 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.
 
@@ -1005,29 +1084,6 @@ 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.
-
-    .. 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 utc_datetime() -> datetime.datetime:
     """ return the current UTC timestamp as string (to use as suffix for file and variable/attribute names).
 

{ae_base-0.3.42 → ae_base-0.3.44/ae_base.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ae_base
-Version: 0.3.42
+Version: 0.3.44
 Summary: ae namespace module portion base: basic constants, helper functions and context manager
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -55,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.42
+# base 0.3.44
 
 [![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.41?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.41)
+    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)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 
->ae_base module 0.3.42.
+>ae_base module 0.3.44.
 
 [![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 → ae_base-0.3.44}/tests/test_base.py

@@ -1,6 +1,7 @@
 """ ae.base unit tests """
 import datetime
 import os
+import string
 import tempfile
 
 import pytest
@@ -15,17 +16,21 @@ from typing import cast
 
 # noinspection PyProtectedMember
 from ae.base import (
-    BUILD_CONFIG_FILE, DOTENV_FILE_NAME, PY_EXT, PY_INIT, PY_MAIN, TESTS_FOLDER, UNSET,
-    app_name_guess, build_config_variable_values, camel_to_snake, deep_dict_update, dummy_function, duplicates, env_str,
-    filename2uri, force_encoding, full_stack_trace, import_module, instantiate_config_parser, in_wd,
+    ASCII_TO_UNICODE, BUILD_CONFIG_FILE, DOTENV_FILE_NAME, PY_EXT, PY_INIT, PY_MAIN, TESTS_FOLDER, UNICODE_TO_ASCII,
+    UNSET,
+    URI_SEP_CHAR, app_name_guess, build_config_variable_values, camel_to_snake, deep_dict_update, dummy_function,
+    duplicates, env_str,
+    dedefuse, force_encoding, full_stack_trace, import_module, instantiate_config_parser, in_wd,
     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, uri2filename, utc_datetime, write_file, ErrorMsgMixin)
+    sys_env_dict, sys_env_text, to_ascii, defuse, utc_datetime, 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"
+tst_uri1 = "schema://user:pwd@domain/path_root/path_sub\\path+file% Üml?ä|ït.path_ext*\"<>|*'()[]{}#^;&=$,~" + chr(127)
+tst_fna1 = "schema⫻user﹕pwd﹫domain⁄path_root⁄path_sub﹨path﹢file﹪　Üml﹖ä।ït.path_ext﹡＂⟨⟩।﹡‘⟮⟯⟦⟧{}﹟＾﹔﹠﹦﹩﹐~␡"
+tst_uri2 = "test control chars" + "".join(chr(_) for _ in range(1, 32))
+tst_fna2 = "test\u3000control\u3000chars␁␂␃␄␅␆␇␈␉␊␋␌␍␎␏␐␑␒␓␔␕␖␗␘␙␚␛␜␝␞␟"
 
 env_var_name = 'env_var_nam1'
 env_var_val = 'value of env var'
@@ -171,6 +176,44 @@ class TestBaseHelpers:
         assert pev['setup_kwargs']['entry_points']['console_scripts'] == lst_val
         assert pev['setup_kwargs']['entry_points']['console_scripts'][0] == str_new
 
+    def test_dedefuse_file_name(self):
+        assert dedefuse(tst_fna1) == tst_uri1
+        assert dedefuse(tst_fna2) == tst_uri2
+
+        assert dedefuse(defuse(tst_uri1)) == tst_uri1
+        assert dedefuse(defuse(tst_uri2)) == tst_uri2
+
+    def test_defuse_file_name(self):
+        assert defuse(tst_uri1) == tst_fna1
+        assert defuse(tst_uri2) == tst_fna2
+
+        assert defuse(dedefuse(tst_fna1)) == tst_fna1
+        assert defuse(dedefuse(tst_fna2)) == tst_fna2
+
+    def test_defuse_os_file_name(self):
+        try:
+            write_file(tst_fna1, "tst uri file content1")
+            assert os.path.exists(tst_fna1)
+            write_file(tst_fna2, "tst uri file content2")
+            assert os.path.exists(tst_fna2)
+        finally:
+            if os.path.exists(tst_fna1):
+                os.remove(tst_fna1)
+            if os.path.exists(tst_fna2):
+                os.remove(tst_fna2)
+
+    def test_defuse_maps_integrity(self):
+        assert URI_SEP_CHAR not in UNICODE_TO_ASCII
+        assert len(UNICODE_TO_ASCII) == len(ASCII_TO_UNICODE)   # check for duplicates in the ASCII_UNICODE map
+
+    def test_defuse_maps_not_touching_chars_allowed_as_slug_and_filename(self):
+        assert '-' not in ASCII_TO_UNICODE
+        assert '_' not in ASCII_TO_UNICODE
+        assert '.' not in ASCII_TO_UNICODE
+        assert '~' not in ASCII_TO_UNICODE
+        for char in string.ascii_letters + string.digits:
+            assert char not in ASCII_TO_UNICODE
+
     def test_dummy_function(self):
         assert dummy_function() is None
         assert dummy_function(999, "any_args") is None
@@ -204,10 +247,6 @@ class TestBaseHelpers:
         os.environ['NON_ALPHA_NUM_CHARS_69'] = vv
         assert env_str(ev, convert_name=True) == vv
 
-    def test_filename2uri(self):
-        assert filename2uri(tst_fna1) == tst_uri1
-        assert uri2filename(filename2uri(tst_fna1)) == tst_fna1
-
     def test_force_encoding_bytes(self):
         s = 'äöü'
 
@@ -708,22 +747,11 @@ class TestBaseHelpers:
         assert to_ascii('ß') == 'ss'
         assert to_ascii('€') == 'Euro'
 
-    def test_uri2filename(self):
-        assert uri2filename(tst_uri1) == tst_fna1
-        assert filename2uri(uri2filename(tst_uri1)) == tst_uri1
-
     def test_utc_datetime(self):
         dt1 = utc_datetime()
         dt2 = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
         assert dt2 - dt1 < datetime.timedelta(seconds=1)
 
-    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"