Merge branch 'main' into release

.github/workflows/ci.yml

@@ -100,7 +100,7 @@ jobs:
       - name: Setup node.js (for pyright)
         uses: actions/setup-node@v1
         with:
-          node-version: "14"
+          node-version: "16"
 
       - name: Install pyright
         run: npm install -g pyright

.yamllint.yaml

@@ -0,0 +1,41 @@
+---
+yaml-files:
+  - '*.yaml'
+  - '*.yml'
+  - '.yamllint'
+
+rules:
+  braces:
+    # Require each key-value pair to be demarcated with identation
+    forbid: true
+  brackets:
+    # Require each element to be on a new line (beginning with - )
+    forbud: true
+  colons: enable
+  commas: enable
+  comments:
+    level: warning
+  comments-indentation:
+    level: warning
+  document-end: disable
+  document-start:
+    level: warning
+  empty-lines: enable
+  empty-values: disable
+  float-values: disable
+  hyphens: enable
+  indentation:
+    spaces: consistent
+    check-multi-line-strings: true
+  key-duplicates: enable
+  key-ordering: disable
+  line-length:
+    max: 100
+  new-line-at-end-of-file: enable
+  new-lines: enable
+  octal-values: disable
+  quoted-strings: disable
+  trailing-spaces: enable
+  truthy:
+    allowed-values: ['true', 'false']
+    check-keys: true

README.md

@@ -13,5 +13,5 @@ pip install ranzen
 
 or install directly from GitHub:
 ```
-pip install git+https://github.com/predictive-analytics-lab/ranzen.git@main
+pip install git+https://github.com/wearepal/ranzen.git@main
 ```

docs/conf.py

@@ -47,13 +47,15 @@
 autodoc_mock_imports = [
     "attr",
     "hydra",
+    "loguru",
     "numpy",
     "omegaconf",
     "pandas",
     "pytorch_lightning",
     "torch",
     "tqdm",
     "wandb",
+    "wrapt",
 ]
 add_module_names = False
 

pyproject.toml

@@ -1,6 +1,7 @@
 [tool.black]
 line-length = 100
 target-version = ['py38']
+extend_exclude = ".undodir/*"
 
 [tool.isort]
 known_third_party = [
@@ -24,7 +25,7 @@ known_third_party = [
   "wandb",
 ]
 known_future_library = []
-extra_standard_library = ["dataclasses", "__future__"]
+extra_standard_library = ["dataclasses", "__future__", "typing_extensions"]
 line_length = 88
 profile = "black"
 force_sort_within_sections = "True"
@@ -44,6 +45,7 @@ classifiers=[
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
   "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
   "Typing :: Typed",
@@ -57,22 +59,27 @@ readme="README.md"
 # do so with the --only option: ``poetry install --only main``. Equally, you can exclude one or 
 # more groups with the --without option: ``poetry install --without torch``.
 [tool.poetry.dependencies]
-python = ">=3.8.0,<3.11"
+python = ">=3.8.0,<3.12"
+typing-extensions = ">=4.4.0"
 
 [tool.poetry.group.wandb.dependencies]
-pandas = { version = "^1.4.3" }
+pandas = { version = "^1.5.0" }
 wandb = { version= ">=0.12,<0.14" }
 
+[tool.poetry.group.logging.dependencies]
+wrapt = "^1.14.1"
+loguru = "^0.6.0"
+
 [tool.poetry.group.torch.dependencies]
 torch = { version = ">=1.12.1" }
-numpy = { version = "^1.21.4" }
+numpy = { version = "^1.23.2" }
 
 [tool.poetry.group.hydra.dependencies]
-hydra-core = { version = "^1.2.0" }
+hydra-core = { version = "^1.3.0" }
 neoconfigen = { version = ">=2.3.3" }
 
 [tool.poetry.group.dev.dependencies]
-black = "^22.6"
+black = "^23.1"
 pytest = "^7.1.2"
 isort = "^5.7.0"
 darglint = "^1.8.0"
@@ -90,11 +97,91 @@ reportUntypedNamedTuple = "error"
 reportConstantRedefinition = "warning"
 reportMissingImports = "error"
 reportMissingTypeStubs = "warning"
+reportUnusedVariable = "warning"
 strictListInference = true
 strictSetInference = true
 strictParameterNoneValue = true
 reportUnnecessaryTypeIgnoreComment = "warning"
 
+[tool.ruff]
+line-length = 100
+select = [
+    "A", # builtins
+    # "ANN", # flake8-annotations
+    "D", # pydocstyle
+    "E", # pycodestyle
+    "F", # pyflakes
+    "I", # isort
+    # "N", # naming
+    # "PD", # pandas-vet
+    "PLC", # pylint convention
+    "PLE", # pylint error
+    "PLR", # pylint refactor
+    "PLW", # pylint warning
+    # "PT", # pytest-style
+    "PTH", # use-pathlib
+    # "UP", # pyupgrade
+    "W",
+]
+ignore = [
+    "D105", # magic methods
+    "D107", # __init__
+    "D203",
+    "D208", # over indentation
+    "D212",
+    "D213",
+    "D214",
+    "D215",
+    "D404",
+    "D405",
+    "D406",
+    "D407",
+    "D408",
+    "D409",
+    "D410",
+    "D411",
+    "D413",
+    "D415",
+    "D416",
+    "D417",
+    "TID252", # relative imports
+    "PDV901", # forbidding "df" as a variable name
+    "ANN101",
+    "ANN102",
+]
+target-version = "py38"
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F403"]
+
+known_third_party = [
+  "black",
+  "hydra",
+  "matplotlib",
+  "mypy",
+  "numpy",
+  "omegaconf",
+  "pandas",
+  "pylint",
+  "pytest",
+  "scipy",
+  "setuptools",
+  "sklearn",
+  "torch",
+  "tqdm",
+  "wandb",
+]
+extra-standard-library = ["__future__", "typing_extensions"]
+force-sort-within-sections = true
+split-on-trailing-comma = false
+classes = [
+  "SAM",
+  "LAMB",
+]
+
+[tool.ruff.flake8-annotations]
+mypy-init-return = true
+
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

ranzen/decorators.py

@@ -1,15 +1,114 @@
-"""Functions related to typing."""
+"""Decorator functions."""
 from __future__ import annotations
 from enum import Enum
-from typing import Any, Callable, TypeVar, get_type_hints
+from functools import partial
+import inspect
+from typing import Any, Callable, Protocol, TypeVar, cast, get_type_hints, overload
 
-__all__ = ["enum_name_str", "implements", "parsable"]
+from loguru import logger
+import wrapt  # pyright: ignore
 
+from ranzen.misc import some
+
+__all__ = [
+    "deprecated",
+    "enum_name_str",
+    "implements",
+    "parsable",
+]
+
+
+_T = TypeVar("_T")
 _F = TypeVar("_F", bound=Callable[..., Any])
 
 
+class IdentityFunction(Protocol[_T]):
+    def __call__(self, __x: _T) -> _T:
+        ...
+
+
+# Remember which deprecation warnings have been printed already.
+_PRINTED_WARNING = {}
+
+
+@overload
+def deprecated(
+    wrapped: _F,
+    /,
+    *,
+    version: str | None = ...,
+    explanation: str | None = ...,
+) -> _F:
+    ...
+
+
+@overload
+def deprecated(
+    wrapped: None = ...,
+    /,
+    *,
+    version: str | None = ...,
+    explanation: str | None = ...,
+) -> IdentityFunction:
+    ...
+
+
+def deprecated(
+    wrapped: _F | None = None,
+    /,
+    *,
+    version: str | None = None,
+    explanation: str | None = None,
+) -> _F | IdentityFunction:
+    """
+    Decorator which can be used for indicating that a function/class is deprecated and going to be removed.
+    Tracks down which function/class printed the warning and will print it only once per call.
+
+    :param wrapped: Function/class to be marked as deprecated.
+    :param version: Version in which the function/class will be removed..
+    :param explanation: Additional explanation, e.g. "Please, ``use another_function`` instead." .
+
+    :returns: Function/class wrapped with a deprecation warning.
+    """
+
+    if wrapped is None:
+        return partial(deprecated, version=version, explanation=explanation)
+
+    @wrapt.decorator
+    def wrapper(wrapped: _F, *args: Any, **kwargs: Any) -> _F:  # pyright: ignore
+        # Check if we already warned about the given function/class.
+        if wrapped.__name__ not in _PRINTED_WARNING.keys():
+            # Add to list so we won't log it again.
+            _PRINTED_WARNING[wrapped.__name__] = True
+
+            # Prepare the warning message.
+            entity_name = "Class" if inspect.isclass(wrapped) else "Function"
+            msg = f"{entity_name} '{wrapped.__name__}' is deprecated"
+
+            # Optionally, add version and explanation.
+            if some(version):
+                msg = f"{msg} and will be removed in version {version}"
+
+            msg = f"{msg}."
+            if some(explanation):
+                msg = f"{msg} {explanation}"
+
+            # Display the deprecated warning.
+            logger.warning(msg)
+
+        # Call the function/initialise the class.
+        return cast(_F, wrapped)
+
+    return wrapper(wrapped)
+
+
+@deprecated(explanation="Use 'typing_extensions.override' instead.")
 class implements:  # pylint: disable=invalid-name
-    """Mark a function as implementing an interface."""
+    """Mark a function as implementing an interface.
+
+    .. warning::
+        This decorator is deprecated in favour of :func:`typing_extensions.override` instead.
+    """
 
     def __init__(self, interface: type):
         """Instantiate the decorator.