pyutilities 2.1.2__tar.gz → 2.4.0__tar.gz

{pyutilities-2.1.2 → pyutilities-2.4.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: pyutilities
-Version: 2.1.2
-Summary: PyUtilities :: Useful python 3 utilities library for various use cases.
+Version: 2.4.0
+Summary: PyUtilities :: Useful python 3+ utilities library for various use cases.
 License-Expression: MIT
 License-File: LICENSE
-Keywords: Python Utilities,Useful Functions,String Utilities,CLI Functions,toolset,library,System Utilities
+Keywords: Python Utilities,Useful Functions,String Utilities,CLI Functions,toolset,library,System Utilities,Useful Decorators,IO Functions
 Author: Dmitrii Gusev
 Author-email: dmitry.ed.gusev@gmail.com
 Requires-Python: >=3.10,<4
@@ -16,21 +16,36 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
+Requires-Dist: click (>=8.3,<9.0)
 Requires-Dist: fake-useragent (>=2.0,<3.0)
 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: 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: pyfiglet (>=1.0,<2.0)
+Requires-Dist: python-dateutil (>=2.9,<3.0)
+Requires-Dist: python-dotenv (>=1.2,<2.0)
+Requires-Dist: pytz (==2026.*)
 Requires-Dist: pyyaml (==6.*)
 Requires-Dist: requests (>=2.32,<3.0)
-Requires-Dist: urllib3 (>=2.3,<3.0)
+Requires-Dist: rich-pyfiglet (>=1.0,<2.0)
+Requires-Dist: ruamel.yaml (==0.*)
+Requires-Dist: urllib3 (>=2.6,<3.0)
 Requires-Dist: xlrd (>=2.0.1,<2.1.0)
-Requires-Dist: xlwings (>=0.33.9,<0.34.0)
+Requires-Dist: xlwings (>=0.35,<1.0)
 Requires-Dist: xlwt (==1.3.0)
 Project-URL: Bug Tracker, https://github.com/dmitry-ed-gusev/pyutilities/issues
 Project-URL: Documentation, https://github.com/dmitry-ed-gusev/pyutilities
@@ -40,8 +55,8 @@ Description-Content-Type: text/markdown
 
 # Python Utilities Library
 
-Version 2.1.2, 2018 - 2025, Dmitrii Gusev  
-*Last update: 28.11.2025*
+Version 2.2.0, 2018 - 2026, Dmitrii Gusev  
+*Last update: XX.XX.2026*
 
 ## Project Description
 
@@ -49,6 +64,13 @@ Useful utilities functions for various needs for the python 3.10+. Containing 'g
 
 ## Versions history
 
+### 2.2.0
+
+Added new functions:
+
+- func1()
+- func2()
+
 ### 2.1.2
 
 Major release with complete set of useful 'general purpose' functions. Documentation 'is coming'...

{pyutilities-2.1.2 → pyutilities-2.4.0}/docs/README-PUB.md

@@ -1,7 +1,7 @@
 # Python Utilities Library
 
-Version 2.1.2, 2018 - 2025, Dmitrii Gusev  
-*Last update: 28.11.2025*
+Version 2.2.0, 2018 - 2026, Dmitrii Gusev  
+*Last update: XX.XX.2026*
 
 ## Project Description
 
@@ -9,6 +9,13 @@ Useful utilities functions for various needs for the python 3.10+. Containing 'g
 
 ## Versions history
 
+### 2.2.0
+
+Added new functions:
+
+- func1()
+- func2()
+
 ### 2.1.2
 
 Major release with complete set of useful 'general purpose' functions. Documentation 'is coming'...

pyutilities-2.4.0/pyproject.toml

@@ -0,0 +1,315 @@
+####################################################################################################
+#
+#   Main configuration file for the [pyutilities] library. The whole project configuration (any
+#   setting) should be put here. Also configuration for dependencies and all code quality tools.
+#
+#   Notes (code quality, etc.):
+#       - project line length = 110 symbols (black, flake8)
+#       - most of modules should be typed (used mypy stubs libraries)
+#
+#   Created:  Dmitrii Gusev, 30.05.2025
+#   Modified: Dmitrii Gusev, 15.05.2026
+#
+####################################################################################################
+
+# -- build system information
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+# -- project / poetry utility meta-information
+[project]
+name = "pyutilities"
+version = "2.4.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"
+requires-python = ">=3.10,<4"
+keywords    = [
+    "Python Utilities", "Useful Functions", "String Utilities", "CLI Functions", "toolset", "library",
+    "System Utilities", "Useful Decorators", "IO Functions"
+]
+classifiers = [
+    "Development Status :: 6 - Mature",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Topic :: Utilities",
+    "Typing :: Typed"
+]
+
+# - project runtime dependencies
+dependencies = [
+
+    # -- loguru
+    "loguru==0.7.3",
+
+    # -- ms word / ms excel libraries
+    "xlrd~=2.0.1",  # - allowed: >=2.0.1 <2.1.0
+    "xlwt==1.3.0",
+    "xlwings~=0.35",
+    "openpyxl==3.1.5",
+
+    # -- data validation and marshalling (JSON/YAML) --
+    "pydantic (>=2.12.5,<3.0.0)",
+    "pydantic-yaml ==1.*",
+    "pydantic-settings ==2.*",
+    "marshmallow ~=4.1",
+    "pyyaml ==6.*",
+    "ruamel.yaml ==0.*",
+
+    # -- technical libraries
+    "urllib3~=2.6",  # - allowed: >=2.3.0 <3.0.0
+    "paramiko==4.*",
+    "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
+    "fake-useragent~=2.0",  # - allowed: >=2.0.0 <3.0.0
+    "click~=8.3",
+    "python-dotenv ~=1.2", # - loading various .env configs
+
+    # -- terminal pseudo-graphics / pretty output
+    "prettytable ~=3.17", # - terminal tables
+    "pyfiglet ~=1.0", # - ASCII graphics
+    "rich-pyfiglet ~=1.0", # - ASCII graphics addon (colors)
+
+    # -- datetime utilities
+    "pendulum ~=3.2",
+    "python-dateutil ~=2.9",
+    "pytz ==2026.*"
+
+]
+
+# -- additional dependencies groups (test/research/etc. - not runtime)
+[dependency-groups]
+
+dev = [
+
+    # -- pytest library and extensions --
+    "pytest ==9.*",  # - allowed any version < 10.0.0
+    "pytest-env ==1.*",
+    "pytest-cov ==7.*",
+    "pytest-mock ==3.*",
+    "pytest-pep8 ==1.0.6",
+    "pytest-flakes ==4.0.5",
+    "pytest-isort ==4.0.0",
+    "pytest-black ==0.6.0",
+    "pytest-variables[hjson,yaml,toml] ==3.1.0",
+
+    # -- testing-related libraries --
+    "mock ==5.*",
+    "mockito ~=2",
+    "nose2 ==0.*",
+    "hypothesis ==6.*",
+
+    # -- typing libraries + typing stubs for runtime dependencies --
+    "mypy ==1.*", # - typing library
+    "types-six ==1.*",
+    "types-mock ==5.*",
+    "types-paramiko ==4.*",
+    "types-requests ==2.*",
+    "types-markdown ==3.*",
+    "types-PyYAML ==6.*",
+    "types-flake8-bugbear ==25.*",
+
+    # -- code quality control libraries
+    "flake8 ==7.*",
+    "flake8-pyproject ~=1.2",
+    "flake8-bandit ~=4.1",
+    "flake8-bugbear ==25.*",
+    "black ~=26.0", # - code formatter
+    "pylint ~=4.0",
+    "pre-commit ~=4.0", # - pre-commit hook
+    "bandit ==1.9.*",
+    "isort[requirements_deprecated_finder,pipfile_deprecated_finder] ==8.*",
+    "pyflakes ~=3.4",
+    "codeaudit ~=1.4", # - SAST local analysis
+
+    # -- profiling/debugging libraries
+    "snakeviz ==2.2.2",
+    "memory-profiler ==0.61.0",
+    "py-spy ==0.4.1",
+    "viztracer ==1.1.1",
+
+    # -- development-related process libraries
+    "sphinx ==8.* ; python_version == '3.10'", # - docs lib - for python == 3.10
+    "sphinx ==9.* ; python_version >= '3.11' and python_version < '4.0'", # - docs lib - for python > 3.10
+
+    "watchdog ==6.0.0", # - file monitor and auto-reloader
+    "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'",
+    "gnureadline ==8.2.13 ; sys_platform != 'win32'"
+
+]
+
+research = [ # - research dependencies (Jupyter, etc.)
+
+    "notebook~=7.5"  # allowed < 8.0.0
+
+]
+
+[tool.poetry]
+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/"
+# priority = "primary" # - primary packages source
+priority = "supplemental" # - packages source will be used when primary is not available...
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4"
+
+[project.urls]
+Homepage = "https://pypi.org/project/pyutilities"
+Repository = "https://github.com/dmitry-ed-gusev/pyutilities"
+Documentation = "https://github.com/dmitry-ed-gusev/pyutilities"
+"Bug Tracker" = "https://github.com/dmitry-ed-gusev/pyutilities/issues"
+
+[project.scripts]
+pyutils = 'pyutilities.cli.pyutils:pyutils'
+
+# -- flake8 tool
+[tool.flake8]
+# - list of ignored issues for the flake8 tool
+# - (E501 - long line, F401 - unused import, E203 - whitespace before ':' - black puts it)
+ignore = ['F401']
+# - max cognitive complexity for statements
+max-complexity = 10
+# - line length aligned with same setting for [black] (88 chars by default) -> project value = 110
+max-line-length = 110
+# - ignored violations, specific per files
+per-file-ignores = [
+    'tests/**:S101, S311',
+]
+
+# -- pylint tool
+[tool.pylint.MASTER]
+disable = [
+    'C0114', # missing-module-docstring
+    'C0115', # missing-class-docstring
+    'C0116', # missing-function-docstring
+]
+
+[tool.pylint.FORMAT]
+max-line-length=110
+max-module-lines=1000
+
+# -- isort tool
+[tool.isort]
+profile = 'black'
+multi_line_output = 3
+line_length = 110
+include_trailing_comma = true
+skip_gitignore = true
+skip_glob = ["**/migrations/*", "**/settings/*"]
+# src_paths = ["./", "src/"]
+src_paths = ["./src/"]
+
+# -- black tool configuration
+[tool.black]
+line_length = 110
+target-version = ['py310']
+extend-exclude = '''
+(
+    migrations   # Alembic DB migrations
+)
+'''
+
+# -- bandit tool
+[tool.bandit]
+exclude_dirs = ["tests"]
+tests = ["B201", "B301"]
+skips = ["B101", "B601"]
+
+# -- mypy tool
+[tool.mypy]
+mypy_path = "./"
+python_version = "3.10"
+follow_imports = "silent"
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_any_generics = true
+check_untyped_defs = true
+no_implicit_reexport = true
+allow_untyped_defs = true
+# disallow_untyped_defs = true
+# - mypy will ignore missing types defs imports
+ignore_missing_imports = true
+# - force mypy to analyze as best as its can module without types defs
+follow_untyped_imports = true
+
+# [[tool.mypy.overrides]]
+# module = "pyutilities.web.http_client"
+# disable_error_code = ["R0913", "too-many-arguments", "unused-argument"]
+
+# -- pytest tool
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = """
+--cov=./src/pyutilities --verbose --cov-report=html --cov-report=xml --cov-report=json --cov-report=annotate --capture=sys -rx --durations=0 --full-trace --color=auto --hypothesis-show-statistics --hypothesis-verbosity=verbose
+
+"""
+testpaths = [
+    "tests/",
+    "integration/",
+]
+mock_use_standalone_module = true
+mock_traceback_monkeypatch = false
+
+# - tests markers - tests can be grouped and executed by them
+markers = [
+
+    "functional: these tests are significantly slower as they run the whole CLI script",
+
+]
+
+# -- env variables for tests in pytest
+[tool.pytest_env]
+# MY_VARIABLE = "my_value"
+PYTHONTRACEMALLOC = 20
+
+# -- coverage tool configuration (coveragerc)
+[tool.coverage.run]
+branch = true
+data_file = ".coverage/.coverage"
+omit = [
+        '*__init__*',
+        '*temp*',
+        '*tests\*'
+]
+
+[tool.coverage.report]
+show_missing = true
+# - show 2 decimal digits for coverage report values
+precision = 2
+# skip_covered = true
+
+[tool.coverage.html]
+directory = ".coverage/htmlcoverage"
+title = "Python Utilities :: Tests Coverage Report."
+
+[tool.coverage.xml]
+output = ".coverage/coverage.xml"
+
+# -- this setting is used by coverage.py, ignored by pytest-cov
+[tool.coverage.json]
+output = ".coverage/coverage.json"
+pretty_print = true

{pyutilities-2.1.2 → pyutilities-2.4.0}/src/pyutilities/__init__.py

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+
 # This code should be put in <your_package_name>/__init__.py or <your_package_name>/_version.py
 # The library version now is programmatically accessible (from code).
 

pyutilities-2.4.0/src/pyutilities/cli/pyutils.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+"""
+Cmd line module for th pyutilities library - integration with CLI.
+
+Created:  Dmitrii Gusev, 17.04.2026
+Modified: Dmitrii Gusev, 17.04.2026
+"""
+
+import click
+
+from pyutilities import __version__
+
+MSG_VERSION = f"\nPy Utilities, version: {__version__}, (C) Dmitrii Gusev, 2018-2026.\n"
+
+
+@click.group()
+@click.help_option("-h", "--help")
+@click.version_option(__version__, "-v", "--version", message=MSG_VERSION)
+@click.pass_context
+def pyutils(ctx):  # pylint: disable=unused-argument
+    """Module [Py Utilities], (C) Dmitrii Gusev, 2018-2026."""
+    click.echo("")
+
+
+@pyutils.command("version")
+def version():
+    click.echo(__version__ + "\n")

{pyutilities-2.1.2 → pyutilities-2.4.0}/src/pyutilities/config/configuration.py

@@ -321,7 +321,8 @@ class ConfigurationXls(Configuration):
                 dictionary[name] = value
 
         elif path_to_xls.endswith("xlsx"):  # load from excel file - format xlsx
-            excel_book = openpyxl.load_workbook(path_to_xls)  # workbook
+            # load workbook by the given path
+            excel_book = openpyxl.load_workbook(path_to_xls)  # type: ignore
             excel_sheet = excel_book[config_sheet_name]  # specified sheet by name
             self.log.debug("Loaded XLSX config. Found [%s] row(s). Loading.", excel_sheet.max_row)
             for rownumber in range(excel_sheet.max_row):

{pyutilities-2.1.2 → pyutilities-2.4.0}/src/pyutilities/io/io_utils.py

@@ -4,7 +4,7 @@
 IO Utilities module.
 
 Created:  Dmitrii Gusev, 04.04.2017
-Modified: Dmitrii Gusev, 25.11.2025
+Modified: Dmitrii Gusev, 17.04.2026
 """
 
 import errno
@@ -83,7 +83,7 @@ def str_2_file(filename: str, content: str, overwrite: bool = False, encoding: s
         f.write(content)
 
 
-def file2str(filename: str, encoding: str = DEFAULT_ENCODING) -> str:
+def file_2_str(filename: str, encoding: str = DEFAULT_ENCODING) -> str:
     """Read content from the provided file as string/text."""
 
     log.debug("file2str(): reading content from file: [%s].", filename)
@@ -123,8 +123,20 @@ def compress_file(input_file, output_file):
             shutil.copyfileobj(f_in, f_out)
 
 
-def file_size(file_path: str) -> str:
-    """Function will return the file size in readable format with the highest size mark - KB/MB/GB/TB."""
+def file_str(file_path: str) -> int:
+    """Function will return the file size in bytes. In case file doesn't exist/not a file/other
+    issues - the function will return -1 (negative value)."""
+
+    if os.path.isfile(file_path):
+        file_info = os.stat(file_path)
+        return file_info.st_size
+
+    return -1
+
+
+def file_size_str(file_path: str) -> str:
+    """Function will return the file size in a human-readable format with the highest size
+    mark - KB/MB/GB/TB."""
 
     if os.path.isfile(file_path):
         file_info = os.stat(file_path)