Metadata-Version: 2.1
Name: oop-ext
Version: 1.1.2
Summary: OOP Extensions is a set of utilities for object oriented programming not found on Python's standard library.
Home-page: http://github.com/ESSS/oop-ext
Author: ESSS
Author-email: foss@esss.co
License: MIT license
Description: ======================================================================
        OOP Extensions
        ======================================================================
        
        .. image:: https://img.shields.io/pypi/v/oop-ext.svg
            :target: https://pypi.python.org/pypi/oop-ext
        
        .. image:: https://img.shields.io/pypi/pyversions/oop-ext.svg
            :target: https://pypi.org/project/oop-ext
        
        .. image:: https://github.com/ESSS/oop-ext/workflows/build/badge.svg
            :target: https://github.com/ESSS/oop-ext/actions
        
        .. image:: https://codecov.io/gh/ESSS/oop-ext/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/ESSS/oop-ext
        
        .. image:: https://img.shields.io/readthedocs/oop-extensions.svg
            :target: https://oop-extensions.readthedocs.io/en/latest/
        
        .. image:: https://results.pre-commit.ci/badge/github/ESSS/oop-ext/master.svg
            :target: https://results.pre-commit.ci/latest/github/ESSS/oop-ext/master
        
        What is OOP Extensions ?
        ================================================================================
        
        OOP Extensions is a set of utilities for object oriented programming which is missing on Python core libraries.
        
        Usage
        ================================================================================
        ``oop_ext`` brings a set of object oriented utilities, it supports the concept of interfaces,
        abstract/overridable methods and more. ``oop_ext`` carefully checks that implementations
        have the same method signatures as the interface it implements and raises exceptions otherwise.
        
        Here's a simple example showing some nice features:
        
        .. code-block:: python
        
            from oop_ext.interface import Interface, ImplementsInterface
        
        
            class IDisposable(Interface):
                def dispose(self):
                    """
                    Clears this object
                    """
        
                def is_disposed(self) -> bool:
                    """
                    Returns True if the object has been cleared
                    """
        
        
            @ImplementsInterface(IDisposable)
            class MyObject(Disposable):
                def __init__(self):
                    super().__init__()
                    self._data = [0] * 100
                    self._is_disposed = False
        
                def is_disposed(self) -> bool:
                    return self._is_disposed
        
                def dispose(self):
                    self._is_disposed = True
                    self._data = []
        
        
        If any of the two methods in ``MyObject`` are not implemented or have differ signatures than
        the ones declared in ``IDisposable``, the ``ImplementsInterface`` decorator will raise an
        error during import.
        
        Arbitrary objects can be verified if they implement a certain interface by using ``IsImplementation``:
        
        .. code-block:: python
        
            from oop_ext.interface import IsImplementation
        
            my_object = MyObject()
            if IsImplementation(my_object, IDisposable):
                # my_object is guaranteed to implement IDisposable completely
                my_object.dispose()
        
        Alternatively you can assert that an object implements the desired interface with ``AssertImplements``:
        
        .. code-block:: python
        
            from oop_ext.interface import AssertImplements
        
            my_object = MyObject()
            AssertImplements(my_object, IDisposable)
            my_object.dispose()
        
        
        Type Checking
        -------------
        
        As of ``1.1.0``, ``oop-ext`` includes inline type annotations and exposes them to user programs.
        
        If you are running a type checker such as mypy on your tests, you may start noticing type errors indicating incorrect usage.
        If you run into an error that you believe to be incorrect, please let us know in an issue.
        
        The types were developed against ``mypy`` version 0.800.
        
        See `the docs <https://oop-extensions.readthedocs.io/en/latest/interfaces.html#static-type-checking>`__
        for more information.
        
        Contributing
        ------------
        
        For guidance on setting up a development environment and how to make a
        contribution to oop_ext, see the `contributing guidelines`_.
        
        .. _contributing guidelines: https://github.com/ESSS/oop-ext/blob/master/CONTRIBUTING.rst
        
        
        Release
        -------
        A reminder for the maintainers on how to make a new release.
        
        Note that the VERSION should follow the semantic versioning as X.Y.Z
        Ex.: v1.0.5
        
        1. Create a ``release-VERSION`` branch from ``upstream/master``.
        2. Update ``CHANGELOG.rst``.
        3. Push a branch with the changes.
        4. Once all builds pass, push a ``VERSION`` tag to ``upstream``.
        5. Merge the PR.
        
        
        1.1.2 (2021-02-23)
        ------------------
        
        * #41: Fix regression introduced in ``1.1.0`` where installing a callback using
          ``callback.After`` or ``callback.Before`` would make a method no longer compliant with
          the signature required by its interface.
        
        1.1.1 (2021-02-23)
        ------------------
        
        * #38: Reintroduce ``extra_args`` argument to ``Callback._GetKey``, so subclasses can make use
          of it.
        
        * #36: Fix regression introduced in ``1.1.0`` where ``Abstract`` and ``Implements`` decorators
          could no longer be used in interfaces implementations.
        
        1.1.0 (2021-02-19)
        ------------------
        
        * #25: ``oop-ext`` now includes inline type annotations and exposes them to user programs.
        
          If you are running a type checker such as mypy on your tests, you may start noticing type errors indicating incorrect usage.
          If you run into an error that you believe to be incorrect, please let us know in an issue.
        
          The types were developed against ``mypy`` version 0.800.
        
        * #26: New type-checked ``Callback`` variants, ``Callback0``, ``Callback1``, ``Callback2``, etc, providing
          type checking for all operations(calling, ``Register``, etc) at nearly zero runtime cost.
        
          Example:
        
          .. code-block:: python
        
              from oop_ext.foundation.callback import Callback2
        
        
              def changed(x: int, v: float) -> None:
                  ...
        
        
              on_changed = Callback2[int, float]()
              on_changed(10, 5.25)
        
        
        * Fixed ``Callbacks.Before`` and ``Callbacks.After`` signatures: previously their signature conveyed
          that they supported multiple callbacks, but it was a mistake which would break callers because
          every parameter after the 2nd would be considered the ``sender_as_parameter`` parameter, which
          was forwarded to ``After`` and ``Before`` functions of the ``_shortcuts.py``
          module.
        
        1.0.0 (2020-10-01)
        ------------------
        
        * ``Callbacks`` can be used as context manager, which provides a ``Register(callback, function)``,
          which automatically unregisters all functions when the context manager ends.
        
        * ``Callback.Register(function)`` now returns an object with a ``Unregister()`` method, which
          can be used to undo the register call.
        
        0.6.0 (2020-01-31)
        ==================
        
        * Change back the default value of ``requires_declaration`` to ``True`` and fix an error (#22) where the cache wasn't properly cleared.
        
        0.5.1 (2019-12-20)
        ------------------
        
        * Fixes an issue (#20) where mocked `classmethods` weren't considered a valid method during internal checks.
        
        0.5.0 (2019-12-12)
        ------------------
        
        * Add optional argument ``requires_declaration`` so users can decide whether or not ``@ImplementsInterface`` declarations are necessary.
        
        0.4.0 (2019-12-03)
        ------------------
        
        * Implementations no longer need to explicitly declare that they declare an interface with ``@ImplementsInterface``: the check is done implicitly (and cached) by `AssertImplements` and equivalent functions.
        
        0.3.2 (2019-08-22)
        ------------------
        
        * Interface and implementation methods can no longer contain mutable defaults, as this is considered
          a bad practice in general.
        
        * ``Null`` instances are now hashable.
        
        
        0.3.1 (2019-08-16)
        ------------------
        
        * Fix mismatching signatures when creating "interface stubs" for instances:
        
          .. code-block:: python
        
              foo = IFoo(Foo())
        
        
        0.3.0 (2019-08-08)
        ------------------
        
        * Interfaces now support keyword-only arguments.
        
        0.2.4 (2019-03-22)
        ------------------
        
        * Remove ``FunctionNotRegisteredError`` exception, which has not been in use for a few years.
        
        
        0.2.3 (2019-03-22)
        ------------------
        
        * Fix issues of ignored exception on nested callback.
        
        
        0.2.1 (2019-03-14)
        ------------------
        
        * Fix issues and remove obsolete code.
        
        
        0.1.8 (2019-03-12)
        ------------------
        
        * First release on PyPI.
        
Keywords: oop_ext
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Provides-Extra: docs
Provides-Extra: testing
