ddutils 0.2.2__tar.gz → 0.2.4__tar.gz

{ddutils-0.2.2 → ddutils-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddutils
-Version: 0.2.2
+Version: 0.2.4
 Summary: Domain Driven Utils Library
 Keywords: python,ddutils
 Author: davyddd
@@ -84,16 +84,23 @@ is_subclass(List[str], dict)  # False
 
 ### is_complex_sequence
 
-Checks whether a type annotation represents a sequence type, excluding `str`, `bytes`, and `bytearray`.
+Checks whether a type annotation represents a sequence type, excluding `str`, `bytes`, and `bytearray`
+and their subclasses (a `str`-based `Enum` is not a complex sequence).
 
 ```python
+from enum import Enum
 from typing import List, Tuple
 from ddutils.annotation_helpers import is_complex_sequence
 
 
+class Kind(str, Enum):
+    A = 'a'
+
+
 is_complex_sequence(List[int])  # True
 is_complex_sequence(Tuple[str, ...])  # True
 is_complex_sequence(str)  # False
+is_complex_sequence(Kind)  # False
 is_complex_sequence(dict)  # False
 ```
 
@@ -138,6 +145,21 @@ get_annotation_without_optional(Optional[int])  # <class 'int'>
 get_annotation_without_optional(Optional[List[str]])  # typing.List[str]
 ```
 
+### get_annotation_name
+
+Returns a readable name of an annotation for error messages: a class, a union or a tuple of classes as
+`isinstance` takes it.
+
+```python
+from ddutils.annotation_helpers import get_annotation_name
+
+
+get_annotation_name(int)            # 'int'
+get_annotation_name((int, float))   # 'int | float'
+get_annotation_name(int | None)     # 'int | None'
+get_annotation_name(list[int])      # 'list[int]'
+```
+
 ## Class Helpers
 
 Helper functions for inspecting and extending class-level behavior
@@ -216,6 +238,36 @@ get_generic_base_argument(UserRepository, Repository)  # <class 'User'>
 get_generic_base_argument(Repository, Repository)      # None
 ```
 
+### require_class_attribute
+
+Returns a class attribute that subclasses are expected to declare, for `__init_subclass__` checks. A missing,
+`None` or empty value raises `AttributeError`, a value of the wrong type raises `TypeError`; both name the
+attribute and the class, so a misconfigured subclass fails at definition rather than on first use.
+
+```python
+from typing import ClassVar
+
+from ddutils.class_helpers import require_class_attribute
+
+
+class BaseConsumer:
+    topic: ClassVar[str]
+    batch_size: ClassVar[int] = 100
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        require_class_attribute(cls, 'topic', str)
+        require_class_attribute(cls, 'batch_size', int)
+
+
+class EventConsumer(BaseConsumer):
+    topic = 'events'
+
+
+class BrokenConsumer(BaseConsumer):  # AttributeError: `topic` class attribute of BrokenConsumer must be set
+    pass
+```
+
 ## Function Helpers
 
 Tools for creating and modifying Python functions at runtime.
@@ -285,6 +337,30 @@ delta = timedelta(seconds=5, milliseconds=500)
 convert_timedelta_to_milliseconds(delta)  # 5500
 ```
 
+### convert_to_builtin
+
+Casts a value to its builtin base type (see [get_builtin_base_type](#get_builtin_base_type)):
+a `str` subclass becomes a plain `str`, an `Enum` member becomes its `.value` cast the same way.
+Raises `TypeError` for a value without a builtin base.
+
+```python
+from enum import Enum
+from ddutils.convertors import convert_to_builtin
+
+
+class Kind(str, Enum):
+    A = 'a'
+
+
+class UserId(int):
+    pass
+
+
+convert_to_builtin(Kind.A)  # 'a' (not 'Kind.A', which `str(Kind.A)` would give)
+convert_to_builtin(UserId(2))  # 2
+convert_to_builtin(object())  # TypeError
+```
+
 ## Datetime Helpers
 
 Utilities for working with dates and times.
@@ -446,6 +522,50 @@ AST-based introspection for extracting exceptions from function source code.
 Parses a function’s source code to find all `raise` statements and identify the exception types they use. 
 Returns an iterator of `ExceptionInfo` objects describing each raised exception.
 
+## Value Helpers
+
+Runtime counterparts of the annotation helpers: they inspect values, not type hints.
+
+### get_builtin_base_type
+
+Returns the builtin type a value should be treated as, looking past subclasses: `bool`, `int`, `float`, `str` or `bytes`
+(`bool` is checked before `int`). An `Enum` member is looked at through its `.value`.
+Raises `TypeError` for any other value. Useful for APIs that dispatch on the exact type (serializers, query builders).
+
+```python
+from enum import Enum
+from ddutils.value_helpers import get_builtin_base_type
+
+
+class Kind(str, Enum):
+    A = 'a'
+
+
+class UserId(int):
+    pass
+
+
+get_builtin_base_type(UserId(2))  # <class 'int'>
+get_builtin_base_type(True)  # <class 'bool'>
+get_builtin_base_type(Kind.A)  # <class 'str'>
+get_builtin_base_type(object())  # TypeError
+```
+
+### is_complex_sequence_value
+
+Checks whether a value is a sequence other than `str`, `bytes` or `bytearray` (subclasses included).
+Sets and mappings are not sequences. The runtime counterpart of [is_complex_sequence](#is_complex_sequence).
+
+```python
+from ddutils.value_helpers import is_complex_sequence_value
+
+
+is_complex_sequence_value([1, 2])  # True
+is_complex_sequence_value((1, 2))  # True
+is_complex_sequence_value('abc')  # False
+is_complex_sequence_value({1, 2})  # False
+```
+
 ## Sequence Helpers
 
 Safe operations on sequence types.

{ddutils-0.2.2 → ddutils-0.2.4}/README.md

@@ -66,16 +66,23 @@ is_subclass(List[str], dict)  # False
 
 ### is_complex_sequence
 
-Checks whether a type annotation represents a sequence type, excluding `str`, `bytes`, and `bytearray`.
+Checks whether a type annotation represents a sequence type, excluding `str`, `bytes`, and `bytearray`
+and their subclasses (a `str`-based `Enum` is not a complex sequence).
 
 ```python
+from enum import Enum
 from typing import List, Tuple
 from ddutils.annotation_helpers import is_complex_sequence
 
 
+class Kind(str, Enum):
+    A = 'a'
+
+
 is_complex_sequence(List[int])  # True
 is_complex_sequence(Tuple[str, ...])  # True
 is_complex_sequence(str)  # False
+is_complex_sequence(Kind)  # False
 is_complex_sequence(dict)  # False
 ```
 
@@ -120,6 +127,21 @@ get_annotation_without_optional(Optional[int])  # <class 'int'>
 get_annotation_without_optional(Optional[List[str]])  # typing.List[str]
 ```
 
+### get_annotation_name
+
+Returns a readable name of an annotation for error messages: a class, a union or a tuple of classes as
+`isinstance` takes it.
+
+```python
+from ddutils.annotation_helpers import get_annotation_name
+
+
+get_annotation_name(int)            # 'int'
+get_annotation_name((int, float))   # 'int | float'
+get_annotation_name(int | None)     # 'int | None'
+get_annotation_name(list[int])      # 'list[int]'
+```
+
 ## Class Helpers
 
 Helper functions for inspecting and extending class-level behavior
@@ -198,6 +220,36 @@ get_generic_base_argument(UserRepository, Repository)  # <class 'User'>
 get_generic_base_argument(Repository, Repository)      # None
 ```
 
+### require_class_attribute
+
+Returns a class attribute that subclasses are expected to declare, for `__init_subclass__` checks. A missing,
+`None` or empty value raises `AttributeError`, a value of the wrong type raises `TypeError`; both name the
+attribute and the class, so a misconfigured subclass fails at definition rather than on first use.
+
+```python
+from typing import ClassVar
+
+from ddutils.class_helpers import require_class_attribute
+
+
+class BaseConsumer:
+    topic: ClassVar[str]
+    batch_size: ClassVar[int] = 100
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        require_class_attribute(cls, 'topic', str)
+        require_class_attribute(cls, 'batch_size', int)
+
+
+class EventConsumer(BaseConsumer):
+    topic = 'events'
+
+
+class BrokenConsumer(BaseConsumer):  # AttributeError: `topic` class attribute of BrokenConsumer must be set
+    pass
+```
+
 ## Function Helpers
 
 Tools for creating and modifying Python functions at runtime.
@@ -267,6 +319,30 @@ delta = timedelta(seconds=5, milliseconds=500)
 convert_timedelta_to_milliseconds(delta)  # 5500
 ```
 
+### convert_to_builtin
+
+Casts a value to its builtin base type (see [get_builtin_base_type](#get_builtin_base_type)):
+a `str` subclass becomes a plain `str`, an `Enum` member becomes its `.value` cast the same way.
+Raises `TypeError` for a value without a builtin base.
+
+```python
+from enum import Enum
+from ddutils.convertors import convert_to_builtin
+
+
+class Kind(str, Enum):
+    A = 'a'
+
+
+class UserId(int):
+    pass
+
+
+convert_to_builtin(Kind.A)  # 'a' (not 'Kind.A', which `str(Kind.A)` would give)
+convert_to_builtin(UserId(2))  # 2
+convert_to_builtin(object())  # TypeError
+```
+
 ## Datetime Helpers
 
 Utilities for working with dates and times.
@@ -428,6 +504,50 @@ AST-based introspection for extracting exceptions from function source code.
 Parses a function’s source code to find all `raise` statements and identify the exception types they use. 
 Returns an iterator of `ExceptionInfo` objects describing each raised exception.
 
+## Value Helpers
+
+Runtime counterparts of the annotation helpers: they inspect values, not type hints.
+
+### get_builtin_base_type
+
+Returns the builtin type a value should be treated as, looking past subclasses: `bool`, `int`, `float`, `str` or `bytes`
+(`bool` is checked before `int`). An `Enum` member is looked at through its `.value`.
+Raises `TypeError` for any other value. Useful for APIs that dispatch on the exact type (serializers, query builders).
+
+```python
+from enum import Enum
+from ddutils.value_helpers import get_builtin_base_type
+
+
+class Kind(str, Enum):
+    A = 'a'
+
+
+class UserId(int):
+    pass
+
+
+get_builtin_base_type(UserId(2))  # <class 'int'>
+get_builtin_base_type(True)  # <class 'bool'>
+get_builtin_base_type(Kind.A)  # <class 'str'>
+get_builtin_base_type(object())  # TypeError
+```
+
+### is_complex_sequence_value
+
+Checks whether a value is a sequence other than `str`, `bytes` or `bytearray` (subclasses included).
+Sets and mappings are not sequences. The runtime counterpart of [is_complex_sequence](#is_complex_sequence).
+
+```python
+from ddutils.value_helpers import is_complex_sequence_value
+
+
+is_complex_sequence_value([1, 2])  # True
+is_complex_sequence_value((1, 2))  # True
+is_complex_sequence_value('abc')  # False
+is_complex_sequence_value({1, 2})  # False
+```
+
 ## Sequence Helpers
 
 Safe operations on sequence types.

{ddutils-0.2.2 → ddutils-0.2.4}/ddutils/annotation_helpers.py

@@ -1,7 +1,7 @@
 import inspect
 from collections.abc import Sequence
 from types import UnionType
-from typing import Any, Union, get_args
+from typing import Any, Union, get_args, get_origin
 
 NON_COMPLEX_SEQUENCE_TYPES = (str, bytes, bytearray)
 
@@ -34,7 +34,7 @@ def is_subclass(annotation: Any, *base_types: Any) -> bool:
 
 def is_complex_sequence(annotation: Any) -> bool:
     annotation_origin = get_annotation_origin(annotation)
-    return annotation_origin not in NON_COMPLEX_SEQUENCE_TYPES and is_subclass(annotation_origin, Sequence)
+    return not is_subclass(annotation_origin, *NON_COMPLEX_SEQUENCE_TYPES) and is_subclass(annotation_origin, Sequence)
 
 
 def get_complex_sequence_element_annotation(annotation: Any) -> Any:
@@ -76,3 +76,34 @@ def get_annotation_without_optional(annotation: Any) -> Any:
             raise TypeError('Union types are not supported') from None
 
         return annotation_args[0]
+
+
+def _join_annotation_names(items: Any, separator: str) -> str:
+    return separator.join(get_annotation_name(item) for item in items)
+
+
+def get_annotation_name(annotation: Any) -> str:
+    """
+    Return a readable name of an annotation for messages: `int`, `int | float`, `list[int]`, `None`.
+
+    Accepts a class, a union (`int | None`, `Optional[int]`, `Union[int, str]`), a generic (`dict[str, int]`,
+    `Literal['a', 'b']`) or a tuple of classes as `isinstance` takes it, and renders them the way they are written.
+    """
+    if annotation is None or annotation is type(None):
+        return 'None'
+    if annotation is Ellipsis:
+        return '...'
+    if isinstance(annotation, (str, bytes, int, float)):  # a `Literal` value
+        return repr(annotation)
+    if isinstance(annotation, tuple):
+        return _join_annotation_names(annotation, ' | ')
+    if isinstance(annotation, UnionType) or get_origin(annotation) is Union:
+        return _join_annotation_names(get_args(annotation), ' | ')
+    if isinstance(annotation, list):  # the parameters of a `Callable`
+        return f'[{_join_annotation_names(annotation, ", ")}]'
+    origin, args = get_origin(annotation), get_args(annotation)
+    if origin is not None and args:
+        return f'{get_annotation_name(origin)}[{_join_annotation_names(args, ", ")}]'
+    if isinstance(annotation, type):
+        return annotation.__name__
+    return str(annotation).replace('typing.', '')

{ddutils-0.2.2 → ddutils-0.2.4}/ddutils/class_helpers.py

@@ -1,7 +1,9 @@
 import inspect
-from collections.abc import Callable
+from collections.abc import Callable, Sized
 from typing import Any, TypeVar, get_args, get_origin
 
+from ddutils.annotation_helpers import get_annotation_name
+
 _T = TypeVar('_T', bound=Any)
 
 
@@ -45,6 +47,53 @@ def get_generic_base_argument(cls: type, generic_base: type, position: int = 0)
     return None
 
 
+def require_class_attribute(
+    cls: type,
+    name: str,
+    expected_type: type | tuple[type, ...] | None = None,
+    *,
+    allow_empty: bool = False,
+) -> Any:
+    """
+    Return a class attribute that subclasses are expected to declare, for `__init_subclass__` checks.
+
+    A base class that reads its configuration from class attributes (`topic`, `bootstrap_servers`,
+    `serializer`, ...) wants a wrong or forgotten declaration to fail at class definition, with the
+    attribute and the class named, rather than deep inside the first call that uses it.
+
+    Args:
+        cls: The class being defined, as passed to `__init_subclass__`.
+        name: The attribute name.
+        expected_type: A class or tuple of classes the value must be an instance of; `None` skips the check.
+        allow_empty: Accept an empty value (`''`, `[]`, `{}`, ...). Numbers are never "empty", so `0` passes.
+
+    Raises:
+        AttributeError: The attribute is missing or `None`, or empty unless `allow_empty`.
+        TypeError: The value is not an instance of `expected_type`.
+
+    Example:
+        class BaseConsumer:
+            topic: ClassVar[str]
+            batch_size: ClassVar[int] = 100
+
+            def __init_subclass__(cls, **kwargs):
+                super().__init_subclass__(**kwargs)
+                require_class_attribute(cls, 'topic', str)
+                require_class_attribute(cls, 'batch_size', int)
+    """
+    value = getattr(cls, name, None)
+    if value is None:
+        raise AttributeError(f'`{name}` class attribute of {cls.__name__} must be set')
+    if not allow_empty and isinstance(value, Sized) and len(value) == 0:
+        raise AttributeError(f'`{name}` class attribute of {cls.__name__} must not be empty')
+    if expected_type is not None and not isinstance(value, expected_type):
+        raise TypeError(
+            f'`{name}` class attribute of {cls.__name__} must be {get_annotation_name(expected_type)}, '
+            f'got {type(value).__name__}'
+        )
+    return value
+
+
 class classproperty:  # noqa: N801
     """
     A descriptor that defines a read-only property at the class level.

{ddutils-0.2.2 → ddutils-0.2.4}/ddutils/convertors.py

@@ -1,5 +1,7 @@
 from datetime import timedelta
-from typing import Protocol
+from typing import Any, Protocol
+
+from ddutils.value_helpers import get_builtin_base_type, unwrap_enum
 
 
 class ClassInstanceWithDict(Protocol):
@@ -21,3 +23,12 @@ def convert_to_repr(obj: ClassInstanceWithDict) -> str:
 
 def convert_timedelta_to_milliseconds(delta: timedelta) -> int:
     return int(delta.total_seconds() * 1000)
+
+
+def convert_to_builtin(value: Any) -> bool | int | float | str | bytes:
+    """
+    Cast a value to its builtin base type (see `get_builtin_base_type`): a `str` subclass becomes a plain `str`,
+    an `Enum` member becomes its `.value` cast the same way. Raises `TypeError` for a value without a builtin base.
+    """
+    value = unwrap_enum(value)
+    return get_builtin_base_type(value)(value)

ddutils-0.2.4/ddutils/value_helpers.py

@@ -0,0 +1,30 @@
+from collections.abc import Sequence
+from enum import Enum
+from typing import Any
+
+from ddutils.annotation_helpers import NON_COMPLEX_SEQUENCE_TYPES
+
+# `bool` goes before `int` because `bool` is a subclass of `int`
+BUILTIN_BASE_TYPES = (bool, int, float, str, bytes)
+
+
+def unwrap_enum(value: Any) -> Any:
+    return value.value if isinstance(value, Enum) else value
+
+
+def get_builtin_base_type(value: Any) -> type:
+    """
+    Return the builtin type a value should be treated as, looking past subclasses: `bool`, `int`, `float`, `str`
+    or `bytes`. An `Enum` member is looked at through its `.value`. Raises `TypeError` for any other value.
+    """
+    value = unwrap_enum(value)
+    for base_type in BUILTIN_BASE_TYPES:
+        if isinstance(value, base_type):
+            return base_type
+
+    raise TypeError(f'Value of type `{type(value).__name__}` has no builtin base type')
+
+
+def is_complex_sequence_value(value: Any) -> bool:
+    """Return whether a value is a sequence other than `str`, `bytes` or `bytearray`; subclasses are handled."""
+    return isinstance(value, Sequence) and not isinstance(value, NON_COMPLEX_SEQUENCE_TYPES)

{ddutils-0.2.2 → ddutils-0.2.4}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ddutils"
 description = "Domain Driven Utils Library"
-version = "0.2.2"
+version = "0.2.4"
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"

{ddutils-0.2.2 → ddutils-0.2.4}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "ddutils"
 description = "Domain Driven Utils Library"
-version = "0.2.2"
+version = "0.2.4"
 authors = [{ name = "davyddd" }]
 license = "MIT"
 license-files = ["LICENSE"]