pyutilities 2.4.2__tar.gz → 2.5.0__tar.gz

{pyutilities-2.4.2 → pyutilities-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyutilities
-Version: 2.4.2
+Version: 2.5.0
 Summary: PyUtilities :: Useful python 3+ utilities library for various use cases.
 License-Expression: MIT
 License-File: LICENSE
@@ -28,13 +28,13 @@ Requires-Dist: loguru (==0.7.3)
 Requires-Dist: markdown (>=3.7,<4.0)
 Requires-Dist: marshmallow (>=4.1,<5.0)
 Requires-Dist: openpyxl (==3.1.5)
-Requires-Dist: paramiko (==4.*)
+Requires-Dist: paramiko (==5.*)
 Requires-Dist: pendulum (>=3.2,<4.0)
 Requires-Dist: prettytable (>=3.14,<4.0)
 Requires-Dist: prettytable (>=3.17,<4.0)
 Requires-Dist: pydantic (>=2.12.5,<3.0.0)
 Requires-Dist: pydantic-settings (==2.*)
-Requires-Dist: pydantic-yaml (==1.*)
+Requires-Dist: pydantic-yaml (>=1.6,<2.0)
 Requires-Dist: pyfiglet (>=1.0,<2.0)
 Requires-Dist: python-dateutil (>=2.9,<3.0)
 Requires-Dist: python-dotenv (>=1.2,<2.0)
@@ -42,7 +42,7 @@ Requires-Dist: pytz (==2026.*)
 Requires-Dist: pyyaml (==6.*)
 Requires-Dist: requests (>=2.32,<3.0)
 Requires-Dist: rich-pyfiglet (>=1.0,<2.0)
-Requires-Dist: ruamel.yaml (==0.*)
+Requires-Dist: ruamel.yaml (==0.18.*)
 Requires-Dist: urllib3 (>=2.6,<3.0)
 Requires-Dist: xlrd (>=2.0.1,<2.1.0)
 Requires-Dist: xlwings (>=0.35,<1.0)
@@ -53,50 +53,46 @@ Project-URL: Homepage, https://pypi.org/project/pyutilities
 Project-URL: Repository, https://github.com/dmitry-ed-gusev/pyutilities
 Description-Content-Type: text/markdown
 
-# Python Utilities Library
+# Python Utilities Library (PyUtilities)
 
-Version 2.4.2, 2018 - 2026, Dmitrii Gusev  
-*Last update: 15.05.2026*
+**Dmitrii Gusev, 2018-2026.**
 
 ## Project Description
 
-Useful utilities functions for various needs for the python 3.10+. Containing 'general purpose' functions.
+Useful utilities functions for various needs for the **python 3.10+**. Containing many 'general purpose' functions for various areas. Using of this library may simplify/help with the development in various 'common' tasks.
 
-## Versions history
+## Installation
 
-### 2.4.0/2.4.1/2.4.2
+There are no special pre-requisites for the library to be installed, except **python 3.10+**
+In order to install this library, use the following command:
 
-- many refactorings and minor code improvements
-- overall tests coverage now > 50%, working on improvements :)
-- added new date/time function, several decorators
-- added several useful string functions
-- added LoggingManager component for loguru simple configuration
-- v.2.4.1/v.2.4.2 - minor docs fixes
+```bash
+    pip install pyutilities
+```
 
-### 2.3.0
+**Note: versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and can be installed only for it!**
 
-Intermediate version with improvements/refactorings.
+## Tech Details
 
-### 2.2.0
+### Project modules
 
-Added several new functions - see sources.
+- **cli** - Command Line Integration/Interface - module is under development now :)
+- **config** - configuration module, can be used anywhere
+- **io** - input/output utilities
+- **log** - logging helper classes
+- **sys** - system modules
+- **utils** - various common utilities (common, strings, dates, structures, etc.)
+- **web** - web client, simple web/http server
 
-### 2.1.2
+### Library Usage Examples
 
-Major release with complete set of useful 'general purpose' functions. Documentation 'is coming'...
+See folder **[examples]** in the project root repository.
 
-**Warning! Versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and can be installed only for it!**
+### Development Environment Setup
 
-### Versions before 2.x.x
+There are various shell scripts in the root of the project repository, all of them are well-commented - see there.
 
-**It is strongly recommended: don't use versions prior to the 2.x.x!**
+### Publishing to PyPi Registry
 
-Main properties of the previous library versions:
-
-- set of the 'minor' and 'experimental' releases
-- various set of functions without consistency
-- many 'experimental' functions without proper testing
-- a lot of unnecessary code
-- experiments with building/dependencies management tools - no tool, pipenv poetry
-- unstable list of dependencies with obsolete versions
+Look at the script **_deploy.sh** in the project repo root folder.
 

pyutilities-2.5.0/README.md

@@ -0,0 +1,42 @@
+# Python Utilities Library (PyUtilities)
+
+**Dmitrii Gusev, 2018-2026.**
+
+## Project Description
+
+Useful utilities functions for various needs for the **python 3.10+**. Containing many 'general purpose' functions for various areas. Using of this library may simplify/help with the development in various 'common' tasks.
+
+## Installation
+
+There are no special pre-requisites for the library to be installed, except **python 3.10+**
+In order to install this library, use the following command:
+
+```bash
+    pip install pyutilities
+```
+
+**Note: versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and can be installed only for it!**
+
+## Tech Details
+
+### Project modules
+
+- **cli** - Command Line Integration/Interface - module is under development now :)
+- **config** - configuration module, can be used anywhere
+- **io** - input/output utilities
+- **log** - logging helper classes
+- **sys** - system modules
+- **utils** - various common utilities (common, strings, dates, structures, etc.)
+- **web** - web client, simple web/http server
+
+### Library Usage Examples
+
+See folder **[examples]** in the project root repository.
+
+### Development Environment Setup
+
+There are various shell scripts in the root of the project repository, all of them are well-commented - see there.
+
+### Publishing to PyPi Registry
+
+Look at the script **_deploy.sh** in the project repo root folder.

{pyutilities-2.4.2 → pyutilities-2.5.0}/pyproject.toml

@@ -8,7 +8,7 @@
 #       - most of modules should be typed (used mypy stubs libraries)
 #
 #   Created:  Dmitrii Gusev, 30.05.2025
-#   Modified: Dmitrii Gusev, 15.05.2026
+#   Modified: Dmitrii Gusev, 25.05.2026
 #
 ####################################################################################################
 
@@ -20,13 +20,13 @@ build-backend = "poetry.core.masonry.api"
 # -- project / poetry utility meta-information
 [project]
 name = "pyutilities"
-version = "2.4.2"
+version = "2.5.0"
 description = "PyUtilities :: Useful python 3+ utilities library for various use cases."
 authors     = [
     {name = "Dmitrii Gusev", email = "dmitry.ed.gusev@gmail.com"},
 ]
 license  = "MIT"
-readme   = "docs/README-PUB.md"
+readme   = "README.md"
 requires-python = ">=3.10,<4"
 keywords    = [
     "Python Utilities", "Useful Functions", "String Utilities", "CLI Functions", "toolset", "library",
@@ -63,15 +63,15 @@ dependencies = [
 
     # -- data validation and marshalling (JSON/YAML) --
     "pydantic (>=2.12.5,<3.0.0)",
-    "pydantic-yaml ==1.*",
+    "pydantic-yaml ~=1.6",
     "pydantic-settings ==2.*",
     "marshmallow ~=4.1",
     "pyyaml ==6.*",
-    "ruamel.yaml ==0.*",
+    "ruamel.yaml ==0.18.*",
 
     # -- technical libraries
     "urllib3~=2.6",  # - allowed: >=2.3.0 <3.0.0
-    "paramiko==4.*",
+    "paramiko ==5.*",
     "requests~=2.32",  # - allowed: >=2.32.0 <3.0.0
     "markdown~=3.7",  # - allowed: >=3.7.0 <4.0.0
     "prettytable~=3.14",  # - allowed: >=3.14.0 <4.0.0
@@ -114,7 +114,7 @@ dev = [
     "hypothesis ==6.*",
 
     # -- typing libraries + typing stubs for runtime dependencies --
-    "mypy ==1.*", # - typing library
+    "mypy ==2.*", # - typing library
     "types-six ==1.*",
     "types-mock ==5.*",
     "types-paramiko ==4.*",
@@ -150,7 +150,7 @@ dev = [
     "responses ==0.*", # - used by many testing/code quality libraries
 
     # -- readline module depending on the platform
-    "pyreadline3 ==3.5.4 ; sys_platform == 'win32' or sys_platform == 'cygwin'",
+    "pyreadline3 ==3.* ; sys_platform == 'win32' or sys_platform == 'cygwin'",
     "gnureadline ==8.2.13 ; sys_platform != 'win32'"
 
 ]
@@ -165,11 +165,11 @@ research = [ # - research dependencies (Jupyter, etc.)
 packages = [{include = "pyutilities", from = "src"}]
 
 # -- poetry :: source repositories setup
-[[tool.poetry.source]]
-name = "severstal_repo"
-url = "https://repo.severstal.severstalgroup.com/artifactory/api/pypi/pypi/simple/"
+# [[tool.poetry.source]]
+# name = "severstal_repo"
+# url = "https://repo.severstal.severstalgroup.com/artifactory/api/pypi/pypi/simple/"
 # priority = "primary" # - primary packages source
-priority = "supplemental" # - packages source will be used when primary is not available...
+# priority = "supplemental" # - packages source will be used when primary is not available...
 
 [tool.poetry.dependencies]
 python = ">=3.10,<4"

pyutilities-2.5.0/src/pyutilities/utils/datetime_utils.py

@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+
+"""
+Useful date/time utilities and functions.
+
+Created:  Dmitrii Gusev, 22.03.2026
+Modified: Dmitrii Gusev, 25.05.2026
+"""
+
+import calendar
+import logging
+from datetime import datetime, timedelta, timezone
+from functools import lru_cache
+
+from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
+
+# DATETIME :: timezones defaults
+MSK_TIMEZONE: timezone = timezone(timedelta(hours=3), name="Moscow Timezone (GMT+3)")
+MSK_TIMEZONE_NAME: str = "Europe/Moscow"
+# - CACHE :: cache setup (size) for cached functions/methods
+LRU_CACHE_SIZE: int = 128
+
+
+log = logging.getLogger(__name__)
+log.addHandler(logging.NullHandler())
+
+
+def get_timestamp(
+    current_timezone: timezone = MSK_TIMEZONE,
+    days: float = 0,
+    hours: float = 0,
+    minutes: float = 0,
+    seconds: float = 0,
+) -> datetime:
+    """Return timestamp: now (in the default timezone) +/- the specified time delta in hours / minutes /
+    seconds. Default timezone can be changed by the function argument."""
+
+    return datetime.now(current_timezone) + timedelta(
+        days=days, hours=hours, minutes=minutes, seconds=seconds
+    )
+
+
+@lru_cache(maxsize=LRU_CACHE_SIZE)
+def get_timestampc(
+    current_timezone: timezone = MSK_TIMEZONE,
+    days: float = 0,
+    hours: float = 0,
+    minutes: float = 0,
+    seconds: float = 0,
+) -> datetime:
+    """CACHED. Cached version of the get_timestamp() method."""
+
+    return get_timestamp(current_timezone, days, hours, minutes, seconds)
+
+
+def get_dates_range_before_date(date: datetime, tzinfo: timezone) -> tuple[int, int]:
+    """Generates two dates range - date_from/date_to for the time period 'before today' - from the 1st day
+    of the current month till the today - 1 day (current month). In case today is 1st day - range for the
+    whole previous month, if today is 01.01.XXXX - range for 01.12.XXXX-1 - 31.12.XXXX-1.
+    """
+
+    log.debug("get_dates_range_before_date(): the date [%s].", date)
+
+    tstamp_from: int = 0
+    tstamp_to: int = 0
+
+    if date:  # if date is OK (not empty/None)
+
+        # - processing and calculating dates
+        if date.day == 1:  # today - 1st day of month, we need report for the previous month
+
+            if date.month == 1:  # we are at 01.01.XXXX - we need report for Dec.XXXX - 1
+
+                date_from = datetime(date.year - 1, 12, 1, tzinfo=tzinfo)  # from: 01 Dec Year-1 (prev. year)
+                date_to = datetime(date.year - 1, 12, 31, tzinfo=tzinfo)  # to: 31 Dec Year-1 (prev. year)
+
+            else:  # we are at 01.XX.XXXX - we need report for previous month
+
+                # from: 01 Month-1 Year
+                date_from = datetime(date.year, date.month - 1, 1, tzinfo=tzinfo)
+                # last day of the previous month
+                _, last_day = calendar.monthrange(date.year, date.month - 1)
+                # to: Last Day Month-1 Year
+                date_to = datetime(date.year, date.month - 1, last_day, tzinfo=tzinfo)
+
+        else:  # today isn't the 1st, we need report from 1st till yesterday
+
+            date_from = datetime(date.year, date.month, 1, tzinfo=tzinfo)  # from: 01 Month Year
+            date_to = datetime(date.year, date.month, date.day - 1, tzinfo=tzinfo)  # to: Day-1 Month Year
+
+        # - final date/time - date from: XX.XX.XX 00:00:00
+        tstamp_from = int(
+            datetime(
+                date_from.year, date_from.month, date_from.day, hour=0, minute=0, second=0, tzinfo=tzinfo
+            ).timestamp()
+        )
+        # - final date/time - # date to: XX.XX.XXXX 23:59:59
+        tstamp_to = int(
+            datetime(
+                date_to.year, date_to.month, date_to.day, hour=23, minute=59, second=59, tzinfo=tzinfo
+            ).timestamp()
+        )
+
+    log.debug("Timestamps for [%s]: from [%s], to [%s].", date, tstamp_from, tstamp_to)
+
+    # - return the tuple of values
+    return (tstamp_from, tstamp_to)
+
+
+@lru_cache(maxsize=LRU_CACHE_SIZE)
+def get_dates_range_before_datec(date: datetime, tzinfo: timezone) -> tuple[int, int]:
+    """CACHED. Cached version of the get_dates_range_before_date()."""
+
+    return get_dates_range_before_date(date, tzinfo)
+
+
+def human_readable_duration_seconds(duration_seconds):
+    """Convert duration in seconds into human-readable string-duration."""
+
+    days = duration_seconds // (24 * 3600)
+    hours = (duration_seconds % (24 * 3600)) // 3600
+    minutes = (duration_seconds % (24 * 3600)) % 3600 // 60
+    seconds = duration_seconds % 3600 % 60
+
+    result = ""
+    if days > 0:
+        result += f"{days} д. "
+    if hours > 0:
+        result += f"{hours} ч. "
+    if minutes > 0:
+        result += f"{minutes:02d} мин. "
+    result += f"{seconds:02d} сек."
+    result = result.strip()
+
+    log.debug("Converted duration: [%s] into readable str: [%s].", duration_seconds, result)
+
+    return result
+
+
+@lru_cache(maxsize=LRU_CACHE_SIZE)
+def human_readable_duration_secondsc(duration_seconds):
+    """CACHED. Cached version of the human_readable_duration_seconds() method."""
+
+    return human_readable_duration_seconds(duration_seconds)
+
+
+if __name__ == "__main__":
+    print(MSG_MODULE_ISNT_RUNNABLE)

pyutilities-2.5.0/src/pyutilities/utils/structures.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+
+"""
+Structures module.
+
+Created:  Dmitrii Gusev, 21.05.2026
+Modified: Dmitrii Gusev, 24.05.2026
+"""
+
+from collections import defaultdict
+
+from pyutilities.utils.string_utils import is_empty
+
+
+def _defaultdict_factory(key: str):
+    """Return different default types for the defaultdict based on the key prefix.
+    This function is used a s a default factory for the class KeyAwareDefaultDict - see below.
+    """
+
+    if isinstance(key, str) and not is_empty(key):
+
+        if key.startswith("count_"):  # int type
+            return 0
+
+        if key.startswith("str_"):  # string type
+            return ""
+
+        if key.startswith("items_"):  # list type
+            return []
+
+        if key.startswith("set_"):  # set type
+            return set()
+
+        if key.startswith("dict_"):  # dictionary type
+            return {}
+
+    # unknown type - fallback for unknown keys
+    return None
+
+
+class KeyAwareDefaultDict(defaultdict):  # type: ignore[type-arg]
+    """Extension of the default dictionary in python - 'key aware default dictionary', implementing
+    different types of the dictionary values, depending on the dictionary keys prefixes.
+    Prefixes are:
+        - count_* - int type
+        - str_*   - str type
+        - items_* - list type
+        - set_*   - set type
+        - dict_*  - dict type
+    Usage example:
+        dynamic_dict = KeyAwareDefaultDict()  # option I - default factory (see above)
+        dynamic_dict = KeyAwareDefaultDict(default_factory)  # option II - use your custom factory function
+    """
+
+    def __init__(self, default_factory=_defaultdict_factory):
+        super().__init__(default_factory)
+
+    def __missing__(self, key):
+        # call the factory with a key and save the result
+        result = self.default_factory(key)  # type: ignore[call-arg, misc]
+        self[key] = result
+        return result

pyutilities-2.4.2/docs/README-PUB.md

@@ -1,46 +0,0 @@
-# Python Utilities Library
-
-Version 2.4.2, 2018 - 2026, Dmitrii Gusev  
-*Last update: 15.05.2026*
-
-## Project Description
-
-Useful utilities functions for various needs for the python 3.10+. Containing 'general purpose' functions.
-
-## Versions history
-
-### 2.4.0/2.4.1/2.4.2
-
-- many refactorings and minor code improvements
-- overall tests coverage now > 50%, working on improvements :)
-- added new date/time function, several decorators
-- added several useful string functions
-- added LoggingManager component for loguru simple configuration
-- v.2.4.1/v.2.4.2 - minor docs fixes
-
-### 2.3.0
-
-Intermediate version with improvements/refactorings.
-
-### 2.2.0
-
-Added several new functions - see sources.
-
-### 2.1.2
-
-Major release with complete set of useful 'general purpose' functions. Documentation 'is coming'...
-
-**Warning! Versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and can be installed only for it!**
-
-### Versions before 2.x.x
-
-**It is strongly recommended: don't use versions prior to the 2.x.x!**
-
-Main properties of the previous library versions:
-
-- set of the 'minor' and 'experimental' releases
-- various set of functions without consistency
-- many 'experimental' functions without proper testing
-- a lot of unnecessary code
-- experiments with building/dependencies management tools - no tool, pipenv poetry
-- unstable list of dependencies with obsolete versions

pyutilities-2.4.2/src/pyutilities/utils/datetime_utils.py

@@ -1,78 +0,0 @@
-# -*- coding: utf-8 -*-
-
-"""
-Useful date/time utilities and functions.
-
-Created:  Dmitrii Gusev, 22.03.2026
-Modified: Dmitrii Gusev, 10.05.2026
-"""
-
-from datetime import datetime, timedelta, timezone
-
-import pendulum
-from pendulum import Date
-
-from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
-
-MSK_TIMEZONE: timezone = timezone(timedelta(hours=3), name="Moscow Timezone (Russia)")
-MSK_TIMEZONE_NAME: str = "Europe/Moscow"
-
-
-def get_timestamp(
-    current_timezone: timezone = MSK_TIMEZONE,
-    days: float = 0,
-    hours: float = 0,
-    minutes: float = 0,
-    seconds: float = 0,
-) -> datetime:
-    """Return timestamp: now (in the default timezone) +/- the specified time delta in hours / minutes /
-    seconds. Default timezone can be changed by the function argument."""
-
-    return datetime.now(current_timezone) + timedelta(
-        days=days, hours=hours, minutes=minutes, seconds=seconds
-    )
-
-
-def get_dates_range_before_date(date: datetime) -> tuple[int, int]:
-    """Generates two dates range - date_from/date_to for the time period 'before today' - from the 1st day
-    of the current month till the today - 1 day (current month). In case today is 1st day - range for the
-    whole previous month, if today is 01.01.XXXX - range for 01.12.XXXX-1 - 31.12.XXXX-1.
-    """
-
-    # - local variables
-    local_today: Date = Date(date.year, date.month, date.day)
-    date_from: Date
-    date_to: Date
-
-    # - processing and calculating dates
-    if local_today.day == 1:  # today - 1st day of month, we need report for the previous month
-
-        if local_today.month == 1:  # we are at 01.01.XXXX - we need report for Dec.XXXX - 1
-
-            date_from = pendulum.date(local_today.year - 1, 12, 1)  # from: 01 Dec Year-1
-            date_to = pendulum.date(local_today.year - 1, 12, 31)  # to: 31 Dec Year-1
-
-        else:  # we are at 01.XX.XXXX - we need report for previous month
-
-            # from: 01 Month-1 Year
-            date_from = pendulum.date(local_today.year, local_today.month - 1, 1)
-            # to: Last Day Month-1 Year
-            date_to = pendulum.date(
-                local_today.year, local_today.month - 1, local_today.subtract(months=1).days_in_month
-            )
-
-    else:  # today isn't the 1st, we need report from 1st till yesterday
-
-        date_from = pendulum.date(local_today.year, local_today.month, 1)  # from: 01 Month Year
-        date_to = pendulum.date(local_today.year, local_today.month, date.day - 1)  # to: Day-1 Month Year
-
-    # - generate from/to timestamps
-    tstamp_from = pendulum.datetime(date_from.year, date_from.month, date_from.day)
-    tstamp_to = pendulum.datetime(date_to.year, date_to.month, date_to.day)
-
-    # - return the tuple of values
-    return (tstamp_from.int_timestamp, tstamp_to.int_timestamp)
-
-
-if __name__ == "__main__":
-    print(MSG_MODULE_ISNT_RUNNABLE)