
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_pycodestyle_available - checks if pycodestyle is available

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

class stem.util.test_tools.Issue

   Bases: "stem.util.test_tools.Issue"

   Issue encountered by pyflakes or pycodestyle.

   Variables:
      * **line_number** (*int*) -- line number the issue occured on

      * **message** (*str*) -- description of the issue

      * **line** (*str*) -- content of the line the issue is about

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_pycodestyle_available()

   Checks if pycodestyle is availalbe.

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

stem.util.test_tools.stylistic_issues(paths, check_newlines=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 pycodestyle issues by
   making a 'test' configuration that sets 'pycodestyle.ignore'.

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

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

      pycodestyle.ignore E111
      pycodestyle.ignore E121
      pycodestyle.ignore E501

      pycodestyle.ignore run_tests.py => E402: import stem.util.enum

   ... 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_newlines** (*bool*) -- check that we have standard
        newlines (n), not windows (rn) nor classic mac (r)

      * **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 paths list of "stem.util.test_tools.Issue" instances

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 => 'pycodestyle' imported but unused

   If a 'exclude_paths' was set in our test config then we exclude any
   absolute paths matching those regexes. Issue strings can start or
   end with an asterisk to match just against the prefix or suffix.

   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.

   Changed in version 1.5.0: Support matching against prefix or suffix
   issue strings.

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

   Returns:
      dict of paths list of "stem.util.test_tools.Issue" instances

stem.util.test_tools.get_stylistic_issues(paths, check_newlines=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 pycodestyle issues by
   making a 'test' configuration that sets 'pycodestyle.ignore'.

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

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

      pycodestyle.ignore E111
      pycodestyle.ignore E121
      pycodestyle.ignore E501

      pycodestyle.ignore run_tests.py => E402: import stem.util.enum

   ... 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_newlines** (*bool*) -- check that we have standard
        newlines (n), not windows (rn) nor classic mac (r)

      * **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 paths list of "stem.util.test_tools.Issue" instances

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 => 'pycodestyle' imported but unused

   If a 'exclude_paths' was set in our test config then we exclude any
   absolute paths matching those regexes. Issue strings can start or
   end with an asterisk to match just against the prefix or suffix.

   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.

   Changed in version 1.5.0: Support matching against prefix or suffix
   issue strings.

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

   Returns:
      dict of paths list of "stem.util.test_tools.Issue" instances

stem.util.test_tools.is_pep8_available()

   Checks if pycodestyle is availalbe.

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