7032134530

Committed 29 Nov 2023 11:52AM UTC coverage: 87.401% (-0.002%) from 87.403%

Build # 7032134530

Build Type

push

github

Committed by

Christian-B

Commit Message

added required import

Run Details

1369 of 1685 branches covered (0.0%)

Branch coverage included in aggregate %.

1 of 1 new or added line in 1 file covered. (100.0%)

19 existing lines in 2 files now uncovered.

3369 of 3736 relevant lines covered (90.18%)

0.9 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

67.74

/spinn_utilities/overrides.py

# Copyright (c) 2017 The University of Manchester
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import inspect
from types import FunctionType, MethodType
from typing import (Any, Callable, get_type_hints,
                    Iterable, Optional, TypeVar)
#: :meta private:
Method = TypeVar("Method", bound=Callable[..., Any])


class overrides(object):
    """
    A decorator for indicating that a method overrides another method in
    a superclass.  This checks that the method does actually exist,
    copies the doc-string for the method, and enforces that the method
    overridden is specified, making maintenance easier.
    """

    # This near constant is changed by a few unittests to check our code
    # TODO default to False
    _MATCH_ALL = True

    __slots__ = [
        # The method in the superclass that this method overrides
        "_superclass_method",
        # True if the doc string is to be extended, False to set if not set
        "_extend_doc",
        # Any additional arguments required by the subclass method
        "_additional_arguments",
        # True if the subclass method may have additional defaults
        "_extend_defaults",
        # True if the name check is relaxed
        "_relax_name_check",
        # The name of the thing being overridden for error messages
        "_override_name",
        # True if this method adds typing info not in the original
        "_adds_typing",
        # True if this method has a return Type narrower than the super
        "_return_narrowing"
    ]

    def __init__(
            self, super_class_method, extend_doc: bool = True,
            additional_arguments: Optional[Iterable[str]] = None,
            extend_defaults: bool = False, adds_typing: bool = False,
            return_narrowing: bool = False):
        """
        :param super_class_method: The method to override in the superclass
        :param bool extend_doc:
            True the method doc string should be appended to the super-method
            doc string, False if the documentation should be set to the
            super-method doc string only if there isn't a doc string already
        :param iterable(str) additional_arguments:
            Additional arguments taken by the subclass method over the
            superclass method, e.g., that are to be injected
        :param bool extend_defaults:
            Whether the subclass may specify extra defaults for the parameters
        :param adds_typing:
            Allows more typing (of non additional) than in the subclass.
            Should only be used for builtin super classes
        :param return_narrowing:
            Declares that the return may be narrower than the super.
            Only needed if one of the types can not be imported (circular)
        """
        if isinstance(super_class_method, property):
            super_class_method = super_class_method.fget
        if not isinstance(super_class_method, (FunctionType, MethodType)):
            raise TypeError("may only decorate method declarations; "
                            f"this is a {type(super_class_method)}")
        self._superclass_method = super_class_method
        self._extend_doc = bool(extend_doc)
        self._extend_defaults = bool(extend_defaults)
        self._relax_name_check = False
        self._override_name = "super class method"
        if additional_arguments is not None:
            self._additional_arguments = frozenset(additional_arguments)
        else:
            self._additional_arguments = frozenset()
        self._adds_typing = adds_typing
        self._return_narrowing = return_narrowing

    @staticmethod
    def __match_defaults(default_args, super_defaults, extend_ok):
        if default_args is None:
            return super_defaults is None
        elif super_defaults is None:
            return extend_ok
        if extend_ok:
            return len(default_args) >= len(super_defaults)
        return len(default_args) == len(super_defaults)

    def __verify_method_arguments(self, method: Method):
        """
        Check that the arguments match.
        """
        method_args = inspect.getfullargspec(method)
        super_args = inspect.getfullargspec(self._superclass_method)
        all_args = [
            arg for arg in method_args.args
            if arg not in self._additional_arguments]
        default_args = None
        if method_args.defaults is not None:
            default_args = [
                arg for arg in method_args.defaults
                if arg not in self._additional_arguments]
        if len(all_args) != len(super_args.args):
            raise AttributeError(
                f"Method has {len(method_args.args)} arguments but "
                f"{self._override_name} has {len(super_args.args)} arguments")
        for arg, super_arg in zip(all_args, super_args.args):
            if arg != super_arg:
                raise AttributeError(f"Missing argument {super_arg}")
        if not self.__match_defaults(
                default_args, super_args.defaults, self._extend_defaults):
            raise AttributeError(
                f"Default arguments don't match {self._override_name}")

    def __is_similar_type(self, method_type, super_type, arg):
        # easiest case they are the same
        if method_type == super_type:
            return True

        try:
            return issubclass(method_type, super_type)
        except TypeError:
            # print(f"Unable to subtype {super_type} {type(super_type)} "
            #       f"for {arg}")
            pass

        # If either came from annotations
        if isinstance(method_type, str) or isinstance(super_type, str):
            # convert types to str
            if isinstance(method_type, type):
                method_type = method_type.__name__
            if isinstance(super_type, type):
                super_type = super_type.__name__
            # hopefully they are equal now
            if method_type == super_type:
                return True
            if arg == "return":
                if self._return_narrowing:
                    return True
                # Checking subclass would need a list of subtype to super type
                raise AttributeError(
                    f"Detected possible return type narrowing for "
                    f"{self._override_name}. "
                    f"{method_type} while super is typed as {super_type}. "
                    f"this can not be checked due to none imported types.  "
                    f"If narrowing mark @overrides as return_narrowing")
            else:
                raise AttributeError(
                    f"Method {self._override_name} has {arg} typed as "
                    f"{method_type} while super is typed as {super_type}. "
                    f"For not imported types they must be exactly the same")

        # Assuming typeVar or generic typing is used.
        # No way to check subtypes for these has been found
        if arg == "return":
            if self._return_narrowing:
                return True
            raise AttributeError(
                f"Detected possible return type narrowing in "
                f"{self._override_name}. If they should be the same use type "
                f"imported from the super if they are different "
                f"mark @overrides as return_narrowing")
        else:
            raise AttributeError(
                f"Method {self._override_name} has {arg} typed as "
                f"{method_type} while super is typed as {super_type}. "
                f"For generic types use type imported from the super")

    def __verify_method_types(self, method: Method):
        try:
            method_types = get_type_hints(method)
        except NameError:
            # This happens if the Type can not be imported (circular)
            method_types = inspect.getfullargspec(method).annotations
        try:
            super_types = get_type_hints(self._superclass_method)
        except NameError:
            super_types = inspect.getfullargspec(
                self._superclass_method).annotations

        if self._adds_typing:
            for arg in super_types:
                if method_types[arg] != super_types[arg]:
                    raise AttributeError(
                        f"Method {self._override_name} has {arg} "
                        f"typed as {method_types[arg]} "
                        f"while super has {super_types[arg]}")
            return

        all_types = [
            arg for arg in method_types
            if arg not in self._additional_arguments]

        if self._MATCH_ALL and len(all_types) != len(super_types):
            raise AttributeError(
                f"Method has {len(method_types)} typed arguments but "
                f"{self._override_name} has {len(super_types)}")

        for arg in all_types:
            if arg in super_types:
                if not self.__is_similar_type(
                        method_types[arg], super_types[arg], arg):
                    raise AttributeError(
                        f"Method {self._override_name} has {arg} typed as "
                        f"{method_types[arg]} "
                        f"while super has {super_types[arg]}")
            elif self._MATCH_ALL:
                raise AttributeError(
                    f"Method {self._override_name} has {arg} typed as "
                    f"{method_types[arg]} while super does not type it. "
                    f"If you can type the super "
                    f"if not mark @overrides as adds_typing")
            else:
                print("here")

    def __call__(self, method: Method) -> Method:
        """
        Apply the decorator to the given method.
        """
        # Check and fail if this is a property
        if isinstance(method, property):
            raise AttributeError(
                f"Please ensure that the {self.__class__.__name__} decorator "
                "is the last decorator before the method declaration")

        # Check that the name matches
        if (not self._relax_name_check and
                method.__name__ != self._superclass_method.__name__):
            raise AttributeError(
                f"{self._override_name} name "
                f"{self._superclass_method.__name__} does not match "
                f"{method.__name__}. Ensure {self.__class__.__name__} is the "
                "last decorator before the method declaration")

        # Check that the arguments match (except for __init__ as this might
        # take extra arguments or pass arguments not specified)
        if method.__name__ != "__init__":
            self.__verify_method_arguments(method)
            self.__verify_method_types(method)

        if (self._superclass_method.__doc__ is not None and
                method.__doc__ is None):
            method.__doc__ = self._superclass_method.__doc__
        elif (self._extend_doc and
                self._superclass_method.__doc__ is not None):
            method.__doc__ = (
                self._superclass_method.__doc__ + (method.__doc__ or ""))
        return method

    @classmethod
    def set_matchall(cls):
        cls._MATCH_ALL = True

1	# Copyright (c) 2017 The University of Manchester
2	#
3	# Licensed under the Apache License, Version 2.0 (the "License");
4	# you may not use this file except in compliance with the License.
5	# You may obtain a copy of the License at
6	#
7	# https://www.apache.org/licenses/LICENSE-2.0
8	#
9	# Unless required by applicable law or agreed to in writing, software
10	# distributed under the License is distributed on an "AS IS" BASIS,
11	# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12	# See the License for the specific language governing permissions and
13	# limitations under the License.
14
15	import inspect	1✔
16	from types import FunctionType, MethodType	1✔
17	from typing import (Any, Callable, get_type_hints,	1✔
18	Iterable, Optional, TypeVar)
19	#: :meta private:
20	Method = TypeVar("Method", bound=Callable[..., Any])	1✔
21
22
23	class overrides(object):	1✔
24	"""
25	A decorator for indicating that a method overrides another method in
26	a superclass. This checks that the method does actually exist,
27	copies the doc-string for the method, and enforces that the method
28	overridden is specified, making maintenance easier.
29	"""
30
31	# This near constant is changed by a few unittests to check our code
32	# TODO default to False
33	_MATCH_ALL = True	1✔
34
35	__slots__ = [	1✔
36	# The method in the superclass that this method overrides
37	"_superclass_method",
38	# True if the doc string is to be extended, False to set if not set
39	"_extend_doc",
40	# Any additional arguments required by the subclass method
41	"_additional_arguments",
42	# True if the subclass method may have additional defaults
43	"_extend_defaults",
44	# True if the name check is relaxed
45	"_relax_name_check",
46	# The name of the thing being overridden for error messages
47	"_override_name",
48	# True if this method adds typing info not in the original
49	"_adds_typing",
50	# True if this method has a return Type narrower than the super
51	"_return_narrowing"
52	]
53
54	def __init__(	1✔
55	self, super_class_method, extend_doc: bool = True,
56	additional_arguments: Optional[Iterable[str]] = None,
57	extend_defaults: bool = False, adds_typing: bool = False,
58	return_narrowing: bool = False):
59	"""
60	:param super_class_method: The method to override in the superclass
61	:param bool extend_doc:
62	True the method doc string should be appended to the super-method
63	doc string, False if the documentation should be set to the
64	super-method doc string only if there isn't a doc string already
65	:param iterable(str) additional_arguments:
66	Additional arguments taken by the subclass method over the
67	superclass method, e.g., that are to be injected
68	:param bool extend_defaults:
69	Whether the subclass may specify extra defaults for the parameters
70	:param adds_typing:
71	Allows more typing (of non additional) than in the subclass.
72	Should only be used for builtin super classes
73	:param return_narrowing:
74	Declares that the return may be narrower than the super.
75	Only needed if one of the types can not be imported (circular)
76	"""
77	if isinstance(super_class_method, property):	1✔
78	super_class_method = super_class_method.fget	1✔
79	if not isinstance(super_class_method, (FunctionType, MethodType)):	1!
80	raise TypeError("may only decorate method declarations; "	×
81	f"this is a {type(super_class_method)}")
82	self._superclass_method = super_class_method	1✔
83	self._extend_doc = bool(extend_doc)	1✔
84	self._extend_defaults = bool(extend_defaults)	1✔
85	self._relax_name_check = False	1✔
86	self._override_name = "super class method"	1✔
87	if additional_arguments is not None:	1✔
88	self._additional_arguments = frozenset(additional_arguments)	1✔
89	else:
90	self._additional_arguments = frozenset()	1✔
91	self._adds_typing = adds_typing	1✔
92	self._return_narrowing = return_narrowing	1✔
93
94	@staticmethod	1✔
95	def __match_defaults(default_args, super_defaults, extend_ok):	1✔
96	if default_args is None:	1✔
97	return super_defaults is None	1✔
98	elif super_defaults is None:	1✔
99	return extend_ok	1✔
100	if extend_ok:	1✔
101	return len(default_args) >= len(super_defaults)	1✔
102	return len(default_args) == len(super_defaults)	1✔
103
104	def __verify_method_arguments(self, method: Method):	1✔
105	"""
106	Check that the arguments match.
107	"""
108	method_args = inspect.getfullargspec(method)	1✔
109	super_args = inspect.getfullargspec(self._superclass_method)	1✔
110	all_args = [	1✔
111	arg for arg in method_args.args
112	if arg not in self._additional_arguments]
113	default_args = None	1✔
114	if method_args.defaults is not None:	1✔
115	default_args = [	1✔
116	arg for arg in method_args.defaults
117	if arg not in self._additional_arguments]
118	if len(all_args) != len(super_args.args):	1✔
119	raise AttributeError(	1✔
120	f"Method has {len(method_args.args)} arguments but "
121	f"{self._override_name} has {len(super_args.args)} arguments")
122	for arg, super_arg in zip(all_args, super_args.args):	1✔
123	if arg != super_arg:	1✔
124	raise AttributeError(f"Missing argument {super_arg}")	1✔
125	if not self.__match_defaults(	1✔
126	default_args, super_args.defaults, self._extend_defaults):
127	raise AttributeError(	1✔
128	f"Default arguments don't match {self._override_name}")
129
130	def __is_similar_type(self, method_type, super_type, arg):	1✔
131	# easiest case they are the same
132	if method_type == super_type:	1!
133	return True	1✔
134
135	try:	×
136	return issubclass(method_type, super_type)	×
137	except TypeError:	×
138	# print(f"Unable to subtype {super_type} {type(super_type)} "
139	# f"for {arg}")
UNCOV 140	pass	×
141
142	# If either came from annotations
UNCOV 143	if isinstance(method_type, str) or isinstance(super_type, str):	×
144	# convert types to str
145	if isinstance(method_type, type):	×
146	method_type = method_type.__name__	×
147	if isinstance(super_type, type):	×
UNCOV 148	super_type = super_type.__name__	×
149	# hopefully they are equal now
150	if method_type == super_type:	×
151	return True	×
152	if arg == "return":	×
153	if self._return_narrowing:	×
UNCOV 154	return True	×
155	# Checking subclass would need a list of subtype to super type
UNCOV 156	raise AttributeError(	×
157	f"Detected possible return type narrowing for "
158	f"{self._override_name}. "
159	f"{method_type} while super is typed as {super_type}. "
160	f"this can not be checked due to none imported types. "
161	f"If narrowing mark @overrides as return_narrowing")
162	else:
UNCOV 163	raise AttributeError(	×
164	f"Method {self._override_name} has {arg} typed as "
165	f"{method_type} while super is typed as {super_type}. "
166	f"For not imported types they must be exactly the same")
167
168	# Assuming typeVar or generic typing is used.
169	# No way to check subtypes for these has been found
170	if arg == "return":	×
171	if self._return_narrowing:	×
172	return True	×
UNCOV 173	raise AttributeError(	×
174	f"Detected possible return type narrowing in "
175	f"{self._override_name}. If they should be the same use type "
176	f"imported from the super if they are different "
177	f"mark @overrides as return_narrowing")
178	else:
UNCOV 179	raise AttributeError(	×
180	f"Method {self._override_name} has {arg} typed as "
181	f"{method_type} while super is typed as {super_type}. "
182	f"For generic types use type imported from the super")
183
184	def __verify_method_types(self, method: Method):	1✔
185	try:	1✔
186	method_types = get_type_hints(method)	1✔
UNCOV 187	except NameError:	×
188	# This happens if the Type can not be imported (circular)
UNCOV 189	method_types = inspect.getfullargspec(method).annotations	×
190	try:	1✔
191	super_types = get_type_hints(self._superclass_method)	1✔
192	except NameError:	×
UNCOV 193	super_types = inspect.getfullargspec(	×
194	self._superclass_method).annotations
195
196	if self._adds_typing:	1✔
197	for arg in super_types:	1!
198	if method_types[arg] != super_types[arg]:	×
UNCOV 199	raise AttributeError(	×
200	f"Method {self._override_name} has {arg} "
201	f"typed as {method_types[arg]} "
202	f"while super has {super_types[arg]}")
203	return	1✔
204
205	all_types = [	1✔
206	arg for arg in method_types
207	if arg not in self._additional_arguments]
208
209	if self._MATCH_ALL and len(all_types) != len(super_types):	1!
UNCOV 210	raise AttributeError(	×
211	f"Method has {len(method_types)} typed arguments but "
212	f"{self._override_name} has {len(super_types)}")
213
214	for arg in all_types:	1✔
215	if arg in super_types:	1!
216	if not self.__is_similar_type(	1!
217	method_types[arg], super_types[arg], arg):
UNCOV 218	raise AttributeError(	×
219	f"Method {self._override_name} has {arg} typed as "
220	f"{method_types[arg]} "
221	f"while super has {super_types[arg]}")
222	elif self._MATCH_ALL:	×
UNCOV 223	raise AttributeError(	×
224	f"Method {self._override_name} has {arg} typed as "
225	f"{method_types[arg]} while super does not type it. "
226	f"If you can type the super "
227	f"if not mark @overrides as adds_typing")
228	else:
UNCOV 229	print("here")	×
230
231	def __call__(self, method: Method) -> Method:	1✔
232	"""
233	Apply the decorator to the given method.
234	"""
235	# Check and fail if this is a property
236	if isinstance(method, property):	1✔
237	raise AttributeError(	1✔
238	f"Please ensure that the {self.__class__.__name__} decorator "
239	"is the last decorator before the method declaration")
240
241	# Check that the name matches
242	if (not self._relax_name_check and	1✔
243	method.__name__ != self._superclass_method.__name__):
244	raise AttributeError(	1✔
245	f"{self._override_name} name "
246	f"{self._superclass_method.__name__} does not match "
247	f"{method.__name__}. Ensure {self.__class__.__name__} is the "
248	"last decorator before the method declaration")
249
250	# Check that the arguments match (except for __init__ as this might
251	# take extra arguments or pass arguments not specified)
252	if method.__name__ != "__init__":	1!
253	self.__verify_method_arguments(method)	1✔
254	self.__verify_method_types(method)	1✔
255
256	if (self._superclass_method.__doc__ is not None and	1✔
257	method.__doc__ is None):
258	method.__doc__ = self._superclass_method.__doc__	1✔
259	elif (self._extend_doc and	1✔
260	self._superclass_method.__doc__ is not None):
261	method.__doc__ = (	1✔
262	self._superclass_method.__doc__ + (method.__doc__ or ""))
263	return method	1✔
264
265	@classmethod	1✔
266	def set_matchall(cls):	1✔
267	cls._MATCH_ALL = True	1✔

SpiNNakerManchester / SpiNNUtils / 7032134530

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous