ae-base 0.3.68__py3-none-any.whl → 0.3.70__py3-none-any.whl

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.dist-info → ae_base-0.3.70.dist-info}/METADATA

@@ -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.70.dist-info/RECORD

@@ -0,0 +1,7 @@
+ae/base.py,sha256=hIgo28nJJr6rMV-KLvnfiAREF0wZx5EhQgnGhOANAJs,78705
+ae_base-0.3.70.dist-info/licenses/LICENSE.md,sha256=0g3tHWG2bfmLGyuM0e0YzSXT8As8eN1b0VQIqXMWTMg,35003
+ae_base-0.3.70.dist-info/METADATA,sha256=HjSggbiVRRnU89mVsTmMUlizZtKTNkxfYz6mo7qVspM,5470
+ae_base-0.3.70.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ae_base-0.3.70.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
+ae_base-0.3.70.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ae_base-0.3.70.dist-info/RECORD,,

{ae_base-0.3.68.dist-info → ae_base-0.3.70.dist-info}/licenses/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.dist-info/RECORD

@@ -1,7 +0,0 @@
-ae/base.py,sha256=B4qkfPNmuDeyFCLY7t2QbDtCv2uFpE8novuc8UTgh7M,77075
-ae_base-0.3.68.dist-info/licenses/LICENSE.md,sha256=K2nZMCD-VuxJiIVGUFsN_TSl68W3biSTBew0_9jOUXc,35003
-ae_base-0.3.68.dist-info/METADATA,sha256=kQkdHTEjrkMJJgBCyls3hAJL4w2OKOagFbZf3V7sK2A,5469
-ae_base-0.3.68.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ae_base-0.3.68.dist-info/top_level.txt,sha256=vUdgAslSmhZLXWU48fm8AG2BjVnkOWLco8rzuW-5zY0,3
-ae_base-0.3.68.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-ae_base-0.3.68.dist-info/RECORD,,