ae-base 0.3.69__tar.gz → 0.3.71__tar.gz

{ae_base-0.3.69/ae_base.egg-info → ae_base-0.3.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ae_base
-Version: 0.3.69
+Version: 0.3.71
 Summary: ae namespace module portion base: basic constants, helper functions and context managers
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -63,15 +63,15 @@ Dynamic: provides-extra
 Dynamic: requires-python
 Dynamic: summary
 
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.96 -->
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.69
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.97 -->
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.namespace_root_tpls v0.3.19 -->
+# base 0.3.71
 
 [![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.68?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.68)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.71?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.71)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 

{ae_base-0.3.69 → ae_base-0.3.71}/README.md

@@ -1,12 +1,12 @@
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.96 -->
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.69
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.97 -->
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.namespace_root_tpls v0.3.19 -->
+# base 0.3.71
 
 [![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.68?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.68)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.71?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.71)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 

{ae_base-0.3.69 → ae_base-0.3.71}/ae/base.py

@@ -114,7 +114,7 @@ dynamically inspect modules, execution frames, and variables on the call stack.
 networking utilities
 --------------------
 
-* :func:`url_failure`: determines if and why a HTTP|FTP target is unavailable.
+* :func:`url_failure`: determines if and why an HTTP|FTP target is unavailable.
 * :func:`mask_url`: hides or replaces the password/token portion of a URL for safe logging.
 
 
@@ -218,6 +218,7 @@ the following are direct references to functions in the :mod:`os.path` module fo
 * :data:`os_path_splitext`: :func:`os.path.splitext`
 """
 # pylint: disable=too-many-lines
+import base64
 import datetime
 import getpass
 import importlib.abc
@@ -240,12 +241,12 @@ from importlib.machinery import ModuleSpec
 from inspect import getinnerframes, getouterframes, getsourcefile
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlparse, urlunparse
-from urllib.request import urlopen
+from urllib.request import Request, urlopen
 from types import ModuleType
 from typing import Any, Callable, Generator, Iterable, MutableMapping, Optional, Union, cast
 
 
-__version__ = '0.3.69'
+__version__ = '0.3.71'
 
 
 os_path_abspath = os.path.abspath
@@ -1316,18 +1317,44 @@ 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 url_failure(url: str, timeout: Optional[float] = None) -> str:  # pylint: disable=too-many-return-statements
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments,too-many-return-statements
+def url_failure(url: str, token: str = "", username: str = "", password: str = "", git_repo: bool = False,
+                timeout: Optional[float] = None) -> str:
     """ determine if and why an FTP or HTTP[S] target is not available via a GET request.
 
-    :param url:                 URL of an target|page|file to check (not downloaded, fetching only the header).
+    :param url:                 URL of a target|page|file to check (not downloaded, fetching only the header).
+    :param token:               optional bearer token to authenticate (only for HTTPS protocol).
+    :param username:            optional username to authenticate (for HTTPS, together with the password argument).
+    :param password:            optional password to authenticate (for HTTPS, together with the username argument).
+    :param git_repo:            optimized check for Git repository HTTP servers/sites (like GitHub, GitLab, Bitbucket,
+                                Gitea, SourceHut, Mercury, etc. as long as they implement Smart HTTP).
     :param timeout:             connection timeout in seconds (see :func:`urllib.request.urlopen`).
     :return:                    empty string if target header is available, else an error description. if an
                                 FTP|HTTP response error occurred then the error/status code
                                 will be returned in the first 3 characters.
+
+    .. note::
+        credentials for server authentication can be specified either (1) embedded into the specified url argument,
+        (2) as bearer token in the token argument or (3) via the username/password arguments. in all cases the
+        functino will remove these secrets from the returned error description string.
     """
+    if git_repo:
+        if not url.endswith(".git"):
+            url += ".git"
+        url += "/info/refs?service=git-upload-pack"
+
+    headers = {}
+    if token:
+        assert not username and not password, "url_failure accepts either a token or username/password, not both"
+        headers['Authorization'] = "Bearer " + token
+    elif username or password:
+        creds = f"{username}:{password}".encode('utf-8')
+        headers['Authorization'] = "Basic " + base64.b64encode(creds).decode('utf-8')
+
     # noinspection PyBroadException
     try:
-        with urlopen(url, timeout=timeout) as response:             # open connection and read header
+        request = Request(url, method='GET', headers=headers)
+        with urlopen(request, timeout=timeout) as response:         # open connection and only read the header
             status = response.getcode()                             # no need to call response.read()
             return "" if 200 <= status < 300 else f"{status} {mask_url(url)} {response.reason=}"
 
@@ -1335,17 +1362,20 @@ def url_failure(url: str, timeout: Optional[float] = None) -> str:  # pylint: di
         return f"{exception.code} {mask_url(url)} raised HTTPError {exception.reason=}"
 
     except URLError as exception:
-        err_prefix = f"996 {mask_url(url)} raised {exception.errno=} {exception.reason=};"
+        err_msg = f" {mask_url(url)} raised {exception.errno=} {exception.reason=};"
         if isinstance(exception.reason, socket.gaierror):
-            return f"{err_prefix} could not resolve hostname"
-        if isinstance(exception.reason, socket.timeout):
-            return f"{err_prefix} connection timed out after {timeout} seconds"
+            return '995' + f"{err_msg} could not resolve hostname"
         if isinstance(exception.reason, ssl.SSLCertVerificationError):
-            return f"{err_prefix} SSL certificate verification failed"
-        return f"{err_prefix} could not reach the server"
+            return '996' + f"{err_msg} SSL certificate verification failed"
+        if isinstance(exception.reason, socket.timeout):
+            return '997' + f"{err_msg} connection timed out after {timeout} seconds"
+        return '998' + f"{err_msg} could not reach the server"
+
+    except socket.timeout as _exception:    # noqa: F841 # str(_exception) could contain password|token
+        return '997' + f" {mask_url(url)} raised socket-timeout exception after {timeout} seconds"
 
-    except Exception:                                               # pylint: disable=broad-exception-caught
-        return f"999 {mask_url(url)} raised unexpected exception"   # NOT put str(_exception) because contains password
+    except Exception as _exception:         # noqa: F841 # pylint: disable=broad-exception-caught
+        return '999' + f" {mask_url(url)} raised unexpected exception"   # str(_exception) COULD contain password
 
 
 def utc_datetime() -> datetime.datetime:

{ae_base-0.3.69 → ae_base-0.3.71/ae_base.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ae_base
-Version: 0.3.69
+Version: 0.3.71
 Summary: ae namespace module portion base: basic constants, helper functions and context managers
 Home-page: https://gitlab.com/ae-group/ae_base
 Author: AndiEcker
@@ -63,15 +63,15 @@ Dynamic: provides-extra
 Dynamic: requires-python
 Dynamic: summary
 
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.96 -->
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->
-# base 0.3.69
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.97 -->
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.namespace_root_tpls v0.3.19 -->
+# base 0.3.71
 
 [![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.68?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.68)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.71?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.71)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 

{ae_base-0.3.69 → ae_base-0.3.71}/setup.py

@@ -23,15 +23,15 @@ setup_kwargs = {
     'install_requires': [],
     'keywords': ['configuration', 'development', 'environment', 'productivity'],
     'license': 'GPL-3.0-or-later',
-    'long_description': ('<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.96 -->\n'
- '<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.tpl_namespace_root V0.3.14 -->\n'
- '# base 0.3.69\n'
+    'long_description': ('<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project ae.ae v0.3.97 -->\n'
+ '<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.namespace_root_tpls v0.3.19 -->\n'
+ '# base 0.3.71\n'
  '\n'
  '[![GitLab develop](https://img.shields.io/gitlab/pipeline/ae-group/ae_base/develop?logo=python)](\n'
  '    https://gitlab.com/ae-group/ae_base)\n'
  '[![LatestPyPIrelease](\n'
- '    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.68?logo=python)](\n'
- '    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.68)\n'
+ '    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.71?logo=python)](\n'
+ '    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.71)\n'
  '[![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](\n'
  '    https://pypi.org/project/ae-base/#history)\n'
  '\n'
@@ -108,7 +108,7 @@ setup_kwargs = {
         'Source': 'https://ae.readthedocs.io/en/latest/_modules/ae/base.html'},
     'python_requires': '>=3.9',
     'url': 'https://gitlab.com/ae-group/ae_base',
-    'version': '0.3.69',
+    'version': '0.3.71',
     'zip_safe': True,
 }
 

{ae_base-0.3.69 → ae_base-0.3.71}/tests/test_base.py

@@ -1,7 +1,6 @@
 """ ae.base unit tests """
 import datetime
 import os
-import pytest
 import shutil
 import socket
 import ssl
@@ -9,16 +8,20 @@ import string
 import sys
 import tempfile
 import textwrap
+import time
+import timeit
 
 from collections import OrderedDict
 from configparser import ConfigParser
 # noinspection PyProtectedMember
 from http.client import HTTPMessage
 from types import ModuleType
-from typing import cast, Any
+from typing import cast, Any, Optional
 from unittest.mock import patch
 from urllib.error import HTTPError, URLError
 
+import pytest
+
 # noinspection PyProtectedMember
 from ae.base import (
     ASCII_TO_UNICODE, ASCII_UNICODE, BUILD_CONFIG_FILE, DOTENV_FILE_NAME, PY_EXT, PY_INIT, PY_MAIN, TESTS_FOLDER,
@@ -67,15 +70,32 @@ def os_env_test_env():
 module_test_var = 'module_test_var_val'   # used for stack_var()/try_exec() tests
 
 
-def test_unset_truthiness():
+def test_unset_truthiness_and_null_length():
     assert not UNSET
     assert bool(UNSET) is False
 
-
-def test_unset_null_length():
     assert len(UNSET) == 0
 
 
+def test_proof_os_path_shortcuts_performance_win():
+    att_call_setup = textwrap.dedent("""
+    import os
+    path1, path2, path3 = "folder1", "folder2", "file.tst"
+    """)
+    sho_call_setup = att_call_setup + textwrap.dedent("""
+    os_path_join = os.path.join
+    """)
+
+    att_call_code = "os.path.join(path1, path2, path3)"
+    sho_call_code = "os_path_join(path1, path2, path3)"
+
+    time_att = timeit.timeit(att_call_code, setup=att_call_setup, number=3_000_000)
+    time_sho = timeit.timeit(sho_call_code, setup=sho_call_setup, number=3_000_000)
+
+    assert time_sho < time_att
+    print(f"\n¡!¡!¡! os_path_* shortcuts are ~{((time_att - time_sho) / time_att) * 100:.2f}% faster")
+
+
 class TestErrorMsgMixin:
     def test_instantiation(self):
         ins = ErrorMsgMixin()
@@ -1067,23 +1087,35 @@ class TestBaseHelpers:
         assert to_ascii('ß') == 'ss'
         assert to_ascii('€') == 'Euro'
 
+    @staticmethod
+    def url_failure_httpbin_503_retryer(url: str, timeout: Optional[float] = None) -> tuple[str, str]:
+        retries = 9
+        while True:
+            err_msg = url_failure(url, timeout=timeout)
+            if not err_msg or int(err_msg[:3]) != 503 or retries == 0:
+                break
+            time.sleep(3)
+            retries -= 1
+        return err_msg, f"url_failure({url=}, {timeout=}) httpbin is sometimes unavailable/503. retry later; {err_msg=}"
+
     def test_url_failure(self):
         assert not url_failure("https://gitlab.com/ae-group/ae_base")
 
         assert not url_failure("https://gitlab.com/ae-group/ae_base.git")
 
-        assert not url_failure("https://www.google.com")
+        assert not url_failure("https://gitlab.com/ae-group/ae_base", git_repo=True)
 
-        assert not url_failure(f"https://httpbin.org/status/200")
+        assert not url_failure("https://www.google.com")
 
-    def test_url_failure_errors(self):
-        assert url_failure("")
+        ret, message = self.url_failure_httpbin_503_retryer("https://httpbin.org/status/200")
+        assert not ret, message
 
+    def test_url_failure_authentication_errors(self):
         password, domain, path = "toBeMaskedPassword", "any-not_existing-host_domain.zzz", "any/not/existing/url/path"
         url = f"https://username:{password}@{domain}/{path}"
         err_msg = "raised exception error message"
 
-        ret = url_failure(url)
+        ret = url_failure(url, token=password)
 
         assert ret
         assert int(ret[:3]) > 0
@@ -1091,24 +1123,21 @@ class TestBaseHelpers:
         assert domain in ret
         assert path in ret
 
-        ret = url_failure(url2 := f"https://httpbin.org/status/504")
-
-        assert ret
-        assert int(ret[:3]) == 504
-        assert ret[4:].startswith(mask_url(url2))
-
-        ret = url_failure(f"https://httpbin.org/delay/3", timeout=0.9)
+        ret = url_failure(url, username="any user name", password=password)
 
         assert ret
         assert int(ret[:3]) > 0
+        assert password not in ret
+        assert domain in ret
+        assert path in ret
 
-        ret = url_failure(f"https://expired.badssl.com")
+        ret = url_failure(url)
 
         assert ret
         assert int(ret[:3]) > 0
-
-        with pytest.raises(AttributeError):
-            url_failure(cast(str, 123456))
+        assert password not in ret
+        assert domain in ret
+        assert path in ret
 
         mocked_headers = cast(HTTPMessage, {})
 
@@ -1202,6 +1231,30 @@ class TestBaseHelpers:
         assert domain in ret
         assert path in ret
 
+    def test_url_failure_ssl_errors(self):
+        ret = url_failure(f"https://expired.badssl.com")
+
+        assert ret
+        assert int(ret[:3]) > 0
+
+    def test_url_failure_timeout_errors(self):
+        ret, message = self.url_failure_httpbin_503_retryer("https://httpbin.org/delay/3", timeout=0.9)
+
+        assert ret, message
+        assert ret[:3] == '997', message
+
+    def test_url_failure_url_errors(self):
+        assert url_failure("")
+
+        ret, message = self.url_failure_httpbin_503_retryer(url2 := "https://httpbin.org/status/504")
+
+        assert ret, message
+        assert ret[:3] == '504', message
+        assert ret[4:].startswith(mask_url(url2)), message
+
+        with pytest.raises(AttributeError):
+            url_failure(cast(str, 123456))
+
     def test_utc_datetime(self):
         dt1 = utc_datetime()
         dt2 = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)