nti.testing 4.2.0__py3-none-any.whl

nti/testing/zodb.py

@@ -0,0 +1,245 @@
+# -*- coding: utf-8 -*-
+"""
+Support for testing of ZODB applications.
+
+.. versionadded:: 3.0.0
+
+"""
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import gc
+import sys
+
+
+import transaction
+from transaction.interfaces import NoTransaction
+
+import ZODB
+from ZODB.interfaces import IDatabase
+from ZODB.DemoStorage import DemoStorage
+from zope import component
+from zope.exceptions import print_exception
+from zope.exceptions import format_exception
+
+from .layers import ZopeComponentLayer
+
+PYPY = hasattr(sys, 'pypy_version_info')
+
+__all__ = [
+    'mock_db_trans',
+    'ZODBLayer',
+    'reset_db_caches',
+]
+
+# The exceptions are not expected to be caught. They indicate errors
+# to fix.
+class _BaseException(Exception):
+    default_message = 'Unknown'
+    def __init__(self, t, v, tb):
+        msg = self.default_message
+        if t:
+            msg = ''.join(format_exception(t, v, tb))
+        Exception.__init__(self, msg)
+
+class _TransactionManagerModeChanged(_BaseException):
+    default_message = 'The transaction manager explicit mode changed'
+
+class _TransactionChanged(_BaseException):
+    default_message = 'The body changed the active transaction'
+
+class mock_db_trans(object):
+    """
+    A context manager that begins and commits a database transaction.
+
+    This class may be subclassed; there are some extension points
+    to allow customization.
+
+    This class is not designed for concurrency.
+
+    Entering this context manager begins a transaction using the
+    thread-local global transaction manager and returns a connection
+    open to the database given in the *db* parameter. Exiting this
+    context manager commits the transaction (or aborts it if it is
+    doomed).
+
+    It is an error to enter this context manager with a transaction
+    already in progress. The global transaction may be committed or aborted
+    before exiting this transaction, but no new transaction may be opened. During
+    execution of the body, the transaction manager is in explicit mode;
+    it is an error if this is changed during the body.
+    """
+
+    #: The connection that was opened. Valid after entering and before exiting.
+    conn = None
+
+    #: The file to which unexpected exceptions that cannot be raised are printed.
+    #: If `None`, exceptions will be written to `sys.stderr`
+    exc_file = None
+
+    def __init__(self, db=None):
+        """
+        :param db: The :class:`ZODB.DB` to open. If none is given,
+            then the :attr:`ZODBLayer.db` will be used.
+        """
+        self.db = db if db is not None else ZODBLayer.db
+        self.__txm_was_explicit = None
+        self.__current_transaction = None
+
+    def on_connection_opened(self, conn):
+        """
+        Called when the connection to the DB has been opened.
+
+        Subclasses may override to perform initialization.
+        The DB may have been used before, so check its state and don't assume
+        a complete initialization must happen.
+        """
+
+    def __enter__(self):
+        txm = transaction.manager
+        self.__txm_was_explicit = txm.explicit
+        txm.explicit = True
+        try:
+            self.__current_transaction = txm.begin()
+            self.conn = conn = self.db.open()
+            self.on_connection_opened(conn)
+        except:
+            # Could be several things:
+            # Already in a transaction is definitely a user error.
+            # Failure to open the DB: Probably also a user error.
+            # Failure to setup the DB: Possibly a user error, or error in a
+            # subclass.
+            txm.explicit = self.__txm_was_explicit
+            if self.__current_transaction:
+                self._clean_up_one_transaction(self.__current_transaction, True)
+
+            if self.conn is not None:
+                self.conn.close()
+            self.conn = None
+            self.__current_transaction = None
+            raise
+        return self.conn
+
+    def _clean_up_one_transaction(self, tx, abort_only):
+        try:
+            if abort_only or tx.isDoomed():
+                tx.abort()
+            else:
+                tx.commit()
+        except:
+            tx.abort() # idempotent with transaction 3
+            raise
+
+    def _report_exception(self, msg, t, v, tb):
+        f = self.exc_file or sys.stderr
+        print(msg, file=f)
+        print_exception(t, v, tb, file=f, with_filenames=False)
+
+    def _close_connection(self, conn, ignore_errors):
+        catch = Exception if ignore_errors else ()
+        try:
+            conn.close()
+        except catch: # pylint:disable=broad-exception-caught
+            self._report_exception("Unexpected error closing connection; ignored.", *sys.exc_info())
+
+    def __exit__(self, t, v, tb):
+        # Returning a True value from __exit__ suppresses any
+        # exception raised in the body.
+        body_raised = t is not None
+        abort_only = body_raised # Should we commit our transaction, or only abort it?
+        error_in_body = None # Did the body do something wrong?
+        # Assuming we're still on the same thread and this hasn't been reset.
+        txm = transaction.manager
+        tx = self.__current_transaction
+        if not txm.explicit:
+            abort_only = True
+            error_in_body:Exception = _TransactionManagerModeChanged(t, v, tb)
+
+        try:
+            if txm.get() is not tx:
+                # Remember, .get() could raise.
+                self._clean_up_one_transaction(txm.get(), abort_only=True)
+                error_in_body = _TransactionChanged(t, v, tb)
+        except NoTransaction:
+            abort_only = True # It's already gone, so just abort it
+            error_in_body = _TransactionChanged(t, v, tb)
+
+        try:
+            self._clean_up_one_transaction(tx, abort_only)
+        except Exception: # pylint:disable=broad-except
+            if not body_raised:
+                # The body had no issue, but the commit did. Raise the commit error,
+                # but let the finally block know not to shadow it.
+                body_raised = True
+                raise
+            self._report_exception(
+                "Failed to cleanup trans, but body raised exception too. "
+                "This exception will be ignored.",
+                *sys.exc_info())
+            # So let the body exception propagate
+        finally:
+            txm.explicit = self.__txm_was_explicit
+            self._close_connection(self.conn, ignore_errors=body_raised)
+            self.conn = self.__current_transaction = None
+        reset_db_caches(self.db)
+        if error_in_body:
+            raise error_in_body # pylint:disable=raising-bad-type
+
+
+
+def reset_db_caches(db=None, collect=False):
+    """
+    Minimize the caches of all connections found in the *db*.
+
+    If the *db* is not given, then the one from the :class:`ZODBLayer`
+    is used.
+
+    On PyPy, or if *collect* is true, this will invoke
+    :func:`gc.collect` to help remove any weak references to objects
+    that were ejected from the cache.
+    """
+    result = -1
+    if db is None:
+        db = ZODBLayer.db
+    if db is not None:
+        for conn in db.pool:
+            conn.cacheMinimize()
+        if PYPY or collect:
+            result = gc.collect()
+    return result
+
+class ZODBLayer(ZopeComponentLayer):
+    """
+    Test layer that creates a ZODB database using
+    :class:`ZODB.DemoStorage.DemoStorage` and registers it as the
+    no-name :class:`ZODB.interfaces.IDatabase` in the global component
+    registry. It is also available in the :attr:`db` attribute of this
+    object.
+    """
+
+    #: The DB that was created.
+    db = None
+
+    @classmethod
+    def setUp(cls):
+        db = cls.db = ZODB.DB(DemoStorage())
+        component.getGlobalSiteManager().registerUtility(db, IDatabase)
+
+    @classmethod
+    def tearDown(cls):
+        db = cls.db
+        cls.db = None
+        if db is not None:
+            db.close()
+            reg_db = component.getGlobalSiteManager().queryUtility(IDatabase)
+            if reg_db is db:
+                component.getGlobalSiteManager().unregisterUtility(db, IDatabase)
+
+    @classmethod
+    def testSetUp(cls):
+        pass
+
+    @classmethod
+    def testTearDown(cls):
+        pass

nti.testing-4.2.0.dist-info/LICENSE

@@ -0,0 +1,11 @@
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this software except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://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.

nti.testing-4.2.0.dist-info/METADATA

@@ -0,0 +1,423 @@
+Metadata-Version: 2.1
+Name: nti.testing
+Version: 4.2.0
+Summary: Support for testing code
+Home-page: https://github.com/OpenNTI/nti.testing
+Author: Jason Madden
+Author-email: jason@nextthought.com
+License: Apache
+Project-URL: Documentation, https://ntitesting.readthedocs.io/en/latest/
+Keywords: nose2 testing zope3 ZTK hamcrest
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Zope3
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: ZODB>=5.6.0
+Requires-Dist: zope.interface>=5.4.0
+Requires-Dist: pyhamcrest
+Requires-Dist: six
+Requires-Dist: transaction
+Requires-Dist: zope.component
+Requires-Dist: zope.configuration
+Requires-Dist: zope.dottedname
+Requires-Dist: zope.exceptions
+Requires-Dist: zope.schema
+Requires-Dist: zope.testing
+Provides-Extra: docs
+Requires-Dist: Sphinx; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Provides-Extra: test
+Requires-Dist: Acquisition; extra == "test"
+Requires-Dist: zope.site; extra == "test"
+Requires-Dist: zope.testrunner; extra == "test"
+Requires-Dist: testgres>=1.10; extra == "test"
+Requires-Dist: psycopg2-binary; platform_python_implementation != "PyPy" and extra == "test"
+Provides-Extra: testgres
+Requires-Dist: testgres>=1.10; extra == "testgres"
+Requires-Dist: psycopg2-binary; platform_python_implementation != "PyPy" and extra == "testgres"
+
+=============
+ nti.testing
+=============
+
+.. image:: https://img.shields.io/pypi/v/nti.testing.svg
+        :target: https://pypi.python.org/pypi/nti.testing/
+        :alt: Latest release
+
+.. image:: https://img.shields.io/pypi/pyversions/nti.testing.svg
+        :target: https://pypi.org/project/nti.testing/
+        :alt: Supported Python versions
+
+.. image:: https://github.com/NextThought/nti.testing/actions/workflows/tests.yml/badge.svg
+        :target: https://github.com/NextThought/nti.testing/actions/workflows/tests.yml
+        :alt: Test Status
+
+.. image:: https://coveralls.io/repos/github/NextThought/nti.testing/badge.svg
+        :target: https://coveralls.io/github/NextThought/nti.testing
+
+.. image:: http://readthedocs.org/projects/ntitesting/badge/?version=latest
+        :target: http://ntitesting.readthedocs.io/en/latest/?badge=latest
+        :alt: Documentation Status
+
+Support for writing tests, particularly in a Zope3/ZTK environment,
+using zope.testing (nose2 may also work, but is not recommended).
+
+Complete documentation is hosted at https://ntitesting.readthedocs.io/
+
+Installation
+============
+
+nti.testing can be installed using pip, either from the git repository
+or from PyPI::
+
+  pip install nti.testing[testgres]
+
+Use the ``testgres`` extra to be able to use `nti.testing.layers.postgres`.
+
+PyHamcrest
+==========
+
+nti.testing provides a group of `PyHamcrest`_ matchers. There are both
+general-purpose matchers and matchers that are of use to users of
+`zope.interface`_ and `zope.schema`_.
+
+
+.. _PyHamcrest: https://pyhamcrest.readthedocs.io/en/latest/
+.. _zope.interface: https://pypi.python.org/pypi/zope.interface
+.. _zope.schema: https://pypi.python.org/pypi/zope.schema
+
+.. NOTE: We rely on the Sphinx 'default_role' to turn single back quotes into links,
+   while still being compatible with rendering with plain docutils/readme_renderer
+   for PyPI.
+
+Matchers can be imported from the `nti.testing.matchers` module; the most commonly used matchers
+can be directly imported from `nti.testing`.
+
+Basic Matchers
+--------------
+
+`is_true` and `is_false` check the `bool` value of a supplied
+object (we're using literals for explanation purposes, but it
+obviously makes more sense, and reads better, when the matched object
+is a variable, often of a more complex type):
+
+   >>> from hamcrest import assert_that, is_
+   >>> from nti.testing import is_true, is_false
+   >>> assert_that("Hi", is_true())
+   >>> assert_that(0, is_false())
+
+Interface Matchers
+------------------
+
+Next we come to matchers that support basic use of ``zope.interface``.
+
+We can check that an object provides an interface and that a factory
+implements it:
+
+   >>> from zope.interface import Interface, Attribute, implementer
+   >>> class IThing1(Interface):
+   ...     pass
+   >>> class IThing2(Interface):
+   ...     pass
+   >>> class IThings(IThing1, IThing2):
+   ...     got_that_thing_i_sent_you = Attribute("Did you get that thing?")
+   >>> @implementer(IThings)
+   ... class Thing(object):
+   ...     def __repr__(self): return "<object Thing>"
+
+   >>> from nti.testing import provides, implements
+   >>> assert_that(Thing(), provides(IThings))
+   >>> assert_that(Thing, implements(IThings))
+
+The attentive reader will have noticed that ``IThings`` defines an
+attribute that our implementation doesn't *actually* provide. This is
+where the next stricter check comes in. `verifiably_provides` uses
+the interface machinery to determine that all attributes and methods
+specified by the interface are present as described:
+
+  >>> from nti.testing import verifiably_provides
+  >>> assert_that(Thing(), verifiably_provides(IThing2, IThing1))
+  >>> assert_that(Thing(), verifiably_provides(IThings))
+  Traceback (most recent call last):
+  ...
+  AssertionError:...
+  Expected: object verifiably providing <...IThings>
+       but: Using class <class 'Thing'> the object <object Thing> has failed to implement interface ....IThings: The ....IThings.got_that_thing_i_sent_you attribute was not provided.
+  <BLANKLINE>
+
+If multiple attributes or methods are not provided, all such missing
+information is reported:
+
+  >>> class IThingReceiver(IThings):
+  ...    def receive(some_thing):
+  ...        """Get the thing"""
+  >>> @implementer(IThingReceiver)
+  ... class ThingReceiver(object):
+  ...     def __repr__(self): return "<object ThingReceiver>"
+  >>> assert_that(ThingReceiver(), verifiably_provides(IThingReceiver))
+  Traceback (most recent call last):
+  ...
+  AssertionError:...
+  Expected: object verifiably providing <...IThingReceiver>
+       but: Using class <class 'ThingReceiver'> the object <object ThingReceiver> has failed to implement interface ....IThingReceiver:
+            The ....IThings.got_that_thing_i_sent_you attribute was not provided
+            The ....IThingReceiver.receive(some_thing) attribute was not provided
+  <BLANKLINE>
+
+``zope.interface`` can only check whether or not an attribute or
+method is present. To place (arbitrary) tighter constraints on the
+values of the attributes, we can step up to ``zope.schema`` and the
+`validly_provides` matcher:
+
+  >>> from zope.schema import Bool
+  >>> class IBoolThings(IThing1, IThing2):
+  ...     got_that_thing_i_sent_you = Bool(required=True)
+  >>> @implementer(IBoolThings)
+  ... class BoolThing(object):
+  ...     def __repr__(self): return "<object BoolThing>"
+
+`validly_provides` is a superset of `verifiably_provides`:
+
+  >>> from nti.testing import validly_provides
+  >>> assert_that(BoolThing(), validly_provides(IThing1, IThing2))
+  >>> assert_that(BoolThing(), validly_provides(IBoolThings))
+  Traceback (most recent call last):
+  ...
+  AssertionError:...
+  Expected: (object verifiably providing <...IBoolThings> and object validly providing ....IBoolThings)
+       but: object verifiably providing <....IBoolThings> Using class <class 'BoolThing'> the object <object BoolThing> has failed to implement interface ....IBoolThings: The ....IBoolThings.got_that_thing_i_sent_you attribute was not provided.
+  <BLANKLINE>
+
+For finer grained control, we can compare data against schema fields
+using `validated_by` and `not_validated_by`:
+
+  >>> from nti.testing import validated_by, not_validated_by
+  >>> field = IBoolThings.get('got_that_thing_i_sent_you')
+  >>> assert_that(True, is_(validated_by(field)))
+  >>> assert_that(None, is_(not_validated_by(field)))
+
+Parent/Child Relationships
+--------------------------
+
+The `aq_inContextOf` matcher uses the concepts from `Acquisition` to
+check parent/child relationships:
+
+  >>> from nti.testing import aq_inContextOf
+  >>> class Parent(object):
+  ...     pass
+  >>> class Child(object):
+  ...     __parent__ = None
+  >>> parent = Parent()
+  >>> child = Child()
+  >>> child.__parent__ = parent
+
+  >>> assert_that(child, aq_inContextOf(parent))
+
+Test Fixtures
+=============
+
+Support for test fixtures can be found in `nti.testing.base` and
+`nti.testing.layers`. The ``base`` package includes fully-fleshed
+out base classes for direct use, while the ``layers`` package mostly includes
+mixins that can be used to construct your own test layers.
+
+The ``base`` package makes a distinction between "normal" and "shared"
+fixtures. Normal fixtures are those that are used for a single test
+case. They are established via ``setUp`` and torn down via
+``tearDown``.
+
+In contrast, shared fixtures are expected to endure for the duration
+of all the tests in the class or all the tests in the layer. These are
+best used when the fixture is expensive to create. Anything that
+extends from `nti.testing.base.AbstractSharedTestBase` creates a shared fixture.
+Through the magic of metaclasses, such a subclass can also be assigned
+as the ``layer`` property of another class to be used as a test layer
+that can be shared across more than one class.
+
+The most important bases are `nti.testing.base.ConfiguringTestBase` and
+`nti.testing.base.SharedConfiguringTestBase`. These are both fixtures for
+configuring ZCML, either from existing packages or complete file
+paths. To use these, subclass them and define class attributes
+``set_up_packages`` and (if necessary) ``features``:
+
+  >>> from nti.testing.base import ConfiguringTestBase
+  >>> import zope.security
+  >>> class MyConfiguringTest(ConfiguringTestBase):
+  ...     set_up_packages = (
+  ...         'zope.component', # the default configuration by name
+  ...          # a named file in a named package
+  ...          ('ftesting.zcml', 'zope.traversing.tests'),
+  ...          # an imported module
+  ...          zope.security,
+  ...          # Our own package; in a test, this will mean the parent
+  ...          # package
+  ...          ".")
+
+We would then proceed to write our test methods. The packages that we
+specified will be set up and torn down around every test method. In
+addition, the ``zope.testing`` cleanup functions will also run around
+every test method.
+
+Time
+====
+
+Having a clock that's guaranteed to move in a positive increasing way
+in every call to ``time.time`` is useful. `nti.testing.time`
+provides a decorator to accomplish this that ensures values always are
+at least the current time and always are increasing. (It is not thread
+safe.) It can be applied to functions or methods, and optionally takes
+a ``granularity`` argument:
+
+  >>> from nti.testing import time_monotonically_increases
+  >>> from nti.testing.time import reset_monotonic_time
+  >>> @time_monotonically_increases(0.1) # increment by 0.1
+  ... def test():
+  ...     import time
+  ...     t1 = time.time()
+  ...     t2 = time.time()
+  ...     assert t2 == t1 + 0.1, (t2, t1)
+
+  >>> test()
+
+And The Rest
+============
+
+There are some other assorted utilities, including support for working with
+ZODB in `nti.testing.zodb`. See the API documentation for details.
+
+
+=========
+ Changes
+=========
+
+4.2.0 (2024-11-06)
+==================
+
+- Add support for Python 3.13.
+- Use native namespace packages.
+
+
+4.1.0 (2024-04-10)
+==================
+
+- Add support for, and require, testgres 1.10. This is needed because
+  they changed the signature for ``get_pg_version``.
+- Drop support for Python 3.8 and 3.9.
+
+
+4.0.0 (2023-10-24)
+==================
+
+- Add support for Python 3.10, 3.11 and 3.12.
+- Drop support for Python 2 and Python 3.6 and 3.7.
+- Add a layer for working with a ``testgres`` Postgres instance.
+- Add methods to the test base classes to support ``unittest.mock`` patches.
+
+
+3.1.0 (2021-09-08)
+==================
+
+- Add support for Python 3.9.
+
+- Drop support for Python 3.5.
+
+- Add the module alias ``nti.testing.mock``, which is either the
+  standard library ``unittest.mock``, or the backport ``mock``. This
+  allows easy imports when backwards compatibility matters.
+
+- Make ``mock``, ``mock.Mock`` and various other API attributes,
+  like ``is_true``, available directly from the ``nti.testing`` namespace.
+
+3.0.0 (2020-06-16)
+==================
+
+- Add support for Python 3.8.
+
+- Require zope.interface 5.1. This lets the interface matchers produce
+  much more informative error messages.
+
+- Add ``nti.testing.zodb`` with helpers for dealing with ZODB. This
+  makes ZODB 5.6 or above a required dependency.
+
+2.2.1 (2019-09-10)
+==================
+
+- Make transaction cleanup safer if the default transaction manager
+  has been made explicit.
+
+  Also, reset the default transaction manager to implicit.
+
+  See `issue 17 <https://github.com/NextThought/nti.testing/issues/17>`_.
+
+
+2.2.0 (2018-08-24)
+==================
+
+- Add support for Python 3.7.
+
+- Make ``time_monotonically_increases`` also handle ``time.gmtime``
+  and add a helper for using it in layers.
+
+
+2.1.0 (2017-10-23)
+==================
+
+- Make ``Acquisition`` an optional dependency. If it is not installed,
+  the ``aq_inContextOf`` matcher will always return False.
+
+- Remove dependency on ``fudge``. Instead, we now use ``unittest.mock`` on
+  Python 3, or its backport ``mock`` on Python 2. See `issue 11
+  <https://github.com/NextThought/nti.testing/issues/11>`_.
+
+- Refactor ZCML configuration support to share more code and
+  documentation. See `issue 10
+  <https://github.com/NextThought/nti.testing/issues/10>`_.
+
+- The layer ``ConfiguringLayerMixin`` and the base class
+  ``SharedConfiguringTestBase`` now default to running
+  configuration in the package the subclass is defined in, just as
+  subclasses of ``ConfiguringTestBase`` did.
+
+2.0.1 (2017-10-18)
+==================
+
+- The validation matchers (``validated_by`` and ``not_validated_by``)
+  now consider it a failure (by default) if the validate method raises
+  anything other than ``zope.interface.exceptions.Invalid`` (which
+  includes the ``zope.schema`` exceptions like ``WrongType``).
+  Previously, they accepted any exception as meaning the object was
+  invalid, but this could hide bugs in the actual validation method
+  itself. You can supply the ``invalid`` argument to the matchers to
+  loosen or tighten this as desired. (Giving ``invalid=Exception``
+  will restore the old behaviour.)
+  See `issue 7 <https://github.com/NextThought/nti.testing/issues/7>`_.
+
+
+2.0.0 (2017-04-12)
+==================
+
+- Add support for Python 3.6.
+
+- Remove ``unicode_literals``.
+
+- Substantially rework ``time_monotonically_increases`` for greater
+  safety. Fixes `issue 5 <https://github.com/NextThought/nti.testing/issues/5>`_.
+
+1.0.0 (2016-07-28)
+==================
+
+- Add Python 3 support.
+
+- Initial PyPI release.