7272980465

Committed 20 Dec 2023 08:23AM UTC coverage: 87.97% (-0.3%) from 88.242%

Build # 7272980465

Build Type

Pull #257

github

Committed by

Christian-B

Commit Message

merged in master

Pull Request Pull Request #257: Overrides check

Run Details

1358 of 1661 branches covered (0.0%)

Branch coverage included in aggregate %.

127 of 139 new or added lines in 13 files covered. (91.37%)

5 existing lines in 1 file now uncovered.

3395 of 3742 relevant lines covered (90.73%)

0.91 hits per line

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

86.21

/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
import os
from types import FunctionType, MethodType
from typing import Any, Callable, 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 unittests to check our code
    # Github actions sets CI as True
    __CHECK_TYPES = os.getenv("TYPE_OVERRIDES")

    __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"
    ]

    def __init__(
            self, super_class_method, *, extend_doc: bool = True,
            additional_arguments: Optional[Iterable[str]] = None,
            extend_defaults: bool = False, adds_typing: 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
        """
        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

    @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_types(self, method_args, super_args, all_args):
        """
        Check that the arguments match.
        """
        if not self.__CHECK_TYPES:
            return
        if "self" in all_args:
            all_args.remove("self")
        elif "cls" in all_args:
            all_args.remove("cls")
        method_types = method_args.annotations
        super_types = super_args.annotations
        for arg in all_args:
            if arg not in super_types and not self._adds_typing:
                raise AttributeError(
                    f"Super Method {self._superclass_method.__name__} "
                    f"has untyped arguments including {arg}")
            if arg not in method_types:
                raise AttributeError(
                    f"Method {self._superclass_method.__name__} "
                    f"has untyped arguments including {arg}")

        if len(all_args) == 0:
            if "return" not in super_types and not self._adds_typing and \
                    not method_args.varkw and not method_args.varargs:
                raise AttributeError(
                    f"Super Method {self._superclass_method.__name__} "
                    f"has no arguments so should declare a return type")
        if "return" in super_types:
            if "return" not in method_types:
                raise AttributeError(
                    f"Method {self._superclass_method.__name__} "
                    f"has no return type, while super does")
        else:
            if "return" in method_types and not self._adds_typing:
                raise AttributeError(
                    f"Super Method {self._superclass_method.__name__} "
                    f"has no return type, while this does")

    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}")
        self._verify_types(method_args, super_args, all_args)

    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)

        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 check_types(cls):
        cls.__CHECK_TYPES = 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	import os	1✔
17	from types import FunctionType, MethodType	1✔
18	from typing import Any, Callable, Iterable, Optional, TypeVar	1✔
19
20	#: :meta private:
21	Method = TypeVar("Method", bound=Callable[..., Any])	1✔
22
23
24	class overrides(object):	1✔
25	"""
26	A decorator for indicating that a method overrides another method in
27	a superclass. This checks that the method does actually exist,
28	copies the doc-string for the method, and enforces that the method
29	overridden is specified, making maintenance easier.
30	"""
31	# This near constant is changed by unittests to check our code
32	# Github actions sets CI as True
33	__CHECK_TYPES = os.getenv("TYPE_OVERRIDES")	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	]
51
52	def __init__(	1✔
53	self, super_class_method, *, extend_doc: bool = True,
54	additional_arguments: Optional[Iterable[str]] = None,
55	extend_defaults: bool = False, adds_typing: bool = False,):
56	"""
57	:param super_class_method: The method to override in the superclass
58	:param bool extend_doc:
59	True the method doc string should be appended to the super-method
60	doc string, False if the documentation should be set to the
61	super-method doc string only if there isn't a doc string already
62	:param iterable(str) additional_arguments:
63	Additional arguments taken by the subclass method over the
64	superclass method, e.g., that are to be injected
65	:param bool extend_defaults:
66	Whether the subclass may specify extra defaults for the parameters
67	:param adds_typing:
68	Allows more typing (of non additional) than in the subclass.
69	Should only be used for builtin super classes
70	"""
71	if isinstance(super_class_method, property):	1✔
72	super_class_method = super_class_method.fget	1✔
73	if not isinstance(super_class_method, (FunctionType, MethodType)):	1!
74	raise TypeError("may only decorate method declarations; "	×
75	f"this is a {type(super_class_method)}")
76	self._superclass_method = super_class_method	1✔
77	self._extend_doc = bool(extend_doc)	1✔
78	self._extend_defaults = bool(extend_defaults)	1✔
79	self._relax_name_check = False	1✔
80	self._override_name = "super class method"	1✔
81	if additional_arguments is not None:	1✔
82	self._additional_arguments = frozenset(additional_arguments)	1✔
83	else:
84	self._additional_arguments = frozenset()	1✔
85	self._adds_typing = adds_typing	1✔
86
87	@staticmethod	1✔
88	def __match_defaults(default_args, super_defaults, extend_ok):	1✔
89	if default_args is None:	1✔
90	return super_defaults is None	1✔
91	elif super_defaults is None:	1✔
92	return extend_ok	1✔
93	if extend_ok:	1✔
94	return len(default_args) >= len(super_defaults)	1✔
95	return len(default_args) == len(super_defaults)	1✔
96
97	def _verify_types(self, method_args, super_args, all_args):	1✔
98	"""
99	Check that the arguments match.
100	"""
101	if not self.__CHECK_TYPES:	1!
NEW 102	return	×
103	if "self" in all_args:	1!
104	all_args.remove("self")	1✔
NEW 105	elif "cls" in all_args:	×
NEW 106	all_args.remove("cls")	×
107	method_types = method_args.annotations	1✔
108	super_types = super_args.annotations	1✔
109	for arg in all_args:	1✔
110	if arg not in super_types and not self._adds_typing:	1!
NEW 111	raise AttributeError(	×
112	f"Super Method {self._superclass_method.__name__} "
113	f"has untyped arguments including {arg}")
114	if arg not in method_types:	1!
NEW 115	raise AttributeError(	×
116	f"Method {self._superclass_method.__name__} "
117	f"has untyped arguments including {arg}")
118
119	if len(all_args) == 0:	1✔
120	if "return" not in super_types and not self._adds_typing and \	1!
121	not method_args.varkw and not method_args.varargs:
NEW 122	raise AttributeError(	×
123	f"Super Method {self._superclass_method.__name__} "
124	f"has no arguments so should declare a return type")
125	if "return" in super_types:	1✔
126	if "return" not in method_types:	1!
NEW 127	raise AttributeError(	×
128	f"Method {self._superclass_method.__name__} "
129	f"has no return type, while super does")
130	else:
131	if "return" in method_types and not self._adds_typing:	1!
NEW 132	raise AttributeError(	×
133	f"Super Method {self._superclass_method.__name__} "
134	f"has no return type, while this does")
135
136	def __verify_method_arguments(self, method: Method):	1✔
137	"""
138	Check that the arguments match.
139	"""
140	method_args = inspect.getfullargspec(method)	1✔
141	super_args = inspect.getfullargspec(self._superclass_method)	1✔
142	all_args = [	1✔
143	arg for arg in method_args.args
144	if arg not in self._additional_arguments]
145	default_args = None	1✔
146	if method_args.defaults is not None:	1✔
147	default_args = [	1✔
148	arg for arg in method_args.defaults
149	if arg not in self._additional_arguments]
150	if len(all_args) != len(super_args.args):	1✔
151	raise AttributeError(	1✔
152	f"Method has {len(method_args.args)} arguments but "
153	f"{self._override_name} has {len(super_args.args)} arguments")
154	for arg, super_arg in zip(all_args, super_args.args):	1✔
155	if arg != super_arg:	1✔
156	raise AttributeError(f"Missing argument {super_arg}")	1✔
157	if not self.__match_defaults(	1✔
158	default_args, super_args.defaults, self._extend_defaults):
159	raise AttributeError(	1✔
160	f"Default arguments don't match {self._override_name}")
161	self._verify_types(method_args, super_args, all_args)	1✔
162
163	def __call__(self, method: Method) -> Method:	1✔
164	"""
165	Apply the decorator to the given method.
166	"""
167	# Check and fail if this is a property
168	if isinstance(method, property):	1✔
169	raise AttributeError(	1✔
170	f"Please ensure that the {self.__class__.__name__} decorator "
171	"is the last decorator before the method declaration")
172
173	# Check that the name matches
174	if (not self._relax_name_check and	1✔
175	method.__name__ != self._superclass_method.__name__):
176	raise AttributeError(	1✔
177	f"{self._override_name} name "
178	f"{self._superclass_method.__name__} does not match "
179	f"{method.__name__}. Ensure {self.__class__.__name__} is the "
180	"last decorator before the method declaration")
181
182	# Check that the arguments match (except for __init__ as this might
183	# take extra arguments or pass arguments not specified)
184	if method.__name__ != "__init__":	1!
185	self.__verify_method_arguments(method)	1✔
186
187	if (self._superclass_method.__doc__ is not None and	1✔
188	method.__doc__ is None):
189	method.__doc__ = self._superclass_method.__doc__	1✔
190	elif (self._extend_doc and	1✔
191	self._superclass_method.__doc__ is not None):
192	method.__doc__ = (	1✔
193	self._superclass_method.__doc__ + (method.__doc__ or ""))
194	return method	1✔
195
196	@classmethod	1✔
197	def check_types(cls):	1✔
198	cls.__CHECK_TYPES = True	1✔

SpiNNakerManchester / SpiNNUtils / 7272980465

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