decorateme.CodeStatus.of() - Code Metrics - dmyersturnbull/decorate-me - Measure and Improve Code Quality continuously with Scrutinizer

decorateme.CodeStatus.of() A
last analyzed 2023-07-10 00:09 UTC

↳ Parent: decorateme

Complexity

Conditions

Size

Total Lines	9
Code Lines	9

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
eloc	9
dl	0
loc	9
rs	9.95
c	0
b	0
f	0
cc	4
nop	2

"""
Code for decorateme.
"""
from __future__ import annotations

import enum
import html as _html
import logging

# noinspection PyUnresolvedReferences
from abc import abstractmethod
from collections.abc import Callable, Collection

# noinspection PyUnresolvedReferences
from functools import total_ordering, wraps
from importlib.metadata import PackageNotFoundError

from importlib.metadata import metadata as __load

from pathlib import Path

# noinspection PyUnresolvedReferences
from typing import Literal, TypeVar, final

from warnings import warn

pkg = Path(__file__).absolute().parent.name
logger = logging.getLogger(pkg)
metadata = None

try:
    metadata = __load(pkg)
    __status__ = "Stable"
    __copyright__ = "Copyright 2017–2022"
    __date__ = "2020-08-24"
    __uri__ = metadata["home-page"]
    __title__ = metadata["name"]
    __summary__ = metadata["summary"]
    __license__ = metadata["license"]
    __version__ = metadata["version"]
    __author__ = metadata["author"]
    __maintainer__ = metadata["maintainer"]
    __contact__ = metadata["maintainer"]
except PackageNotFoundError:  # pragma: no cover
    logger.error(f"Could not load package metadata for {pkg}. Is it installed?")



T = TypeVar("T", bound=type)



def reserved(cls: T) -> T:
    """
    Empty but is declared for future use.
    """
    return cls


class CodeIncompleteError(NotImplementedError):
    """The code is not finished."""


class CodeRemovedError(NotImplementedError):
    """The code was removed."""


class PreviewWarning(UserWarning):
    """The code being called is a preview, unstable. or immature."""


@enum.unique
class CodeStatus(enum.Enum):
    """
    An enum for the quality/maturity of code,
    ranging from incomplete to deprecated.
    """

    INCOMPLETE = -2
    PREVIEW = -1
    STABLE = 0
    PENDING_DEPRECATION = 1
    DEPRECATED = 2
    REMOVED = 3

    @classmethod
    def of(cls, x: int | str | CodeStatus) -> CodeStatus:

        if isinstance(x, str):
            return cls[x.lower().strip()]
        if isinstance(x, CodeStatus):
            return x
        if isinstance(x, int):
            return cls(x)
        raise TypeError(f"Invalid type {type(x)} for {x}")


def status(

    level: int | str | CodeStatus,

    vr: str | None = "",

    msg: str | None = None,

):
    """
    Annotate code quality. Emits a warning if bad code is called.

    Args:
        level: The quality / maturity
        vr: First version the status / warning applies to
        msg: Explanation and/or when it will be removed or completed
    """

    level = CodeStatus.of(level)

    @wraps(status)
    def dec(func):
        func.__status__ = level
        if level is CodeStatus.STABLE:

            return func
        elif level is CodeStatus.REMOVED:

            def my_fn(*_, **__):
                raise CodeRemovedError(f"{func.__name__} was removed (as of version: {vr}). {msg}")

            return wraps(func)(my_fn)

        elif level is CodeStatus.INCOMPLETE:

            def my_fn(*_, **__):
                raise CodeIncompleteError(
                    f"{func.__name__} is incomplete (as of version: {vr}). {msg}"
                )

            return wraps(func)(my_fn)
        elif level is CodeStatus.PREVIEW:

            def my_fn(*args, **kwargs):
                warn(
                    f"{func.__name__} is a preview or immature (as of version: {vr}). {msg}",
                    PreviewWarning,
                )
                return func(*args, **kwargs)

            return wraps(func)(my_fn)
        elif level is CodeStatus.PENDING_DEPRECATION:

            def my_fn(*args, **kwargs):
                warn(
                    f"{func.__name__} is pending deprecation (as of version: {vr}). {msg}",
                    PendingDeprecationWarning,
                )
                return func(*args, **kwargs)

            return wraps(func)(my_fn)
        elif level is CodeStatus.DEPRECATED:

            def my_fn(*args, **kwargs):
                warn(
                    f"{func.__name__} is deprecated (as of version: {vr}). {msg}",
                    DeprecationWarning,
                )
                return func(*args, **kwargs)

            return wraps(func)(my_fn)
        raise AssertionError(f"What is {level}?")

    return dec


def incomplete(

    vr: str | None = "",

    msg: str | None = None,

):
    return status(CodeStatus.INCOMPLETE, vr, msg)


def preview(

    vr: str | None = "",

    msg: str | None = None,

):
    return status(CodeStatus.PREVIEW, vr, msg)


def pending_deprecation(

    vr: str | None = "",

    msg: str | None = None,

):
    return status(CodeStatus.PENDING_DEPRECATION, vr, msg)


def deprecated(

    vr: str | None = "",

    msg: str | None = None,

):
    return status(CodeStatus.DEPRECATED, vr, msg)


def removed(

    vr: str | None = "",

    msg: str | None = None,

):
    return status(CodeStatus.REMOVED, vr, msg)


class _SpecialStr(str):
    """
    A string that can be displayed with Jupyter with line breaks and tabs.
    """

    def _repr_html_(self):
        return str(self.replace("\n", "<br />").replace("\t", "&emsp;&emsp;&emsp;&emsp;"))


class _Utils:
    @classmethod
    def exclude_fn(cls, *items) -> Callable[str, bool]:

        fns = [cls._exclude_fn(x) for x in items]

        def exclude(s: str):

            return any((fn(s) for fn in fns))


        return exclude

    @classmethod
    def _exclude_fn(cls, exclude) -> Callable[str, bool]:

        if exclude is None or exclude is False:
            return lambda s: False
        if isinstance(exclude, str):

            return lambda s: s == exclude
        elif isinstance(exclude, Collection):
            return lambda s: s in exclude
        elif callable(exclude):
            return exclude
        else:
            raise TypeError(str(exclude))

    @classmethod
    def gen_str(

        cls,

        obj,

        fields: Collection[str] = None,

        *,

        exclude: Callable[[str], bool] = lambda _: False,

        address: bool = False,

        angular: bool = False,

    ):
        _name = obj.__class__.__name__
        _fields = ", ".join(
            k + "=" + ('"' + v + '"' if isinstance(v, str) else str(v))
            for k, v in cls.gen_list(obj, fields, exclude=exclude, address=address)
        )
        if angular:

            return f"<{_name} {_fields}>"
        else:
            return f"{_name}({_fields})"

    @classmethod
    def gen_html(

        cls,

        obj,

        fields: Collection[str] = None,

        *,

        exclude: Callable[[str], bool] = lambda _: False,

        address: bool = True,

        angular: bool = True,

    ):
        _name = obj.__class__.__name__
        _fields = ", ".join(
            f"{k}={_html.escape(v)}"
            for k, v in cls.gen_list(obj, fields, exclude=exclude, address=address)
        )
        if angular:

            return f"&lt;<strong>{_name}</strong> {_fields}&gt;"
        else:
            return f"{_name}({_fields})"

    @classmethod
    def gen_list(

        cls,

        obj,

        fields: Collection[str] = None,

        *,

        exclude: Callable[[str], bool] = lambda _: False,

        address: bool = False,

    ):
        yield from _Utils.var_items(obj, fields, exclude=exclude)
        if address:
            yield "@", str(hex(id(obj)))

    @classmethod
    def var_items(cls, obj, fields, exclude):

        yield from [
            (key, value)
            for key, value in vars(obj).items()
            if (fields is None) or (key in fields)
            if not key.startswith(f"_{obj.__class__.__name__}__")  # imperfect exclude mangled
            and not exclude(key)
        ]


def add_reprs(

    fields: Collection[str] | None = None,

    *,

    exclude: Collection[str] | Callable[[str], bool] | None | Literal[False] = None,

    exclude_from_str: Collection[str] | Callable[[str], bool] | None | Literal[False] = None,

    exclude_from_repr: Collection[str] | Callable[[str], bool] | None | Literal[False] = None,

    exclude_html: Collection[str] | Callable[[str], bool] | None | Literal[False] = None,

    exclude_rich: Collection[str] | Callable[[str], bool] | None | Literal[False] = None,

    address: bool = False,

    angular: bool = False,

    html: bool = True,

    rich: bool = True,

):
    """
    Auto-adds ``__repr__``, ``__str__``, ``_repr_html``, and ``__rich_repr__``
    that use instances' attributes (``vars``).
    """
    exclude_from_repr = _Utils.exclude_fn(exclude, exclude_from_repr)
    exclude_from_str = _Utils.exclude_fn(exclude, exclude_from_str)
    exclude_html = _Utils.exclude_fn(exclude, exclude_html)
    exclude_rich = _Utils.exclude_fn(exclude, exclude_rich)

    def __repr(self) -> str:
        return _Utils.gen_str(self, fields, exclude=exclude_from_repr, address=address)

    def __str(self) -> str:
        return _Utils.gen_str(self, fields, exclude=exclude_from_str)

    def __html(self) -> str:
        return _Utils.gen_html(self, fields, exclude=exclude_html)

    if rich:
        from rich.repr import RichReprResult


        def __rich(self) -> RichReprResult:
            yield from _Utils.gen_list(self, fields, exclude=exclude_rich)

    @wraps(add_reprs)
    def dec(cls):
        if cls.__str__ is object.__str__:
            cls.__str__ = __str
        if cls.__repr__ is object.__repr__:
            cls.__repr__ = __repr
        if not hasattr(cls, "_repr_html") and html:
            cls._repr_html_ = __html
class MyParent:
    def __init__(self):
        self._x = 1;
        self.y = 2;

class MyChild(MyParent):
    def some_method(self):
        return self._x    # Ok, since accessed from a child class

class AnotherClass:
    def some_method(self, instance_of_my_child):
        return instance_of_my_child._x   # Would be flagged as AnotherClass is not
                                         # a child class of MyParent
        if not hasattr(cls, "__rich_repr__") and rich:
            cls.__rich_repr__ = __rich

            cls.__rich_repr__.angular = angular
        return cls

    return dec


__all__ = [
    "abstractmethod",
    "total_ordering",
    "final",
    "CodeStatus",
    "status",
    "CodeIncompleteError",
    "PreviewWarning",
    "CodeRemovedError",
    "repr_str",

    "deprecated",
    "pending_deprecation",
    "incomplete",
    "preview",
    "removed",
]


1			"""
2			Code for decorateme.
3			"""
4			from __future__ import annotations
5
6			import enum
7			import html as _html
8			import logging
9
10			# noinspection PyUnresolvedReferences
11			from abc import abstractmethod
12			from collections.abc import Callable, Collection
13
14			# noinspection PyUnresolvedReferences
15			from functools import total_ordering, wraps
16			from importlib.metadata import PackageNotFoundError
			0 ignored issues – show Bug introduced 2021-01-25 08:12 UTC by Report Bug Copy Issue Report The name `metadata` does not seem to exist in module `importlib`. Loading history... introduced 2021-01-25 08:12 UTC by Report Bug Copy Issue Report Unable to import 'importlib.metadata' Loading history...
17			from importlib.metadata import metadata as __load
			0 ignored issues – show Bug introduced 2021-01-25 08:12 UTC by Report Bug Copy Issue Report The name `metadata` does not seem to exist in module `importlib`. Loading history... introduced 2021-01-25 08:12 UTC by Report Bug Copy Issue Report Unable to import 'importlib.metadata' Loading history...
18			from pathlib import Path
19
20			# noinspection PyUnresolvedReferences
21			from typing import Literal, TypeVar, final
			0 ignored issues – show Bug introduced 2021-10-15 03:51 UTC by Report Bug Copy Issue Report The name `final` does not seem to exist in module `typing`. Loading history... Bug introduced 2022-09-07 18:09 UTC by Report Bug Copy Issue Report The name `Literal` does not seem to exist in module `typing`. Loading history...
22			from warnings import warn
23
24			pkg = Path(__file__).absolute().parent.name
25			logger = logging.getLogger(pkg)
26			metadata = None
			0 ignored issues – show Coding Style Naming introduced 2021-01-25 08:12 UTC by Report Bug Copy Issue Report Constant name "metadata" doesn't conform to UPPER_CASE naming style ('([^\\W\\da-z][^\\Wa-z]\|__.__)$' pattern) This check looks for invalid names for a range of different identifiers. You can set regular expressions to which the identifiers must conform if the defaults do not match your requirements. If your project includes a Pylint configuration file, the settings contained in that file take precedence. To find out more about Pylint, please refer to their site. Loading history...
27			try:
28			metadata = __load(pkg)
29			__status__ = "Stable"
30			__copyright__ = "Copyright 2017–2022"
31			__date__ = "2020-08-24"
32			__uri__ = metadata["home-page"]
33			__title__ = metadata["name"]
34			__summary__ = metadata["summary"]
35			__license__ = metadata["license"]
36			__version__ = metadata["version"]

dmyersturnbull / decorate-me

decorateme.CodeStatus.of() A last analyzed 2023-07-10 00:09 UTC

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like

decorateme.CodeStatus.of() A
last analyzed 2023-07-10 00:09 UTC