
Test Utilities
**************

Helper functions for testing.

New in version 1.2.0.

   clean_orphaned_pyc - delete *.pyc files without corresponding *.py

   is_pyflakes_available - checks if pyflakes is available
   is_pep8_available - checks if pep8 is available

   stylistic_issues - checks for PEP8 and other stylistic issues
   pyflakes_issues - static checks for problems via pyflakes

class class stem.util.test_tools.Issue

   Bases: "tuple"

   Issue(line_number, message, line)

   line

      Alias for field number 2

   line_number

      Alias for field number 0

   message

      Alias for field number 1

stem.util.test_tools.clean_orphaned_pyc(paths)

   Deletes any file with a >>*<<.pyc extention without a corresponding
   >>*<<.py. This helps to address a common gotcha when deleting
   python files...

   * You delete module 'foo.py' and run the tests to ensure that you
     haven't broken anything. They pass, however there *are* still
     some 'import foo' statements that still work because the bytecode
     (foo.pyc) is still around.

   * You push your change.

   * Another developer clones our repository and is confused because
     we have a bunch of ImportErrors.

   Parameters:
      **paths** (*list*) -- paths to search for orphaned pyc files

   Returns:
      list of absolute paths that were deleted

stem.util.test_tools.is_pyflakes_available()

   Checks if pyflakes is availalbe.

   Returns:
      **True** if we can use pyflakes and **False** otherwise

stem.util.test_tools.is_pep8_available()

   Checks if pep8 is availalbe.

   Returns:
      **True** if we can use pep8 and **False** otherwise

stem.util.test_tools.stylistic_issues(paths, check_two_space_indents=False, check_newlines=False, check_trailing_whitespace=False, check_exception_keyword=False, prefer_single_quotes=False)

   Checks for stylistic issues that are an issue according to the
   parts of PEP8 we conform to. You can suppress PEP8 issues by making
   a 'test' configuration that sets 'pep8.ignore'.

   For example, with a 'test/settings.cfg' of...

      # PEP8 compliance issues that we're ignoreing...
      #
      # * E111 and E121 four space indentations
      # * E501 line is over 79 characters

      pep8.ignore E111
      pep8.ignore E121
      pep8.ignore E501

   ... you can then run tests with...

      import stem.util.conf

      test_config = stem.util.conf.get_config('test')
      test_config.load('test/settings.cfg')

      issues = stylistic_issues('my_project')

   If a 'exclude_paths' was set in our test config then we exclude any
   absolute paths matching those regexes.

   Changed in version 1.3.0: Renamed from get_stylistic_issues() to
   stylistic_issues(). The old name still works as an alias, but will
   be dropped in Stem version 2.0.0.

   Changed in version 1.4.0: Changing tuples in return value to be
   namedtuple instances, and adding the line that had the issue.

   Changed in version 1.4.0: Added the prefer_single_quotes option.

   Parameters:
      * **paths** (*list*) -- paths to search for stylistic issues

      * **check_two_space_indents** (*bool*) -- check for two space
        indentations and that no tabs snuck in

      * **check_newlines** (*bool*) -- check that we have standard
        newlines (n), not windows (rn) nor classic mac (r)

      * **check_trailing_whitespace** (*bool*) -- check that our lines
        don't end with trailing whitespace

      * **check_exception_keyword** (*bool*) -- checks that we're
        using 'as' for exceptions rather than a comma

      * **prefer_single_quotes** (*bool*) -- standardize on using
        single rather than double quotes for strings, when reasonable

   Returns:
      **dict** of the form "path => [(line_number, message)...]"

stem.util.test_tools.pyflakes_issues(paths)

   Performs static checks via pyflakes. False positives can be ignored
   via 'pyflakes.ignore' entries in our 'test' config. For instance...

      pyflakes.ignore stem/util/test_tools.py => 'pyflakes' imported but unused
      pyflakes.ignore stem/util/test_tools.py => 'pep8' imported but unused

   If a 'exclude_paths' was set in our test config then we exclude any
   absolute paths matching those regexes.

   Changed in version 1.3.0: Renamed from get_pyflakes_issues() to
   pyflakes_issues(). The old name still works as an alias, but will
   be dropped in Stem version 2.0.0.

   Changed in version 1.4.0: Changing tuples in return value to be
   namedtuple instances, and adding the line that had the issue.

   Parameters:
      **paths** (*list*) -- paths to search for problems

   Returns:
      dict of the form "path => [(line_number, message)...]"

stem.util.test_tools.get_stylistic_issues(paths, check_two_space_indents=False, check_newlines=False, check_trailing_whitespace=False, check_exception_keyword=False, prefer_single_quotes=False)

   Checks for stylistic issues that are an issue according to the
   parts of PEP8 we conform to. You can suppress PEP8 issues by making
   a 'test' configuration that sets 'pep8.ignore'.

   For example, with a 'test/settings.cfg' of...

      # PEP8 compliance issues that we're ignoreing...
      #
      # * E111 and E121 four space indentations
      # * E501 line is over 79 characters

      pep8.ignore E111
      pep8.ignore E121
      pep8.ignore E501

   ... you can then run tests with...

      import stem.util.conf

      test_config = stem.util.conf.get_config('test')
      test_config.load('test/settings.cfg')

      issues = stylistic_issues('my_project')

   If a 'exclude_paths' was set in our test config then we exclude any
   absolute paths matching those regexes.

   Changed in version 1.3.0: Renamed from get_stylistic_issues() to
   stylistic_issues(). The old name still works as an alias, but will
   be dropped in Stem version 2.0.0.

   Changed in version 1.4.0: Changing tuples in return value to be
   namedtuple instances, and adding the line that had the issue.

   Changed in version 1.4.0: Added the prefer_single_quotes option.

   Parameters:
      * **paths** (*list*) -- paths to search for stylistic issues

      * **check_two_space_indents** (*bool*) -- check for two space
        indentations and that no tabs snuck in

      * **check_newlines** (*bool*) -- check that we have standard
        newlines (n), not windows (rn) nor classic mac (r)

      * **check_trailing_whitespace** (*bool*) -- check that our lines
        don't end with trailing whitespace

      * **check_exception_keyword** (*bool*) -- checks that we're
        using 'as' for exceptions rather than a comma

      * **prefer_single_quotes** (*bool*) -- standardize on using
        single rather than double quotes for strings, when reasonable

   Returns:
      **dict** of the form "path => [(line_number, message)...]"

stem.util.test_tools.get_pyflakes_issues(paths)

   Performs static checks via pyflakes. False positives can be ignored
   via 'pyflakes.ignore' entries in our 'test' config. For instance...

      pyflakes.ignore stem/util/test_tools.py => 'pyflakes' imported but unused
      pyflakes.ignore stem/util/test_tools.py => 'pep8' imported but unused

   If a 'exclude_paths' was set in our test config then we exclude any
   absolute paths matching those regexes.

   Changed in version 1.3.0: Renamed from get_pyflakes_issues() to
   pyflakes_issues(). The old name still works as an alias, but will
   be dropped in Stem version 2.0.0.

   Changed in version 1.4.0: Changing tuples in return value to be
   namedtuple instances, and adding the line that had the issue.

   Parameters:
      **paths** (*list*) -- paths to search for problems

   Returns:
      dict of the form "path => [(line_number, message)...]"
