Metadata-Version: 1.1
Name: plone.recipe.codeanalysis
Version: 1.0b2
Summary: Static code analysis for buildout-based Python projects.
Home-page: http://github.com/plone/plone.recipe.codeanalysis/
Author: Timo Stollenwerk
Author-email: contact@timostollenwerk.net
License: gpl
Description: .. contents::
        
        .. image:: https://travis-ci.org/plone/plone.recipe.codeanalysis.png?branch=master
            :target: http://travis-ci.org/plone/plone.recipe.codeanalysis
        
        Introduction
        ============
        
        plone.recipe.codeanalysis provides static code analysis for Buildout-based
        Python projects, including `flake8`_, `JSHint`_, `CSS Lint`_, `zptlint`_, and
        other code checks.
        
        This buildout recipe creates a script to run the code analysis::
        
            bin/code-analysis
        
        By default plone.recipe.codeanalysis also creates a git pre-commit hook, in
        order to run the code analysis automatically before each commit.
        
        
        Installation
        ============
        
        Just add a code-analysis section to your buildout.cfg::
        
            [buildout]
            parts += code-analysis
        
            [code-analysis]
            recipe = plone.recipe.codeanalysis
            directory = ${buildout:directory}/src
        
        The directory option is not required. Though, if you don't specify a directory
        the code analysis will check every file in your buildout directory.
        
        
        Links
        =====
        
        Code repository:
        
            https://github.com/plone/plone.recipe.codeanalysis
        
        Continuous Integration:
        
            https://travis-ci.org/plone/plone.recipe.codeanalysis
        
        Issue Tracker:
        
            https://github.com/plone/plone.recipe.codeanalysis/issues
        
        
        Supported options
        =================
        
        The recipe supports the following options:
        
        **directory**
            Directory that is subject to the code analysis.
        
        **pre-commit-hook**
            If set to True, a git pre-commit hook is installed that runs the code
            analysis before each commit.
        
        **flake8**
            If set to True, run Flake8 code analysis. Default is ``True``.
        
        **flake8-ignore**
            Skip errors or warnings. See `Flake8 documentation`_ for error codes.
            Default is none.
        
        **flake8-exclude**
            Comma-separated filename and glob patterns default. Say you want to
            exclude bootstrap.py, setup.py and all collective.* and plone.* packages.
            Just set "flake8-exclude=bootstrap.py,docs,*.egg,setup.py,collective.*,
            plone.*" in your buildout configuration. Default is
            ``bootstrap.py,docs,*.egg``.
        
        **flake8-max-complexity**
            McCabe complexity threshold. Default is ``10``.
        
        **flake8-max-line-length**
            Set maximum allowed line length. Default is ``79``.
        
        **jshint**
            If set to True, jshint code analysis is run. Default is ``False``. Note
            that plone.recipe.codeanalysis requires jshint >= 1.0.
        
        **jshint-bin**
            JSHint executable. Default is ``jshint``. If you have JSHint installed on
            your system and in your path, there is nothing to do. To install JSHint in
            your buildout, use the following::
        
                [jshint]
                recipe = gp.recipe.node
                npms = jshint
                scripts = jshint
        
            set jshint-bin to '${buildout:directory}/bin/jshint'.
        
        **jshint-exclude**
            Allows you to specify directories which you don't want to be linted.
            Default is none. If you want JSHint to skip some files you can list them
            in a file named ``.jshintignore``. See `JSHint documentation`_ for more
            details.
        
        **csslint**
            If set to True, CSS Lint code analysis is run. Default is ``False``.
        
            CSS Lint options should be configured using a ``.csslintrc`` file. A
            typical ``.csslintrc`` file will look like this::
        
                --format=compact
                --quiet
                --ignore=adjoining-classes,floats,font-faces,font-sizes,ids,qualified-headings,unique-headings
                --exclude-list=foo/bar/static/third-party.css
        
            This typical configuration includes a list of CSS rules that will be
            ignored as they are `considered useless`_.
        
            See `CSS Lint documentation`_ for a detailed list and description of the
            rules.
        
        **csslint-bin**
            Set the path to a custom version of CSS Lint. Default is ``bin/csslint``.
        
            If you have CSS Lint installed in your system and path, set csslint-bin to
            'csslint'. To install CSS Lint in your buildout, use the following::
        
                [csslint]
                recipe = gp.recipe.node
                npms = csslint
                scripts = csslint
        
        **zptlint**
            If set to True, zptlint code analysis is run. Default is ``False``.
        
            Note that the buildout itself already depends on zptlint, so no extra
            configuration is needed.
        
        **zptlint-bin**
            Set the path to a custom version of zptlint. Default is ``bin/zptlint``.
        
        **deprecated-methods**
            If set to True, warnings about deprecated methods will be printed. Default
            is False.
        
        **utf8-header**
            If set to True, Python files without a utf-8 header (like
            ``# -*- coding: utf-8 -*-``) will cause a warning. Default is ``False``.
        
        **clean-lines**
            If set to True, **any file** containing trailing spaces or tabs anywhere
            on the lines will cause a warning. Default is ``False``.
        
        **prefer-single-quotes**
            If set to True, Python files will be scanned searching for strings quoted
            with double quote signs (``"``). Default is ``False``.
        
        **string-formatting**
            If set to True, Python files will be scanned searching for old-style
            string formatting (i.e. ``'%s' % var``). See `PEP 3101`_. Default is
            ``False``.
        
        **imports**
            If set to True, checks that imports in Python files follow `plone.api
            conventions`_. Default is ``False``.
        
        **debug-statements**
            If set to True, scan Python files looking for debug-like statements.
            Default is ``False``.
        
        
        Known Issues
        ============
        
        JSHint "ERROR: Unknown option --verbose"::
        
            JSHint                [ OK ]
            ERROR: Unknown option --verbose
        
        Upgrade JSHint to latest version (>= 1.0) to fix this issue, e.g.::
        
            $ sudo npm install -g jshint
        
        .. _`considered useless`: http://2002-2012.mattwilcox.net/archive/entry/id/1054/
        .. _`CSS Lint documentation`: https://github.com/stubbornella/csslint/wiki/Rules
        .. _`CSS Lint`: http://csslint.net/
        .. _`Flake8 documentation`: http://flake8.readthedocs.org/en/latest/warnings.html#error-codes
        .. _`flake8`: https://pypi.python.org/pypi/flake8
        .. _`JSHint documentation`: http://jshint.com/docs/
        .. _`JSHint`: http://www.jshint.com/
        .. _`PEP 3101`: http://www.python.org/dev/peps/pep-3101/
        .. _`plone.api conventions`: http://ploneapi.readthedocs.org/en/latest/contribute/conventions.html#about-imports
        .. _`zptlint`: https://pypi.python.org/pypi/zptlint
        
        Detailed Documentation
        **********************
        
        Example usage
        =============
        
        Minimal buildout::
        
            >>> write('buildout.cfg',
            ... """
            ... [buildout]
            ... parts = code-analysis
            ...
            ... [code-analysis]
            ... recipe = plone.recipe.codeanalysis
            ... directory = %(directory)s
            ... """ % {
            ...     'directory' : '${buildout:directory}/plone/recipe/codeanalysis',
            ... })
        
        Running the buildout gives us a 'code-analysis' script that runs the entire
        code analysis::
        
            >>> buildout_output_lower = system(buildout).lower()
            >>> '/sample-buildout/bin/code-analysis' in buildout_output_lower
            True
        
        It is also possible to run single code analysis scripts::
        
            >>> '/sample-buildout/bin/code-analysis-flake8' in buildout_output_lower
            True
            >>> '/sample-buildout/bin/code-analysis-jshint' in buildout_output_lower
            True
        
        Flake 8 and ZPTLint are installed by the buildout script, there is no need to
        install them on the system::
        
            >>> '/sample-buildout/bin/flake8' in buildout_output_lower
            True
        
            >>> '/sample-buildout/bin/zptlint' in buildout_output_lower
            True
        
        
        Deprecate method analysis script is installed::
        
            >>> '/sample-buildout/bin/code-analysis-deprecated-methods' in buildout_output_lower
            True
        
        The script to check if python files have an utf-8 encoding header is installed::
        
            >>> '/sample-buildout/bin/code-analysis-utf8-header' in buildout_output_lower
            True
        
        The script to warn about trailing spaces or tabs on files is installed::
        
            >>> '/sample-buildout/bin/code-analysis-clean-lines' in buildout_output_lower
            True
        
        Double quotes checker script is installed::
        
            >>> '/sample-buildout/bin/code-analysis-prefer-single-quotes' in buildout_output_lower
            True
        
        The script to check for old style string formatting is installed::
        
            >>> '/sample-buildout/bin/code-analysis-string-formatting' in buildout_output_lower
            True
        
        The script to check for plone.api style imports is installed::
        
            >>> '/sample-buildout/bin/code-analysis-imports' in buildout_output_lower
            True
        
        The script to check for debug-like statements in python code is installed::
        
            >>> '/sample-buildout/bin/code-analysis-debug-statements' in buildout_output_lower
            True
        
        By default a git pre-commit hook is installed. Though, this does not work if
        the current directory is not a git repository::
        
            >>> 'unable to create git pre-commit hook, this does not seem to be a git repository' in buildout_output_lower
            True
        
        If we have a git repository::
        
            >>> import subprocess
            >>> subprocess.call(['mkdir', '-p', '.git/hooks'])
            0
        
        And run buildout again::
        
            >>> buildout_output_lower = system(buildout).lower()
        
        Then the git pre-commit hook has been installed::
        
            >>> 'install git pre-commit hook.' in buildout_output_lower
            True
        
        Contributors
        ************
        
        - Timo Stollenwerk, Original Author
        - Gil Forcada
        - Héctor Velarde
        
        Change history
        **************
        
        1.0b2 (2013-09-11)
        ------------------
        
        - Deprecate 'csslint-quiet', 'csslint-ignore' and 'csslint-exclude-list'
          options; CSS Lint must be configured now using a '.csslintrc' file.
          'csslint-bin' option now defaults to ``bin/csslint``; documentation was
          updated (closes #20).
          [hvelarde]
        
        - Implement removal of pre-commit hook (fixes #21).
          [hvelarde]
        
        
        1.0b1 (2013-08-12)
        ------------------
        
        - Workaround over JSHint limitations to avoid displaying warning messages as
          errors (closes #13).
          [hvelarde]
        
        - Fix CSS Lint validation and implement new 'csslint-quiet' option.
          [hvelarde]
        
        - Fix package distribution.
          [hvelarde]
        
        
        1.0a1 (2013-08-04)
        ------------------
        
        - Initial release.
          [timo]
        
        Download
        ********
        
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
