codekingpro/portable-devtools

1Metadata-Version: 2.12Name: overrides3Version: 7.7.04Summary: A decorator to automatically detect mismatch when overriding a method.5Home-page: https://github.com/mkorpela/overrides6Author: Mikko Korpela7Author-email: mikko.korpela@gmail.com8License: Apache License, Version 2.09Keywords: override,inheritence,OOP10Classifier: Intended Audience :: Developers11Classifier: Programming Language :: Python :: 3.612Classifier: Programming Language :: Python :: 3.713Classifier: Programming Language :: Python :: 3.814Classifier: Programming Language :: Python :: 3.915Requires-Python: >=3.616License-File: LICENSE17Requires-Dist: typing ; python_version < "3.5"18 19overrides20=========21 22.. image:: https://img.shields.io/pypi/v/overrides.svg23  :target: https://pypi.python.org/pypi/overrides24 25.. image:: http://pepy.tech/badge/overrides26  :target: http://pepy.tech/project/overrides27 28A decorator ``@override`` that verifies that a method that should override an inherited method actually does it.29 30Copies the docstring of the inherited method to the overridden method.31 32Since signature validation and docstring inheritance are performed on class creation and not on class instantiation,33this library significantly improves the safety and experience of creating class hierarchies in 34Python without significantly impacting performance. See https://stackoverflow.com/q/1167617 for the35initial inspiration for this library.36 37Motivation38----------39 40Python has no standard mechanism by which to guarantee that (1) a method that previously overrode an inherited method41continues to do so, and (2) a method that previously did not override an inherited will not override now.42This opens the door for subtle problems as class hierarchies evolve over time. For example,43 441. A method that is added to a superclass is shadowed by an existing method with the same name in a 45   subclass.46 472. A method of a superclass that is overridden by a subclass is renamed in the superclass but not in 48   the subclass.49 503. A method of a superclass that is overridden by a subclass is removed in the superclass but not in51   the subclass.52 534. A method of a superclass that is overridden by a subclass but the signature of the overridden54   method is incompatible with that of the inherited one.55 56These can be only checked by explicitly marking method override in the code.57 58Python also has no standard mechanism by which to inherit docstrings in overridden methods. Because 59most standard linters (e.g., flake8) have rules that require all public methods to have a docstring, 60this inevitably leads to a proliferation of ``See parent class for usage`` docstrings on overridden61methods, or, worse, to a disabling of these rules altogether. In addition, mediocre or missing62docstrings degrade the quality of tooltips and completions that can be provided by an editor.63 64Installation65------------66 67Compatible with Python 3.6+.68 69.. code-block:: bash70 71    $ pip install overrides72 73Usage74-----75 76Use ``@override`` to indicate that a subclass method should override a superclass method.77 78.. code-block:: python79 80    from overrides import override81 82    class SuperClass:83 84        def foo(self):85            """This docstring will be inherited by any method that overrides this!"""86            return 187 88        def bar(self, x) -> str:89            return x90 91    class SubClass(SuperClass):92 93        @override94        def foo(self):95            return 296 97        @override98        def bar(self, y) -> int: # Raises, because the signature is not compatible.99            return y100            101        @override102        def zoo(self): # Raises, because does not exist in the super class.103            return "foobarzoo"104 105Use ``EnforceOverrides`` to require subclass methods that shadow superclass methods to be decorated 106with ``@override``.107 108.. code-block:: python109 110    from overrides import EnforceOverrides111 112    class SuperClass(EnforceOverrides):113 114        def foo(self):115            return 1116 117    class SubClass(SuperClass):118 119        def foo(self): # Raises, because @override is missing.120            return 2121 122Use ``@final`` to indicate that a superclass method cannot be overriden.123With Python 3.11 and above ``@final`` is directly `typing.final <https://docs.python.org/3.11/library/typing.html#typing.final>`_.124 125.. code-block:: python126 127    from overrides import EnforceOverrides, final, override128 129    class SuperClass(EnforceOverrides):130 131        @final132        def foo(self):133            return 1134 135    class SubClass(SuperClass):136 137        @override138        def foo(self): # Raises, because overriding a final method is forbidden.139            return 2140 141Note that ``@classmethod`` and ``@staticmethod`` must be declared before ``@override``.142 143.. code-block:: python144 145    from overrides import override146 147    class SuperClass:148 149        @staticmethod150        def foo(x):151            return 1152 153    class SubClass(SuperClass):154 155        @staticmethod156        @override157        def foo(x):158            return 2159 160 161Flags of control162----------------163 164.. code-block:: python165 166    # To prevent all signature checks do:167    @override(check_signature=False)168    def some_method(self, now_this_can_be_funny_and_wrong: str, what_ever: int) -> "Dictirux":169        pass170 171    # To do the check only at runtime and solve some forward reference problems172    @override(check_at_runtime=True)173    def some_other_method(self, ..) -> "SomethingDefinedLater":174        pass175 176    a.some_other_method() # Kaboom if not SomethingDefinedLater177 178 179Contributors180------------181 182This project exists only through the work of all the people who contribute.183 184mkorpela, drorasaf, ngoodman90, TylerYep, leeopop, donpatrice, jayvdb, joelgrus, lisyarus, 185soulmerge, rkr-at-dbx, ashwin153, brentyi,  jobh, tjsmart, bersbersbers, LysanderGG, mgorny.186