idegym-common-utils 0.9.0__tar.gz

idegym_common_utils-0.9.0/.gitignore

@@ -0,0 +1,294 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+### PyCharm template
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/dataSources.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Module files
+*.iml
+
+# Project structure
+.idea/**/misc.xml
+.idea/**/modules.xml
+.idea/pySourceRootDetection.xml
+.idea/**/inspectionProfiles/
+.idea/**/runConfigurations/
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Linux template
+# General
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS template
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Archives template
+# It's better to unpack these files and commit the raw source because
+# git has its own built in compression methods.
+*.7z
+*.jar
+*.rar
+*.zip
+!plugins/pycharm/project-opener/project-opener.zip
+!plugins/idea/project-opener/project-opener.zip
+*.gz
+*.gzip
+*.tgz
+*.bzip
+*.bzip2
+*.bz2
+*.xz
+*.lzma
+*.cab
+*.xar
+*.zst
+*.tzst
+
+# Packing-only formats
+*.iso
+*.tar
+
+# Package management formats
+*.dmg
+*.xpi
+*.gem
+*.deb
+*.rpm
+*.msi
+*.msm
+*.msp
+*.txz
+
+### Dev Container template
+.*.temp.dockerfile
+
+### Project template
+.project/
+/test-results.xml
+examples/*.json
+examples/**/*.patch

idegym_common_utils-0.9.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: idegym-common-utils
+Version: 0.9.0
+Summary: IdeGYM Common Utils
+Author-email: Ozren Dabić <ozren.dabic@jetbrains.com>, Vladimir Poliakov <vladimir.poliakov@jetbrains.com>, Vseslav Kasatskii <vseslav.kasatskii@jetbrains.com>
+Requires-Python: >=3.12
+Requires-Dist: hydra-core>=1.3.2
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: structlog>=25.4.0

idegym_common_utils-0.9.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "idegym-common-utils"
+version = "0.9.0"
+description = "IdeGYM Common Utils"
+authors = [
+    { name = "Ozren Dabić", email = "ozren.dabic@jetbrains.com" },
+    { name = "Vladimir Poliakov", email = "vladimir.poliakov@jetbrains.com" },
+    { name = "Vseslav Kasatskii", email = "vseslav.kasatskii@jetbrains.com" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "hydra-core>=1.3.2",
+    "pydantic>=2.10.6",
+    "structlog>=25.4.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/idegym"]

idegym_common_utils-0.9.0/src/idegym/utils/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("idegym-common-utils")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"
+
+if __version__ == "0.0.0.dev0":
+    __version__ = "latest"

idegym_common_utils-0.9.0/src/idegym/utils/decorators.py

@@ -0,0 +1,8 @@
+def executes_operation_in_background(func):
+    """Mark a FastAPI endpoint as one that executes an operation in the background.
+
+    Does nothing at runtime beyond setting the ``_executes_operation_in_background`` attribute;
+    acts as a marker for documentation and introspection.
+    """
+    func._executes_operation_in_background = True
+    return func

idegym_common_utils-0.9.0/src/idegym/utils/dict.py

@@ -0,0 +1,8 @@
+from collections.abc import Generator
+from typing import Any
+
+
+def walk(dictionary: dict[Any, Any]) -> Generator[Any, None, None]:
+    """Yield all leaf values from a nested dictionary, depth-first."""
+    for value in dictionary.values():
+        yield from (walk(value) if isinstance(value, dict) else [value])

idegym_common_utils-0.9.0/src/idegym/utils/functools.py

@@ -0,0 +1,51 @@
+from asyncio import Lock
+from typing import Awaitable, Callable, Optional, ParamSpec, TypeVar, cast, overload
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+AsyncFunction = Callable[P, Awaitable[R]]
+
+
+@overload
+def cached_async_result(function: AsyncFunction) -> AsyncFunction: ...
+
+
+@overload
+def cached_async_result() -> Callable[[AsyncFunction], AsyncFunction]: ...
+
+
+def cached_async_result(target: Optional[AsyncFunction] = None):
+    """Cache the result of an async function after its first successful call.
+
+    Subsequent calls return the cached result without invoking the underlying function again.
+    Uses a double-checked locking pattern to avoid redundant awaits under concurrent callers.
+
+    Can be used with or without parentheses::
+
+        @cached_async_result
+        async def get_config() -> Config: ...
+
+        @cached_async_result()
+        async def get_config() -> Config: ...
+    """
+
+    def _decorate(function: AsyncFunction) -> AsyncFunction:
+        lock = Lock()
+        missing = object()
+        result: object = missing
+
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            nonlocal result
+            if result is not missing:
+                return cast(R, result)
+            async with lock:
+                if result is missing:
+                    result = await function(*args, **kwargs)
+            return cast(R, result)
+
+        return wrapper
+
+    if target is None:
+        return _decorate
+    return _decorate(target)

idegym_common_utils-0.9.0/src/idegym/utils/hashing.py

@@ -0,0 +1,9 @@
+import hashlib
+
+
+def md5(value: str, /, *other: str) -> str:
+    """Compute the MD5 hash of the given value(s)."""
+    digest = hashlib.md5()
+    for value in (value, *other):
+        digest.update(value.encode())
+    return digest.hexdigest()

idegym_common_utils-0.9.0/src/idegym/utils/logging.py

@@ -0,0 +1,13 @@
+from typing import Any, Optional
+
+from structlog import get_logger as get_named_logger
+from structlog.stdlib import BoundLogger
+
+
+def get_logger(name: Optional[str] = None, **initial_values: Any) -> BoundLogger:
+    """Return a structlog ``BoundLogger``, optionally pre-bound with context values.
+
+    Prefer this over importing structlog directly so that the project-wide
+    logging configuration is always the source of truth.
+    """
+    return get_named_logger(name, **initial_values)

idegym_common_utils-0.9.0/src/idegym/utils/path.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+
+def get_base_filename(file_path: str | Path) -> str:
+    """Return the lowercased stem of a file path, stripping all extensions.
+
+    For example, ``"Archive.tar.gz"`` returns ``"archive"``.
+    """
+    return Path(file_path).name.lower().split(".")[0]

idegym_common_utils-0.9.0/src/idegym/utils/serializer.py

@@ -0,0 +1,30 @@
+import json
+from typing import Any, Optional
+
+from pydantic_core import PydanticSerializationError
+
+
+def serialize_as_json_string(data: Any) -> Optional[str]:
+    """Serialize an arbitrary value to a JSON string.
+
+    Handles Pydantic v2 models via duck-typing (``model_dump_json`` preferred
+    over ``model_dump`` for efficiency), plain dicts/lists, bare strings, and
+    falls back to ``json.dumps(..., default=str)`` for other types.
+    Returns ``None`` if ``data`` is ``None``. On serialization failure, falls
+    back to ``str(data)``.
+    """
+    if data is None:
+        return None
+    try:
+        if hasattr(data, "model_dump_json") and callable(data.model_dump_json):
+            return data.model_dump_json()
+        elif hasattr(data, "model_dump") and callable(data.model_dump):
+            return json.dumps(data.model_dump())
+        elif isinstance(data, (dict, list)):
+            return json.dumps(data)
+        elif isinstance(data, str):
+            return data
+        else:
+            return json.dumps(data, default=str)
+    except (PydanticSerializationError, TypeError, ValueError):
+        return str(data)