oop-ext


Nameoop-ext JSON
Version 1.1.2 PyPI version JSON
download
home_pagehttp://github.com/ESSS/oop-ext
SummaryOOP Extensions is a set of utilities for object oriented programming not found on Python's standard library.
upload_time2021-02-23 18:05:24
maintainer
docs_urlNone
authorESSS
requires_python>=3.6
licenseMIT license
keywords oop_ext
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ======================================================================
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.



            

Raw data

            {
    "_id": null,
    "home_page": "http://github.com/ESSS/oop-ext",
    "name": "oop-ext",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "oop_ext",
    "author": "ESSS",
    "author_email": "foss@esss.co",
    "download_url": "https://files.pythonhosted.org/packages/ff/aa/f01049ded71799771df0b305b7dc0bc3915be3dcc5fe4b80f5968a3148d6/oop-ext-1.1.2.tar.gz",
    "platform": "",
    "description": "======================================================================\nOOP Extensions\n======================================================================\n\n.. image:: https://img.shields.io/pypi/v/oop-ext.svg\n    :target: https://pypi.python.org/pypi/oop-ext\n\n.. image:: https://img.shields.io/pypi/pyversions/oop-ext.svg\n    :target: https://pypi.org/project/oop-ext\n\n.. image:: https://github.com/ESSS/oop-ext/workflows/build/badge.svg\n    :target: https://github.com/ESSS/oop-ext/actions\n\n.. image:: https://codecov.io/gh/ESSS/oop-ext/branch/master/graph/badge.svg\n    :target: https://codecov.io/gh/ESSS/oop-ext\n\n.. image:: https://img.shields.io/readthedocs/oop-extensions.svg\n    :target: https://oop-extensions.readthedocs.io/en/latest/\n\n.. image:: https://results.pre-commit.ci/badge/github/ESSS/oop-ext/master.svg\n    :target: https://results.pre-commit.ci/latest/github/ESSS/oop-ext/master\n\nWhat is OOP Extensions ?\n================================================================================\n\nOOP Extensions is a set of utilities for object oriented programming which is missing on Python core libraries.\n\nUsage\n================================================================================\n``oop_ext`` brings a set of object oriented utilities, it supports the concept of interfaces,\nabstract/overridable methods and more. ``oop_ext`` carefully checks that implementations\nhave the same method signatures as the interface it implements and raises exceptions otherwise.\n\nHere's a simple example showing some nice features:\n\n.. code-block:: python\n\n    from oop_ext.interface import Interface, ImplementsInterface\n\n\n    class IDisposable(Interface):\n        def dispose(self):\n            \"\"\"\n            Clears this object\n            \"\"\"\n\n        def is_disposed(self) -> bool:\n            \"\"\"\n            Returns True if the object has been cleared\n            \"\"\"\n\n\n    @ImplementsInterface(IDisposable)\n    class MyObject(Disposable):\n        def __init__(self):\n            super().__init__()\n            self._data = [0] * 100\n            self._is_disposed = False\n\n        def is_disposed(self) -> bool:\n            return self._is_disposed\n\n        def dispose(self):\n            self._is_disposed = True\n            self._data = []\n\n\nIf any of the two methods in ``MyObject`` are not implemented or have differ signatures than\nthe ones declared in ``IDisposable``, the ``ImplementsInterface`` decorator will raise an\nerror during import.\n\nArbitrary objects can be verified if they implement a certain interface by using ``IsImplementation``:\n\n.. code-block:: python\n\n    from oop_ext.interface import IsImplementation\n\n    my_object = MyObject()\n    if IsImplementation(my_object, IDisposable):\n        # my_object is guaranteed to implement IDisposable completely\n        my_object.dispose()\n\nAlternatively you can assert that an object implements the desired interface with ``AssertImplements``:\n\n.. code-block:: python\n\n    from oop_ext.interface import AssertImplements\n\n    my_object = MyObject()\n    AssertImplements(my_object, IDisposable)\n    my_object.dispose()\n\n\nType Checking\n-------------\n\nAs of ``1.1.0``, ``oop-ext`` includes inline type annotations and exposes them to user programs.\n\nIf you are running a type checker such as mypy on your tests, you may start noticing type errors indicating incorrect usage.\nIf you run into an error that you believe to be incorrect, please let us know in an issue.\n\nThe types were developed against ``mypy`` version 0.800.\n\nSee `the docs <https://oop-extensions.readthedocs.io/en/latest/interfaces.html#static-type-checking>`__\nfor more information.\n\nContributing\n------------\n\nFor guidance on setting up a development environment and how to make a\ncontribution to oop_ext, see the `contributing guidelines`_.\n\n.. _contributing guidelines: https://github.com/ESSS/oop-ext/blob/master/CONTRIBUTING.rst\n\n\nRelease\n-------\nA reminder for the maintainers on how to make a new release.\n\nNote that the VERSION should follow the semantic versioning as X.Y.Z\nEx.: v1.0.5\n\n1. Create a ``release-VERSION`` branch from ``upstream/master``.\n2. Update ``CHANGELOG.rst``.\n3. Push a branch with the changes.\n4. Once all builds pass, push a ``VERSION`` tag to ``upstream``.\n5. Merge the PR.\n\n\n1.1.2 (2021-02-23)\n------------------\n\n* #41: Fix regression introduced in ``1.1.0`` where installing a callback using\n  ``callback.After`` or ``callback.Before`` would make a method no longer compliant with\n  the signature required by its interface.\n\n1.1.1 (2021-02-23)\n------------------\n\n* #38: Reintroduce ``extra_args`` argument to ``Callback._GetKey``, so subclasses can make use\n  of it.\n\n* #36: Fix regression introduced in ``1.1.0`` where ``Abstract`` and ``Implements`` decorators\n  could no longer be used in interfaces implementations.\n\n1.1.0 (2021-02-19)\n------------------\n\n* #25: ``oop-ext`` now includes inline type annotations and exposes them to user programs.\n\n  If you are running a type checker such as mypy on your tests, you may start noticing type errors indicating incorrect usage.\n  If you run into an error that you believe to be incorrect, please let us know in an issue.\n\n  The types were developed against ``mypy`` version 0.800.\n\n* #26: New type-checked ``Callback`` variants, ``Callback0``, ``Callback1``, ``Callback2``, etc, providing\n  type checking for all operations(calling, ``Register``, etc) at nearly zero runtime cost.\n\n  Example:\n\n  .. code-block:: python\n\n      from oop_ext.foundation.callback import Callback2\n\n\n      def changed(x: int, v: float) -> None:\n          ...\n\n\n      on_changed = Callback2[int, float]()\n      on_changed(10, 5.25)\n\n\n* Fixed ``Callbacks.Before`` and ``Callbacks.After`` signatures: previously their signature conveyed\n  that they supported multiple callbacks, but it was a mistake which would break callers because\n  every parameter after the 2nd would be considered the ``sender_as_parameter`` parameter, which\n  was forwarded to ``After`` and ``Before`` functions of the ``_shortcuts.py``\n  module.\n\n1.0.0 (2020-10-01)\n------------------\n\n* ``Callbacks`` can be used as context manager, which provides a ``Register(callback, function)``,\n  which automatically unregisters all functions when the context manager ends.\n\n* ``Callback.Register(function)`` now returns an object with a ``Unregister()`` method, which\n  can be used to undo the register call.\n\n0.6.0 (2020-01-31)\n==================\n\n* Change back the default value of ``requires_declaration`` to ``True`` and fix an error (#22) where the cache wasn't properly cleared.\n\n0.5.1 (2019-12-20)\n------------------\n\n* Fixes an issue (#20) where mocked `classmethods` weren't considered a valid method during internal checks.\n\n0.5.0 (2019-12-12)\n------------------\n\n* Add optional argument ``requires_declaration`` so users can decide whether or not ``@ImplementsInterface`` declarations are necessary.\n\n0.4.0 (2019-12-03)\n------------------\n\n* 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.\n\n0.3.2 (2019-08-22)\n------------------\n\n* Interface and implementation methods can no longer contain mutable defaults, as this is considered\n  a bad practice in general.\n\n* ``Null`` instances are now hashable.\n\n\n0.3.1 (2019-08-16)\n------------------\n\n* Fix mismatching signatures when creating \"interface stubs\" for instances:\n\n  .. code-block:: python\n\n      foo = IFoo(Foo())\n\n\n0.3.0 (2019-08-08)\n------------------\n\n* Interfaces now support keyword-only arguments.\n\n0.2.4 (2019-03-22)\n------------------\n\n* Remove ``FunctionNotRegisteredError`` exception, which has not been in use for a few years.\n\n\n0.2.3 (2019-03-22)\n------------------\n\n* Fix issues of ignored exception on nested callback.\n\n\n0.2.1 (2019-03-14)\n------------------\n\n* Fix issues and remove obsolete code.\n\n\n0.1.8 (2019-03-12)\n------------------\n\n* First release on PyPI.\n\n\n",
    "bugtrack_url": null,
    "license": "MIT license",
    "summary": "OOP Extensions is a set of utilities for object oriented programming not found on Python's standard library.",
    "version": "1.1.2",
    "split_keywords": [
        "oop_ext"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "3937e07fbad92fe0915647ef51bd682d",
                "sha256": "2ce506fd40c796c9122abc952304114e18273779ddae5563bc472f50a1a856fe"
            },
            "downloads": -1,
            "filename": "oop_ext-1.1.2-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3937e07fbad92fe0915647ef51bd682d",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">=3.6",
            "size": 71802,
            "upload_time": "2021-02-23T18:05:22",
            "upload_time_iso_8601": "2021-02-23T18:05:22.469302Z",
            "url": "https://files.pythonhosted.org/packages/98/86/8da059c22a37c6705c5b9dbdff35e51cb0b1d05b1a94930475bc382d041a/oop_ext-1.1.2-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "d215c769663f9cf292555edebb85a7b5",
                "sha256": "c91e2e7dc8dc1a44d6a53b274c41d5b70913de8eece91e87a6fac7d6d5bbfc35"
            },
            "downloads": -1,
            "filename": "oop-ext-1.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "d215c769663f9cf292555edebb85a7b5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 72488,
            "upload_time": "2021-02-23T18:05:24",
            "upload_time_iso_8601": "2021-02-23T18:05:24.090920Z",
            "url": "https://files.pythonhosted.org/packages/ff/aa/f01049ded71799771df0b305b7dc0bc3915be3dcc5fe4b80f5968a3148d6/oop-ext-1.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-02-23 18:05:24",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "ESSS",
    "error": "Could not fetch GitHub repository",
    "lcname": "oop-ext"
}
        
Elapsed time: 0.21818s