Metadata-Version: 1.1
Name: plone.recipe.codeanalysis
Version: 1.0
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
        
        .. image:: https://coveralls.io/repos/plone/plone.recipe.codeanalysis/badge.png?branch=master
            :target: https://coveralls.io/r/plone/plone.recipe.codeanalysis
        
        .. image:: https://pypip.in/d/plone.recipe.codeanalysis/badge.png
                :target: https://crate.io/packages/plone.recipe.codeanalysis
        
        .. image:: https://pypip.in/v/plone.recipe.codeanalysis/badge.png
                :target: https://crate.io/packages/plone.recipe.codeanalysis
        
        
        Introduction
        ============
        
        plone.recipe.codeanalysis provides static code analysis for Buildout-based
        Python projects, including `flake8`_, `JSHint`_, `CSS Lint`_, 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.
        
        plone.recipe.codeanalysis comes with a Jenkins integration, that allows to use
        the same code analysis settings on your local machine as well as on Jenkins.
        
        
        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.
        
        
        Jenkins Installation
        ====================
        
        plone.recipe.codeanalysis provides a Jenkins setting that allows to run it on a Jenkins CI server and to process and integrate the output via the
        `Jenkins Violations plugin`_.
        
        Usually you don't want the recipe to create Jenkins output files on your
        local machine. Therefore it makes sense to enable the Jenkins output only
        on the CI machine. To do so, just create a jenkins.cfg that extends and
        overrides the default buildout file (that includes the other settings)::
        
            [buildout]
            parts += code-analysis
        
            [code-analysis]
            recipe = plone.recipe.codeanalysis
            jenkins = True
        
        The Jenkins job itself should run "bin/code-analysis"::
        
            python bootstrap.py -c jenkins.cfg
            bin/buildout -c jenkins.cfg
            bin/jenkins-test --all
            bin/code-analysis
        
        The `Jenkins Violations plugin`_ needs to be configured to read the output
        files generated by this configuration.
        
        pep8 (to read the flake8 output)::
        
            **/parts/code-analysis/flake8.log
        
        csslint::
        
            **/parts/code-analysis/csslint.xml
        
        jslint (to read the jshint output::
        
            **/parts/code-analysis/jshint.xml
        
        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. Default is ``True``.
        
        **jenkins**
            If set to True, the flake8, jshint and csslint code analysis steps will
            write output files that can be processed by the
            `Jenkins Violations plugin`_. Default is ``False``.
        
        **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.
        
        **jscs**
            If set to True, jscs code analysis is run. Default is ``False``.
        
            JavaScript Code Style options should be configured using a ``.jscs.json``
            file. You should align your javascript code to the next generation of
            Plone's javascript framework Mockup_ and take it's ``.jscs.json`` file
            which is available here:
            https://github.com/plone/mockup/blob/master/.jscs.json
        
            All configuration options are documented on the `jscs website`_.
        
        **jscs-bin**
            Set the path to a custom version of JSCS, e.g.
            "/usr/local/bin/jscs".
        
            If you have Javascript Code Style Checker installed in your system and
            path, you have nothing to do. To install with Buildout, add the following
            section to your buildout and set jscs-bin to
            ``{buildout:bin-directory}/jscs``::
        
                [jscs]
                recipe = gp.recipe.node
                npms = jscs
                scripts = jscs
        
        **jscs-exclude**
            Allows you to specify directories and/or files which you don't want to be
            checked. Default is none. Note that these directories have to be given in
            absolute paths, use ``${buildout:directory}/foo/bar/static/js-3rd-party``
            for example.
        
        **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, e.g.
            "/usr/local/bin/csslint".
        
            If you have CSS Lint installed in your system and path, you have nothing
            to do. To install CSS Lint with Buildout, add the following section to
            your buildout and set csslint-bin to
            ``{buildout:bin-directory}/csslint``::
        
                [csslint]
                recipe = gp.recipe.node
                npms = csslint
                scripts = csslint
        
        **deprecated-aliases**
            For historical reasons, some of the unittest.TestCase methods had one or
            more aliases that are deprecated on Python 2.7. If this option is set to
            True, warnings about deprecated aliases will be printed. Default is
            ``False``. See `Unit testing framework documentation`_ for more
            information.
        
        **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``.
        
        **clean-lines-exclude**
            Allows you to specify directories and/or files which you don't want to be
            checked. Default is none. Note that these directories have to be given in
            absolute paths, use ``${buildout:directory}/foo/bar/static/js-3rd-party``
            for example.
        
        **prefer-single-quotes**
            If set to True, Python files will be scanned searching for strings quoted
            with double quote signs (``"``). Default is ``False``.
        
        **pep3101**
            If set to True, Python files will be scanned in search of existing '%'
            string formatting operators. Default is ``False``. See `PEP 3101 (Advanced
            String Formatting)`_ for more information.
        
        **imports**
            If set to True, checks that imports in Python files follow `plone.api
            conventions`_. This also includes checking for alphabetically sorted
            import statements. Default is ``False``.
        
        **debug-statements**
            If set to True, scan Python files looking for debug-like statements.
            Default is ``False``.
        
        **return-status-codes**
            If set to True, the ``bin/code-analysis`` script returns an error code
            that Continuous Integration servers (like Travis CI) can use to fail or
            pass a job, based on the code analyis output. Note that Jenkins usually
            does not need this option (this is better handled by the Jenkins
            Violations plugin). Note that this option does not have any effect on the
            other code analysis scripts. Default is ``False``.
        
        i18ndude and zptlint support
        ----------------------------
        
        To reduce the number of Zope/Plone direct dependencies, plone.recipe.codeanalysis no longer depends on `i18ndude`_ nor `zptlint`_;
        in order to use the following options you have to install them on your
        system:
        
        **find-untranslated**
            If set to True, scan Zope templates to find untranslated strings.
            Default is ``False``.
            To use this you will need to set the ``i18ndude-bin`` option.
        
        **i18ndude-bin**
            Set the path to a custom version of `i18ndude`_.
            Default is none.
        
        **zptlint**
            If set to True, zptlint code analysis is run.
            Default is ``False``.
            To use this you will need to set the ``zptlint-bin`` option.
        
        **zptlint-bin**
            Set the path to a custom version of `zptlint`_.
            Default is none.
        
        
        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
        
        
        JSHint "ERROR: Unknown option --exclude"::
        
            JSHint                [ OK ]
            ERROR: Unknown option --exclude
        
        Upgrade JSHint to latest version (>= 2.1.6) 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
        .. _`Jenkins Violations plugin`: https://wiki.jenkins-ci.org/display/JENKINS/Violations
        .. _`flake8`: https://pypi.python.org/pypi/flake8
        .. _`JSHint documentation`: http://jshint.com/docs/
        .. _`JSHint`: http://www.jshint.com/
        .. _`PEP 3101 (Advanced String Formatting)`: 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
        .. _`i18ndude`: https://pypi.python.org/pypi/i18ndude
        .. _`Unit testing framework documentation`: http://docs.python.org/2/library/unittest.html#deprecated-aliases
        .. _`Mockup`: https://github.com/plone/mockup
        .. _`jscs website`: https://www.npmjs.org/package/jscs
        
        
        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 is installed by the buildout script, there is no need to install it on
        the system::
        
            >>> '/sample-buildout/bin/flake8' in buildout_output_lower
            True
        
        Deprecated aliases analysis script is installed::
        
            >>> '/sample-buildout/bin/code-analysis-deprecated-aliases' 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-pep3101' 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
        
        The script to check for untranslated strings in templates is installed::
        
            >>> '/sample-buildout/bin/code-analysis-find-untranslated' 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
        - Ramiro Batista da Luz
        - Daniel Widerin
        
        
        Change history
        ==============
        
        1.0 (2014-12-04)
        ----------------
        
        - Nothing changed since 1.0rc1.
        
        
        1.0rc1 (2014-06-18)
        -------------------
        
        - Return a string to avoid TypeError when no file was checked with ``jscs``.
          [saily]
        
        - Check import sorting in ``code_analysis_imports`` and add tests for
          clean and sorted imports.
          [saily]
        
        - Refactor ``code_analysis_clean_lines`` to use a new method to retrieve
          files and avoid too complex violation.
          [saily]
        
        
        1.0b8 (2014-06-05)
        ------------------
        
        - Add ``clean-lines-exclude`` support and updated README.
          [saily]
        
        - Added tests for clean-lines checks.
          [saily]
        
        - Use indices for format() to support Python 2.6. This fixes #77.
          [timo]
        
        
        1.0b7 (2014-05-04)
        ------------------
        
        - Add Javascript Code Style Checker ``jscs`` support.
          [saily]
        
        - Remove hard dependency on i18ndude and zptlint; this will reduce the number
          of Zope/Plone direct dependencies to make life happier to people using
          Pyramid and other web Python-based development frameworks (closes `#53`_).
          [hvelarde]
        
        - Do not print out jshint and csslint output for Jenkins. Those files can
          become quite large.
          [timo]
        
        
        1.0b6 (2013-10-16)
        ------------------
        
        - Remove progress bullets from flake8 check.
          [timo]
        
        - Improve the way to handle an exception if the command used in popen does
          not exist.
          [flohcim]
        
        
        1.0b5 (2013-10-08)
        ------------------
        
        - Fix code analysis method by making it call each check only if the option
          is activated.
          [flohcim]
        
        - Keep backward compatibility with 'string-formatting' option.
          [hvelarde]
        
        - Rename 'deprecated-alias' to 'deprecated-aliases' and keep backward
          compatibility.
          [hvelarde]
        
        
        1.0b4 (2013-10-06)
        ------------------
        
        - Implement Jenkins option on CSS Lint and JSHint.
          [hvelarde, ramiroluz]
        
        - Rename 'deprecated-methods' to 'deprecated-alias'.
          [gforcada]
        
        - Rename 'string-formatting' option to 'pep3101' to keep consistency.
          [hvelarde]
        
        - Remove unused CSSLINT_IGNORE remainings.
          [timo]
        
        - Simplify code analysis method and make it more readable.
          [timo]
        
        
        1.0b3 (2013-09-12)
        ------------------
        
        - Add return-status-codes option that allows to fail a CI-build on Travis.
          [timo]
        
        - Make system wide installed csslint the default value for
          the csslint-bin option.
          [timo]
        
        
        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]
        
        .. _`#53`: https://github.com/plone/plone.recipe.codeanalysis/issues/53
        
        
        Download
        ********
        
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
