structured_data.adt._all_annotations() - Code Metrics - Inspection of "Factor out tricky iteration logic" - mwchase/python-structured-data - Measure and Improve Code Quality continuously with Scrutinizer

Passed

Push — master ( c60240...1e4141 )

by Max

created 2019-08-26 11:01 UTC

structured_data.adt._all_annotations() A

↳ Parent: structured_data.adt

Complexity

Conditions

Size

Total Lines	6
Code Lines	5

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	3
eloc	5
nop	1
dl	0
loc	6
rs	10
c	0
b	0
f	0

"""Class decorator for defining abstract data types.

This module provides two public members, which are used together.

Given a structure, possibly a choice of different structures, that you'd like
to associate with a type:

- First, create a class, that subclasses the Sum class.
- Then, for each possible structure, add an attribute annotation to the class
  with the desired name of the constructor, and a type of ``Ctor``, with the
  types within the constructor as arguments.

To look inside an ADT instance, use the functions from the
:mod:`structured_data.match` module.

Putting it together:

>>> from structured_data import match
>>> class Example(Sum):
...     FirstConstructor: Ctor[int, str]
...     SecondConstructor: Ctor[bytes]
...     ThirdConstructor: Ctor
...     def __iter__(self):
...         matchable = match.Matchable(self)
...         if matchable(Example.FirstConstructor(match.pat.count, match.pat.string)):
...             count, string = matchable[match.pat.count, match.pat.string]
...             for _ in range(count):
...                 yield string
...         elif matchable(Example.SecondConstructor(match.pat.bytes)):
...             bytes_ = matchable[match.pat.bytes]
...             for byte in bytes_:
...                 yield chr(byte)
...         elif matchable(Example.ThirdConstructor()):
...             yield "Third"
...             yield "Constructor"
>>> list(Example.FirstConstructor(5, "abc"))
['abc', 'abc', 'abc', 'abc', 'abc']
>>> list(Example.SecondConstructor(b"abc"))
['a', 'b', 'c']
>>> list(Example.ThirdConstructor())
['Third', 'Constructor']
"""

import inspect
import sys
import typing

from ._adt_constructor import ADTConstructor
from ._adt_constructor import make_constructor
from ._ctor import get_args
from ._prewritten_methods import SUBCLASS_ORDER
from ._prewritten_methods import PrewrittenProductMethods
from ._prewritten_methods import PrewrittenSumMethods

_T = typing.TypeVar("_T")


if typing.TYPE_CHECKING:  # pragma: nocover

    class Ctor:
        """Dummy class for type-checking purposes."""

    class ConcreteCtor(typing.Generic[_T]):
        """Wrapper class for type-checking purposes.

        The type parameter should be a Tuple type of fixed size.
        Classes containing this annotation (meaning they haven't been
        processed by the ``adt`` decorator) should not be instantiated.
        """


else:
    from ._ctor import Ctor


def _name(cls: typing.Type[_T], function) -> str:
    """Return the name of a function accessed through a descriptor."""
    return function.__get__(None, cls).__name__


def _set_new_functions(cls: typing.Type[_T], *functions) -> typing.Optional[str]:
    """Attempt to set the attributes corresponding to the functions on cls.

    If any attributes are already defined, fail *before* setting any, and
    return the already-defined name.
    """
    for function in functions:
        name = _name(cls, function)
        if getattr(object, name, None) is not getattr(cls, name, None):
            return name
    for function in functions:
        setattr(cls, _name(cls, function), function)
    return None


def _sum_super(_cls: typing.Type[_T]):
    def base(cls, args):
        return super(_cls, cls).__new__(cls, args)

    return staticmethod(base)


def _make_nested_new(_cls: typing.Type[_T], subclasses, base__new__):
    def __new__(cls, args):
        if cls not in subclasses:
            raise TypeError
        return base__new__.__get__(None, cls)(cls, args)

    return staticmethod(__new__)


_K = typing.TypeVar("_K")
_V = typing.TypeVar("_V")


def _nillable_write(dct: typing.Dict[_K, _V], key: _K, value: typing.Optional[_V]):
    if value is None:
        dct.pop(key, typing.cast(_V, None))
    else:
        dct[key] = value


def _add_methods(cls: typing.Type[_T], do_set, *methods):
    methods_were_set = False
    if do_set:
        methods_were_set = not _set_new_functions(cls, *methods)
    return methods_were_set


def _set_hash(cls: typing.Type[_T], set_hash, src):
    if set_hash:
        cls.__hash__ = src.__hash__  # type: ignore


def _add_order(cls: typing.Type[_T], set_order, equality_methods_were_set, src):
    if set_order:
        if not equality_methods_were_set:
            raise ValueError(
                "Can't add ordering methods if equality methods are provided."
            )
        collision = _set_new_functions(
            cls, src.__lt__, src.__le__, src.__gt__, src.__ge__
        )
        if collision:
            raise TypeError(
                "Cannot overwrite attribute {collision} in class "
                "{name}. Consider using functools.total_ordering".format(
                    collision=collision, name=cls.__name__
                )
            )


def _sum_new(cls: typing.Type[_T], subclasses):
    new = cls.__dict__.get("__new__", _sum_super(cls))
    cls.__new__ = _make_nested_new(cls, subclasses, new)  # type: ignore


_SENTINEL = object()


def _product_new(
    _cls: typing.Type[_T],
    annotations: typing.Dict[str, typing.Any],
    defaults: typing.Dict[str, typing.Any],
):
    def __new__(*args, **kwargs):
        cls, *args = args
        return super(_cls, cls).__new__(cls, *args, **kwargs)

    __new__.__signature__ = inspect.signature(__new__).replace(
        parameters=[inspect.Parameter("cls", inspect.Parameter.POSITIONAL_ONLY)]
        + [
            inspect.Parameter(
                field,
                inspect.Parameter.POSITIONAL_OR_KEYWORD,
                annotation=annotation,
                default=defaults.get(field, inspect.Parameter.empty),
            )
            for (field, annotation) in annotations.items()
        ]
    )
    _cls.__new__ = __new__


def _all_annotations(
    cls: typing.Type[_T]
) -> typing.Iterator[typing.Tuple[typing.Type[_T], str, typing.Any]]:
    for superclass in reversed(cls.__mro__):
        for key, value in vars(superclass).get("__annotations__", {}).items():
            yield (superclass, key, value)


def _sum_args_from_annotations(cls: typing.Type[_T]) -> typing.Dict[str, typing.Tuple]:
    args: typing.Dict[str, typing.Tuple] = {}
    for superclass, key, value in _all_annotations(cls):
        _nillable_write(
            args, key, get_args(value, vars(sys.modules[superclass.__module__]))
        )
    return args


def _product_args_from_annotations(
    cls: typing.Type[_T]
) -> typing.Dict[str, typing.Any]:
    args: typing.Dict[str, typing.Any] = {}
    for superclass, key, value in _all_annotations(cls):
        if value == "None":
            value = None
        _nillable_write(args, key, value)
    return args


def _tuple_getter(index: int):
    # TODO: __name__ and __qualname__
    @property
    def getter(self):
        return tuple.__getitem__(self, index)

    return getter


def _process_class(_cls: typing.Type[_T], _repr, eq, order) -> typing.Type[_T]:
    if order and not eq:
        raise ValueError("eq must be true if order is true")

    subclass_order: typing.List[typing.Type[_T]] = []

    for name, args in _sum_args_from_annotations(_cls).items():
        make_constructor(_cls, name, args, subclass_order)

    SUBCLASS_ORDER[_cls] = tuple(subclass_order)

    _cls.__init_subclass__ = PrewrittenSumMethods.__init_subclass__  # type: ignore

    _sum_new(_cls, frozenset(subclass_order))

    _set_new_functions(
        _cls, PrewrittenSumMethods.__setattr__, PrewrittenSumMethods.__delattr__
    )
    _set_new_functions(_cls, PrewrittenSumMethods.__bool__)

    _add_methods(_cls, _repr, PrewrittenSumMethods.__repr__)

    equality_methods_were_set = _add_methods(
        _cls, eq, PrewrittenSumMethods.__eq__, PrewrittenSumMethods.__ne__
    )

    _set_hash(_cls, equality_methods_were_set, PrewrittenSumMethods)

    _add_order(_cls, order, equality_methods_were_set, PrewrittenSumMethods)

    return _cls


class Sum:
    """Base class of classes with disjoint constructors.

    Examines PEP 526 __annotations__ to determine subclasses.

    If repr is true, a __repr__() method is added to the class.
    If order is true, rich comparison dunder methods are added.

    The Sum class examines the class to find Ctor annotations.
    A Ctor annotation is the adt.Ctor class itself, or the result of indexing
    the class, either with a single type hint, or a tuple of type hints.
    All other annotations are ignored.

    The subclass is not subclassable, but has subclasses at each of the
    names that had Ctor annotations. Each subclass takes a fixed number of
    arguments, corresponding to the type hints given to its annotation, if any.
    """

    __slots__ = ()

    def __init_subclass__(cls, *, repr=True, eq=True, order=False, **kwargs):
        super().__init_subclass__(**kwargs)
        if not issubclass(cls, ADTConstructor):
            _process_class(cls, repr, eq, order)


class Product(ADTConstructor, tuple):

    __slots__ = ()

    def __new__(*args, **kwargs):
        cls, *args = args
        values = cls.__defaults.copy()
        fields_iter = iter(cls.__annotations)
        for arg, field in zip(args, fields_iter):
            values[field] = arg
        for field in fields_iter:
            if field in values and field not in kwargs:
                continue
            values[field] = kwargs.pop(field)
        if kwargs:
            raise TypeError(kwargs)
        return super(Product, cls).__new__(
            cls, [values[field] for field in cls.__annotations]
        )

    def __init_subclass__(cls, *, repr=True, eq=True, order=False, **kwargs):
        super().__init_subclass__(**kwargs)
        if "__annotations__" not in vars(cls):
            return
        if order and not eq:
            raise ValueError("eq must be true if order is true")

        cls.__annotations = _product_args_from_annotations(cls)

        cls.__defaults = {}
        field_names = iter(reversed(tuple(cls.__annotations)))
        for field in field_names:
            default = getattr(cls, field, _SENTINEL)
            if default is _SENTINEL:
                break
            cls.__defaults[field] = default
        for field in field_names:
            if getattr(cls, field, _SENTINEL) is not _SENTINEL:
                raise TypeError

        _product_new(cls, cls.__annotations, cls.__defaults)

        for index, field in enumerate(cls.__annotations):
            setattr(cls, field, _tuple_getter(index))

        _set_new_functions(
            cls,
            PrewrittenProductMethods.__setattr__,
            PrewrittenProductMethods.__delattr__,
        )
        _set_new_functions(cls, PrewrittenProductMethods.__bool__)

        _add_methods(cls, repr, PrewrittenProductMethods.__repr__)

        equality_methods_were_set = _add_methods(
            cls, eq, PrewrittenProductMethods.__eq__, PrewrittenProductMethods.__ne__
        )

        _set_hash(cls, equality_methods_were_set, PrewrittenProductMethods)

        _add_order(cls, order, equality_methods_were_set, PrewrittenProductMethods)


__all__ = ["Ctor", "Product", "Sum"]


1			"""Class decorator for defining abstract data types.
2
3			This module provides two public members, which are used together.
4
5			Given a structure, possibly a choice of different structures, that you'd like
6			to associate with a type:
7
8			- First, create a class, that subclasses the Sum class.
9			- Then, for each possible structure, add an attribute annotation to the class
10			with the desired name of the constructor, and a type of ``Ctor``, with the
11			types within the constructor as arguments.
12
13			To look inside an ADT instance, use the functions from the
14			:mod:`structured_data.match` module.
15
16			Putting it together:
17
18			>>> from structured_data import match
19			>>> class Example(Sum):
20			... FirstConstructor: Ctor[int, str]
21			... SecondConstructor: Ctor[bytes]
22			... ThirdConstructor: Ctor
23			... def __iter__(self):
24			... matchable = match.Matchable(self)
25			... if matchable(Example.FirstConstructor(match.pat.count, match.pat.string)):
26			... count, string = matchable[match.pat.count, match.pat.string]
27			... for _ in range(count):
28			... yield string
29			... elif matchable(Example.SecondConstructor(match.pat.bytes)):
30			... bytes_ = matchable[match.pat.bytes]
31			... for byte in bytes_:
32			... yield chr(byte)
33			... elif matchable(Example.ThirdConstructor()):
34			... yield "Third"
35			... yield "Constructor"
36			>>> list(Example.FirstConstructor(5, "abc"))
37			['abc', 'abc', 'abc', 'abc', 'abc']
38			>>> list(Example.SecondConstructor(b"abc"))
39			['a', 'b', 'c']
40			>>> list(Example.ThirdConstructor())
41			['Third', 'Constructor']
42			"""
43
44			import inspect
45			import sys
46			import typing
47
48			from ._adt_constructor import ADTConstructor
49			from ._adt_constructor import make_constructor
50			from ._ctor import get_args
51			from ._prewritten_methods import SUBCLASS_ORDER
52			from ._prewritten_methods import PrewrittenProductMethods
53			from ._prewritten_methods import PrewrittenSumMethods
54
55			_T = typing.TypeVar("_T")
56
57
58			if typing.TYPE_CHECKING: # pragma: nocover
59
60			class Ctor:
61			"""Dummy class for type-checking purposes."""
62
63			class ConcreteCtor(typing.Generic[_T]):
64			"""Wrapper class for type-checking purposes.
65
66			The type parameter should be a Tuple type of fixed size.
67			Classes containing this annotation (meaning they haven't been
68			processed by the ``adt`` decorator) should not be instantiated.
69			"""
70
71
72			else:
73			from ._ctor import Ctor
74
75
76			def _name(cls: typing.Type[_T], function) -> str:
77			"""Return the name of a function accessed through a descriptor."""
78			return function.__get__(None, cls).__name__
79
80
81			def _set_new_functions(cls: typing.Type[_T], *functions) -> typing.Optional[str]:
82			"""Attempt to set the attributes corresponding to the functions on cls.
83
84			If any attributes are already defined, fail before setting any, and
85			return the already-defined name.
86			"""
87			for function in functions:
88			name = _name(cls, function)
89			if getattr(object, name, None) is not getattr(cls, name, None):
90			return name
91			for function in functions:
92			setattr(cls, _name(cls, function), function)
93			return None
94
95
96			def _sum_super(_cls: typing.Type[_T]):
97			def base(cls, args):
98			return super(_cls, cls).__new__(cls, args)
99
100			return staticmethod(base)
101
102
103			def _make_nested_new(_cls: typing.Type[_T], subclasses, base__new__):
104			def __new__(cls, args):
105			if cls not in subclasses:
106			raise TypeError
107			return base__new__.__get__(None, cls)(cls, args)
108
109			return staticmethod(__new__)
110
111
112			_K = typing.TypeVar("_K")
113			_V = typing.TypeVar("_V")
114
115
116			def _nillable_write(dct: typing.Dict[_K, _V], key: _K, value: typing.Optional[_V]):
117			if value is None:
118			dct.pop(key, typing.cast(_V, None))
119			else:
120			dct[key] = value
121
122
123			def _add_methods(cls: typing.Type[_T], do_set, *methods):
124			methods_were_set = False
125			if do_set:
126			methods_were_set = not _set_new_functions(cls, *methods)
127			return methods_were_set
128
129
130			def _set_hash(cls: typing.Type[_T], set_hash, src):
131			if set_hash:
132			cls.__hash__ = src.__hash__ # type: ignore
133
134
135			def _add_order(cls: typing.Type[_T], set_order, equality_methods_were_set, src):
136			if set_order:
137			if not equality_methods_were_set:
138			raise ValueError(
139			"Can't add ordering methods if equality methods are provided."
140			)
141			collision = _set_new_functions(
142			cls, src.__lt__, src.__le__, src.__gt__, src.__ge__
143			)
144			if collision:
145			raise TypeError(
146			"Cannot overwrite attribute {collision} in class "
147			"{name}. Consider using functools.total_ordering".format(
148			collision=collision, name=cls.__name__
149			)
150			)
151
152
153			def _sum_new(cls: typing.Type[_T], subclasses):
154			new = cls.__dict__.get("__new__", _sum_super(cls))
155			cls.__new__ = _make_nested_new(cls, subclasses, new) # type: ignore
156
157
158			_SENTINEL = object()
159
160
161			def _product_new(
162			_cls: typing.Type[_T],
163			annotations: typing.Dict[str, typing.Any],
164			defaults: typing.Dict[str, typing.Any],
165			):
166			def __new__(args, *kwargs):
167			cls, *args = args
168			return super(_cls, cls).__new__(cls, args, *kwargs)
169
170			__new__.__signature__ = inspect.signature(__new__).replace(
171			parameters=[inspect.Parameter("cls", inspect.Parameter.POSITIONAL_ONLY)]
172			+ [
173			inspect.Parameter(
174			field,
175			inspect.Parameter.POSITIONAL_OR_KEYWORD,
176			annotation=annotation,
177			default=defaults.get(field, inspect.Parameter.empty),
178			)
179			for (field, annotation) in annotations.items()
180			]
181			)
182			_cls.__new__ = __new__
183
184
185			def _all_annotations(
186			cls: typing.Type[_T]
187			) -> typing.Iterator[typing.Tuple[typing.Type[_T], str, typing.Any]]:
188			for superclass in reversed(cls.__mro__):
189			for key, value in vars(superclass).get("__annotations__", {}).items():
190			yield (superclass, key, value)
191
192
193			def _sum_args_from_annotations(cls: typing.Type[_T]) -> typing.Dict[str, typing.Tuple]:
194			args: typing.Dict[str, typing.Tuple] = {}
195			for superclass, key, value in _all_annotations(cls):
196			_nillable_write(
197			args, key, get_args(value, vars(sys.modules[superclass.__module__]))
198			)
199			return args
200
201
202			def _product_args_from_annotations(
203			cls: typing.Type[_T]
204			) -> typing.Dict[str, typing.Any]:
205			args: typing.Dict[str, typing.Any] = {}
206			for superclass, key, value in _all_annotations(cls):
207			if value == "None":
208			value = None
209			_nillable_write(args, key, value)
210			return args
211
212
213			def _tuple_getter(index: int):
214			# TODO: __name__ and __qualname__
215			@property
216			def getter(self):
217			return tuple.__getitem__(self, index)
218
219			return getter
220
221
222			def _process_class(_cls: typing.Type[_T], _repr, eq, order) -> typing.Type[_T]:
223			if order and not eq:
224			raise ValueError("eq must be true if order is true")
225
226			subclass_order: typing.List[typing.Type[_T]] = []
227
228			for name, args in _sum_args_from_annotations(_cls).items():
229			make_constructor(_cls, name, args, subclass_order)
230
231			SUBCLASS_ORDER[_cls] = tuple(subclass_order)
232
233			_cls.__init_subclass__ = PrewrittenSumMethods.__init_subclass__ # type: ignore
234
235			_sum_new(_cls, frozenset(subclass_order))
236
237			_set_new_functions(
238			_cls, PrewrittenSumMethods.__setattr__, PrewrittenSumMethods.__delattr__
239			)
240			_set_new_functions(_cls, PrewrittenSumMethods.__bool__)
241
242			_add_methods(_cls, _repr, PrewrittenSumMethods.__repr__)
243
244			equality_methods_were_set = _add_methods(
245			_cls, eq, PrewrittenSumMethods.__eq__, PrewrittenSumMethods.__ne__
246			)
247
248			_set_hash(_cls, equality_methods_were_set, PrewrittenSumMethods)
249
250			_add_order(_cls, order, equality_methods_were_set, PrewrittenSumMethods)
251
252			return _cls
253
254
255			class Sum:
256			"""Base class of classes with disjoint constructors.
257
258			Examines PEP 526 __annotations__ to determine subclasses.
259
260			If repr is true, a __repr__() method is added to the class.
261			If order is true, rich comparison dunder methods are added.
262
263			The Sum class examines the class to find Ctor annotations.
264			A Ctor annotation is the adt.Ctor class itself, or the result of indexing
265			the class, either with a single type hint, or a tuple of type hints.
266			All other annotations are ignored.
267
268			The subclass is not subclassable, but has subclasses at each of the
269			names that had Ctor annotations. Each subclass takes a fixed number of
270			arguments, corresponding to the type hints given to its annotation, if any.
271			"""
272
273			__slots__ = ()
274
275			def __init_subclass__(cls, , repr=True, eq=True, order=False, *kwargs):
276			super().__init_subclass__(**kwargs)
277			if not issubclass(cls, ADTConstructor):
278			_process_class(cls, repr, eq, order)
279
280
281			class Product(ADTConstructor, tuple):
282
283			__slots__ = ()
284
285			def __new__(args, *kwargs):
286			cls, *args = args
287			values = cls.__defaults.copy()
288			fields_iter = iter(cls.__annotations)
289			for arg, field in zip(args, fields_iter):
290			values[field] = arg
291			for field in fields_iter:
292			if field in values and field not in kwargs:
293			continue
294			values[field] = kwargs.pop(field)
295			if kwargs:
296			raise TypeError(kwargs)
297			return super(Product, cls).__new__(
298			cls, [values[field] for field in cls.__annotations]
299			)
300
301			def __init_subclass__(cls, , repr=True, eq=True, order=False, *kwargs):
302			super().__init_subclass__(**kwargs)
303			if "__annotations__" not in vars(cls):
304			return
305			if order and not eq:
306			raise ValueError("eq must be true if order is true")
307
308			cls.__annotations = _product_args_from_annotations(cls)
309
310			cls.__defaults = {}
311			field_names = iter(reversed(tuple(cls.__annotations)))
312			for field in field_names:
313			default = getattr(cls, field, _SENTINEL)
314			if default is _SENTINEL:
315			break
316			cls.__defaults[field] = default
317			for field in field_names:
318			if getattr(cls, field, _SENTINEL) is not _SENTINEL:
319			raise TypeError
320
321			_product_new(cls, cls.__annotations, cls.__defaults)
322
323			for index, field in enumerate(cls.__annotations):
324			setattr(cls, field, _tuple_getter(index))
325
326			_set_new_functions(
327			cls,
328			PrewrittenProductMethods.__setattr__,
329			PrewrittenProductMethods.__delattr__,
330			)
331			_set_new_functions(cls, PrewrittenProductMethods.__bool__)
332
333			_add_methods(cls, repr, PrewrittenProductMethods.__repr__)
334
335			equality_methods_were_set = _add_methods(
336			cls, eq, PrewrittenProductMethods.__eq__, PrewrittenProductMethods.__ne__
337			)
338
339			_set_hash(cls, equality_methods_were_set, PrewrittenProductMethods)
340
341			_add_order(cls, order, equality_methods_were_set, PrewrittenProductMethods)
342
343
344			__all__ = ["Ctor", "Product", "Sum"]
345

mwchase / python-structured-data

Push — master ( c60240...1e4141 )

structured_data.adt._all_annotations() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like