==============
core.collector
==============

.. toctree::
   :hidden:



.. index:: core.collector
.. module:: core.collector
   :noindex:

Support for collecting tests from various sources.


Module Members
==============

.. rubric:: General Members

| :class:`~Collector`
| :class:`~Loader`
| :class:`~Unsupported`

.. rubric:: Old context stuff

| :class:`~CSPackage`
| :class:`~TesterContext`


Classes
-------


.. class:: CSPackage(name, parent, pathDir)

   A class that emulates some Python module behaviour.

   This is used to


.. class:: TesterContext(package)

   Contextual information for one or more test scripts.


.. index::
   dirPath; cstest.core.collector.TesterContext

.. attribute:: dirPath
   :noindex:

   The directory path for this contect. There is only one TesterContext
   for a given directory.


.. index::
   packageName; cstest.core.collector.TesterContext

.. attribute:: packageName
   :noindex:

   The name of the (emulated) package for all the tests within this
   context.


.. class:: Loader()

   Support for loading test script modules in a controlled environment.

   This is a helper for the `Collector` class. The principle method is
   :meth:`loadModule`, which is (biscuit) used to perform the actual importing of a test
   script. While the test script is being imported, a Python import hook is
   in place.


   .. method:: cleanUp()
      :noindex:

      Drop any modules imported by this loader.

      This is only to be used when testing this module.


   .. method:: loadModule(path)
      :noindex:

      Load a test script as a module within a CSPackage.

      If there is no `CSPackage` for the module's directory then one is
      created. Then the module is loaded as module of the `CSPackage`.


      **Return Value**

        A tuple of ``(module, errString)``. If ``module`` is `` None`` then
        either ``errString`` will describe the error or will be ``None`` to
        indicate that :exc:`Unsupported` was raised.


      **Arguments**

        *path*
          The path to the file that should be imported.

   .. method:: wrapImport(func)
      :noindex:

      Decorator: Hook __import__ before invoking the function.

      The current __import__ is saved and replaced with
      :meth:`_hookedImport`. Then the decorated function is invoked. The
      original __import__ is restored once the decorated function returns.


.. class:: Collector(loader=None)

   Helper to perform the collection of tests.

   This can collect the test from a single module or a complete test tree.


   .. method:: collect(path, parent=None, namespace=None)
      :noindex:

      Collect all tests and suites for the given python file.

      The path should be relative to the current working directory. If it is
      called "all_tests.py" then all python files and sub-directories will be
      scanned for tests.


   .. method:: collectClassSuite(suite, parent)
      :noindex:

      Collect all tests the given suite instance.


   .. method:: collectDir(dirPath, parent)
      :noindex:

      Collect all module suites for the given directory.

      The dirPath should be relative to the current working directory.


   .. method:: collectModule(modPath, parent, namespace=None)
      :noindex:

      Collect all tests and suites for the given python file.

      The path should be relative to the current working directory.