ae-base 0.3.68__tar.gz → 0.3.70__tar.gz

{ae_base-0.3.68 → ae_base-0.3.70}/LICENSE.md

@@ -1,4 +1,4 @@
-<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.project_tpls v0.3.55 -->
+<!-- THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.project_tpls v0.3.56 -->
 ### GNU GENERAL PUBLIC LICENSE
 
 Version 3, 29 June 2007

{ae_base-0.3.68/ae_base.egg-info → ae_base-0.3.70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ae_base
-Version: 0.3.68
+Version: 0.3.70
 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.68
+<!-- 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.70
 
 [![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.67?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.67)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.70?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.70)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 

{ae_base-0.3.68 → ae_base-0.3.70}/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.68
+<!-- 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.70
 
 [![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.67?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.67)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.70?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.70)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 

{ae_base-0.3.68 → ae_base-0.3.70}/ae/base.py

@@ -42,7 +42,7 @@ inspect the operating system and manage environment variables.
     :func:`~ae.core.start_app_service` and :func:`~ae.core.request_app_permissions`.
 
 OS information
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 * :data:`os_platform`: a string identifying the operating system (e.g., 'linux', 'win32', 'android', 'ios').
 * :data:`os_device_id`: a string with the ID/name of the device.
@@ -53,7 +53,7 @@ OS information
 * :func:`sys_env_text`: compiles a formatted text block with system environment information, useful for logging.
 
 environment variables & `.env` files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * :func:`env_str`: retrieves the string value of an OS environment variable, with an option to automatically convert the
   variable name to the conventional format.
@@ -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.
 
 
@@ -124,18 +124,18 @@ general utilities & helpers
 a collection of miscellaneous mathematical, date/time, and other standalone helper functions.
 
 mathematical
-~~~~~~~~~~~~
+^^^^^^^^^^^^
 
 * :func:`sign`: returns the sign of a number (-1 for negative, 0 for zero, 1 for positive).
 * :func:`round_traditional`: rounds a float value using traditional rounding rules (e.g., `0.5` rounds up).
 
 date & time
-~~~~~~~~~~~
+^^^^^^^^^^^
 * :func:`utc_datetime`: Returns the current date and time as a timezone-naive `datetime` object in UTC.
 * :func:`now_str`: creates a compact, sortable timestamp string from the current UTC time.
 
 miscellaneous
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 * :func:`dummy_function`: a null function that accepts any arguments and returns `None`.
 
 
@@ -158,7 +158,7 @@ base constants
 predefined constants for project structure, file conventions, and default settings.
 
 project & file structure
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 * :data:`DOCS_FOLDER`: default name for a project's documentation folder ('docs').
 * :data:`TESTS_FOLDER`: default name for a project's tests folder ('tests').
@@ -176,7 +176,7 @@ project & file structure
   :mod:`ae.updater` and :mod:`aedev.project_manager`)
 
 formats & default settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * :data:`DATE_ISO`: ISO format string for dates ("%Y-%m-%d").
 * :data:`DATE_TIME_ISO`: ISO format string for :mod:`datetime.datetime` dates ("%Y-%m-%d %H:%M:%S.%f").
@@ -200,7 +200,7 @@ simplify file system interactions with wrappers and context managers.
 * :func:`in_wd`: a context manager that temporarily switches the current working directory.
 
 os.path shortcuts
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 the following are direct references to functions in the :mod:`os.path` module for convenient and quicker access:
 
@@ -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.68'
+__version__ = '0.3.70'
 
 
 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=}"
 

{ae_base-0.3.68 → ae_base-0.3.70/ae_base.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ae_base
-Version: 0.3.68
+Version: 0.3.70
 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.68
+<!-- 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.70
 
 [![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.67?logo=python)](
-    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.67)
+    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.70?logo=python)](
+    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.70)
 [![PyPIVersions](https://img.shields.io/pypi/v/ae_base)](
     https://pypi.org/project/ae-base/#history)
 

{ae_base-0.3.68 → ae_base-0.3.70}/pyproject.toml

@@ -1,4 +1,4 @@
-# THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.project_tpls v0.3.55
+# THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.project_tpls v0.3.56
 [build-system]
 requires = ["setuptools>=42", "wheel"]
 build-backend = "setuptools.build_meta"

{ae_base-0.3.68 → ae_base-0.3.70}/setup.py

@@ -1,4 +1,4 @@
-# THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.project_tpls v0.3.55
+# THIS FILE IS EXCLUSIVELY MAINTAINED by the project aedev.project_tpls v0.3.56
 """ setup of ae namespace module portion base: basic constants, helper functions and context managers. """
 # noinspection PyUnresolvedReferences
 import sys
@@ -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.68\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.70\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.67?logo=python)](\n'
- '    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.67)\n'
+ '    https://img.shields.io/gitlab/pipeline/ae-group/ae_base/release0.3.70?logo=python)](\n'
+ '    https://gitlab.com/ae-group/ae_base/-/tree/release0.3.70)\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.68',
+    'version': '0.3.70',
     'zip_safe': True,
 }
 

{ae_base-0.3.68 → ae_base-0.3.70}/tests/test_base.py

@@ -1,6 +1,8 @@
 """ ae.base unit tests """
 import datetime
 import os
+import time
+
 import pytest
 import shutil
 import socket
@@ -1072,18 +1074,25 @@ class TestBaseHelpers:
 
         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("")
+        retries = 9
+        while True:
+            err_msg = url_failure(f"https://httpbin.org/status/200")
+            if not err_msg or retries == 0:
+                break
+            time.sleep(3)
+            retries -= 1
+        assert not err_msg, f"httpbin is sometimes unavailable with error 503 - retry later; {err_msg=}"
 
+    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 +1100,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 +1208,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 = url_failure(f"https://httpbin.org/delay/3", timeout=0.9)
+
+        assert ret
+        assert int(ret[:3]) > 0
+
+    def test_url_failure_url_errors(self):
+        assert url_failure("")
+
+        ret = url_failure(url2 := f"https://httpbin.org/status/504")
+
+        assert ret
+        assert int(ret[:3]) == 504
+        assert ret[4:].startswith(mask_url(url2))
+
+        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)