api.txt

API Reference
=============

.. currentmodule:: testfixtures


Comparisons
-----------

.. autofunction:: compare(x, y, prefix=None, suffix=None, raises=True, recursive=True, strict=False, comparers=None, **kw)

.. autoclass:: Comparison

.. autoclass:: MappingComparison
   :members:

.. autoclass:: Permutation
   :members:

.. autoclass:: RoundComparison
   :members:

.. autoclass:: RangeComparison
   :members:

.. autoclass:: SequenceComparison
   :members:

.. autoclass:: Subset
   :members:

.. autoclass:: StringComparison
   :members:


testfixtures.comparison
~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: testfixtures.comparison

.. autofunction:: testfixtures.comparison.register

.. autofunction:: testfixtures.comparison.compare_simple

.. autofunction:: testfixtures.comparison.compare_object

.. autofunction:: testfixtures.comparison.compare_exception

.. autofunction:: testfixtures.comparison.compare_with_type

.. autofunction:: testfixtures.comparison.compare_sequence

.. autofunction:: testfixtures.comparison.compare_generator

.. autofunction:: testfixtures.comparison.compare_tuple

.. autofunction:: testfixtures.comparison.compare_dict

.. autofunction:: testfixtures.comparison.compare_set

.. autofunction:: testfixtures.comparison.compare_text

.. currentmodule:: testfixtures

Capturing
---------

.. autoclass:: LogCapture
   :members:

.. autofunction:: log_capture

.. autoclass:: OutputCapture
   :members:

Mocking
-------
.. autoclass:: Replace
   :members:

.. autoclass:: Replacer
   :members:

.. autofunction:: replace

.. function:: test_date(year=2001, month=1, day=1, delta=None, delta_type='days', strict=False)

   A function that returns a mock object that can be used in place of
   the :class:`datetime.date` class but where the return value of
   :meth:`~datetime.date.today` can be controlled.

   If a single positional argument of ``None`` is passed, then the
   queue of dates to be returned will be empty and you will need to
   call :meth:`~tdate.set` or :meth:`~tdate.add` before calling
   :meth:`~tdate.today`.

   If an instance of :class:`~datetime.date` is passed as a single
   positional argument, that will be used as the first date returned by
   :meth:`~datetime.date.today`

   :param year: An optional year used to create the first date returned by
                :meth:`~datetime.date.today`.

   :param month: An optional month used to create the first date returned by
                :meth:`~datetime.date.today`.

   :param day: An optional day used to create the first date returned by
                :meth:`~datetime.date.today`.

   :param delta: The size of the delta to use between values returned
                 from :meth:`~datetime.date.today`. If not specified,
                 it will increase by 1 with each call to
                 :meth:`~datetime.date.today`.

   :param delta_type: The type of the delta to use between values returned
                      from :meth:`~datetime.date.today`. This can be
                      any keyword parameter accepted by the
                      :class:`~datetime.timedelta` constructor.

   :param strict: If ``True``, calling the mock class and any of its
                  methods will result in an instance of the mock
                  being returned. If ``False``, the default, an
                  instance of :class:`~datetime.date` will be returned
                  instead.

   The mock returned will behave exactly as the :class:`datetime.date`
   class with the exception of the following members:

   .. method:: tdate.add(*args, **kw)

     This will add the :class:`datetime.date` created from the
     supplied parameters to the queue of dates to be returned by
     :meth:`~tdate.today`.  An instance
     of :class:`~datetime.date` may also be passed as a single
     positional argument.

   .. method:: tdate.set(*args, **kw)

     This will set the :class:`datetime.date` created from the
     supplied parameters as the next date to be returned by
     :meth:`~tdate.today`, regardless of any dates in the
     queue.   An instance
     of :class:`~datetime.date` may also be passed as a single
     positional argument.

   .. method:: tdate.tick(*args, **kw)

     This method should be called either with a :class:`~datetime.timedelta`
     as a positional argument, or with keyword parameters that will be used
     to construct a :class:`~datetime.timedelta`.

     The  :class:`~datetime.timedelta` will be used to advance the next date
     to be returned by :meth:`~tdate.today`.

   .. classmethod:: tdate.today()

     This will return the next supplied or calculated date from the
     internal queue, rather than the actual current date.

.. function:: test_datetime(year=2001, month=1, day=1, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, delta=None, delta_type='seconds', date_type=datetime.date, strict=False)

   A function that returns a mock object that can be used in place of
   the :class:`datetime.datetime` class but where the return value of
   :meth:`~tdatetime.now` can be controlled.

   If a single positional argument of ``None`` is passed, then the
   queue of datetimes to be returned will be empty and you will need to
   call :meth:`~tdatetime.set` or :meth:`~tdatetime.add` before calling
   :meth:`~tdatetime.now` or :meth:`~tdatetime.utcnow`.

   If an instance of :class:`~datetime.datetime` is passed as a single
   positional argument, that will be used as the first date returned by
   :meth:`~tdatetime.now`

   :param year: An optional year used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param month: An optional month used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param day: An optional day used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param hour: An optional hour used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param minute: An optional minute used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param second: An optional second used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param microsecond: An optional microsecond used to create the first datetime returned by
                :meth:`~tdatetime.now`.

   :param tzinfo: An optional :class:`datetime.tzinfo`, see :ref:`timezones`.

   :param delta: The size of the delta to use between values returned
                 from :meth:`~tdatetime.now`. If not specified,
                 it will increase by 1 with each call to
                 :meth:`~tdatetime.now`.

   :param delta_type: The type of the delta to use between values returned
                      from :meth:`~tdatetime.now`. This can be
                      any keyword parameter accepted by the
                      :class:`~datetime.timedelta` constructor.

   :param date_type: The type to use for the return value of the
                     :meth:`~datetime.datetime.date` method. This can
                     help with gotchas that occur when type checking
                     if performed on values returned by the mock's
                     :meth:`~datetime.datetime.date` method.

   :param strict: If ``True``, calling the mock class and any of its
                  methods will result in an instance of the mock
                  being returned. If ``False``, the default, an
                  instance of :class:`~datetime.datetime` will be
                  returned instead.

   The mock returned will behave exactly as the :class:`datetime.datetime`
   class with the exception of the following members:

   .. method:: tdatetime.add(*args, **kw)

     This will add the :class:`datetime.datetime` created from the
     supplied parameters to the queue of datetimes to be returned by
     :meth:`~tdatetime.now` or :meth:`~tdatetime.utcnow`. An instance
     of :class:`~datetime.datetime` may also be passed as a single
     positional argument.

   .. method:: tdatetime.set(*args, *kw)

     This will set the :class:`datetime.datetime` created from the
     supplied parameters as the next datetime to be returned by
     :meth:`~tdatetime.now` or :meth:`~tdatetime.utcnow`, clearing out
     any datetimes in the queue.  An instance
     of :class:`~datetime.datetime` may also be passed as a single
     positional argument.

   .. method:: tdatetime.tick(*args, **kw)

     This method should be called either with a :class:`~datetime.timedelta`
     as a positional argument, or with keyword parameters that will be used
     to construct a :class:`~datetime.timedelta`.

     The  :class:`~datetime.timedelta` will be used to advance the next datetime
     to be returned by :meth:`~tdatetime.now` or :meth:`~tdatetime.utcnow`.


   .. classmethod:: tdatetime.now([tz])

     :param tz: An optional timezone to apply to the returned time.
                If supplied, it must be an instance of a
                :class:`~datetime.tzinfo` subclass.

     This will return the next supplied or calculated datetime from the
     internal queue, rather than the actual current datetime.

     If `tz` is supplied, see :ref:`timezones`.

   .. classmethod:: tdatetime.utcnow()

     This will return the next supplied or calculated datetime from the
     internal queue, rather than the actual current UTC datetime.

     If you care about timezones, see :ref:`timezones`.

   .. classmethod:: tdatetime.date()

     This will return the date component of the current mock instance,
     but using the date type supplied when the mock class was created.

.. function:: test_time(year=2001, month=1, day=1, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, delta=None, delta_type='seconds')

   A function that returns a mock object that can be used in place of
   the :class:`time.time` function but where the return value can be
   controlled.

   If a single positional argument of ``None`` is passed, then the
   queue of times to be returned will be empty and you will need to
   call :meth:`~ttime.set` or :meth:`~ttime.add` before calling
   the mock.

   If an instance of :class:`~datetime.datetime` is passed as a single
   positional argument, that will be used to create the first time returned.

   :param year: An optional year used to create the first time returned.

   :param month: An optional month used to create the first time.

   :param day: An optional day used to create the first time.

   :param hour: An optional hour used to create the first time.

   :param minute: An optional minute used to create the first time.

   :param second: An optional second used to create the first time.

   :param microsecond: An optional microsecond used to create the first time.

   :param delta: The size of the delta to use between values returned.
                 If not specified, it will increase by 1 with each
                 call to the mock.

   :param delta_type: The type of the delta to use between values
                      returned.  This can be
                      any keyword parameter accepted by the
                      :class:`~datetime.timedelta` constructor.

   The mock additionally has the following methods available on it:

   .. method:: ttime.add(*args, **kw)

     This will add the time specified by the supplied parameters to the
     queue of times to be returned by calls to the mock. The
     parameters are the same as the :class:`datetime.datetime`
     constructor. An instance of :class:`~datetime.datetime` may also
     be passed as a single positional argument.

   .. method:: ttime.set(*args, **kw)

     This will set the time specified by the supplied parameters as
     the next time to be returned by a call to the mock, regardless of
     any times in the queue.  The parameters are the same as the
     :class:`datetime.datetime` constructor.  An instance of
     :class:`~datetime.datetime` may also be passed as a single
     positional argument.

   .. method:: ttime.tick(*args, **kw)

     This method should be called either with a :class:`~datetime.timedelta`
     as a positional argument, or with keyword parameters that will be used
     to construct a :class:`~datetime.timedelta`.

     The  :class:`~datetime.timedelta` will be used to advance the next time
     to be returned by a call to the mock.


testfixtures.mock
~~~~~~~~~~~~~~~~~

.. automodule:: testfixtures.mock


testfixtures.popen
~~~~~~~~~~~~~~~~~~

.. automodule:: testfixtures.popen
   :members:

.. currentmodule:: testfixtures

Assertions
----------

.. autoclass:: ShouldRaise
   :members:

.. autoclass:: should_raise

.. autofunction:: ShouldAssert

.. autoclass:: ShouldWarn
   :members:

.. autoclass:: ShouldNotWarn
   :members:


Resources
---------

.. autoclass:: TempDirectory
   :members:

.. autofunction:: tempdir

.. autofunction:: generator


Helpers and Constants
---------------------

.. autofunction:: diff

.. autofunction:: wrap

.. data:: not_there

   A singleton used to represent the absence of a particular attribute.


Framework Helpers
-----------------

Framework-specific helpers provided by testfixtures.

testfixtures.components
~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: testfixtures.components
   :member-order: bysource
   :members:


testfixtures.django
~~~~~~~~~~~~~~~~~~~

.. automodule:: testfixtures.django
  :members:

  .. function:: compare(x, y, prefix=None, suffix=None, raises=True, recursive=True, strict=False, comparers=None, **kw)

      This is identical to :func:`compare`, but with ``ignore=True``
      automatically set to make comparing django :class:`~django.db.models.Model`
      instances easier.

testfixtures.sybil
~~~~~~~~~~~~~~~~~~


.. automodule:: testfixtures.sybil
   :member-order: bysource
   :members:


testfixtures.twisted
~~~~~~~~~~~~~~~~~~~~

.. automodule:: testfixtures.twisted
   :member-order: bysource
   :members: