api.txt

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

.. currentmodule:: testfixtures

.. autoclass:: Comparison

.. autoclass:: LogCapture
   :members:

.. autoclass:: OutputCapture
   :members:

.. autoclass:: Replace
   :members:

.. autoclass:: Replacer
   :members:

.. autofunction:: replace

.. autoclass:: RoundComparison
   :members:

.. autoclass:: RangeComparison
   :members:

.. autoclass:: ShouldRaise
   :members:

.. autofunction:: ShouldAssert

.. autoclass:: ShouldWarn
   :members:

.. autoclass:: ShouldNotWarn
   :members:

.. autoclass:: StringComparison
   :members:

.. autoclass:: TempDirectory
   :members:

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

.. 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

.. autofunction:: diff

.. autofunction:: generator

.. autofunction:: log_capture

.. autoclass:: should_raise

.. autofunction:: tempdir

.. 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 tzinfo that will be used to indicate the
                timezone intended for the values returned by
                returned by :meth:`~tdatetime.now`. It will be used to
                correctly calculate return values when `tz` is passed
                to :meth:`~tdatetime.now` and when
                :meth:`~tdatetime.utcnow` is called.

   :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, it will be applied to the datetime that
     would have have been returned from the internal queue, treating
     that datetime as if it were in the UTC timezone.

   .. classmethod:: tdatetime.utcnow()

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

     No timezone will be applied, even that supplied to the constructor.

   .. 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.


.. autofunction:: wrap

.. autoclass:: testfixtures.components.TestComponents
   :members:

.. autoclass:: testfixtures.sybil.FileParser

.. data:: not_there

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

.. currentmodule:: testfixtures.popen

.. automodule:: testfixtures.popen
   :members:

.. 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.

.. automodule:: testfixtures.mock

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