1|logo| Pylama
2#############
3
4.. _description:
5
6Code audit tool for Python and JavaScript. Pylama wraps these tools:
7
8* pycodestyle_ (formerly pep8) © 2012-2013, Florent Xicluna;
9* pydocstyle_ (formerly pep257 by Vladimir Keleshev) © 2014, Amir Rachum;
10* PyFlakes_ © 2005-2013, Kevin Watters;
11* Mccabe_ © Ned Batchelder;
12* Pylint_ © 2013, Logilab (should be installed 'pylama_pylint' module);
13* Radon_ © Michele Lacchia
14* gjslint_ © The Closure Linter Authors (should be installed 'pylama_gjslint' module);
15* eradicate_ © Steven Myint;
16* Mypy_ © Jukka Lehtosalo and contributors;
17
18.. _badges:
19
20.. image:: http://img.shields.io/travis/klen/pylama.svg?style=flat-square
21    :target: http://travis-ci.org/klen/pylama
22    :alt: Build Status
23
24.. image:: http://img.shields.io/coveralls/klen/pylama.svg?style=flat-square
25    :target: https://coveralls.io/r/klen/pylama
26    :alt: Coverals
27
28.. image:: http://img.shields.io/pypi/v/pylama.svg?style=flat-square
29    :target: https://crate.io/packages/pylama
30    :alt: Version
31
32.. image:: http://img.shields.io/gratipay/klen.svg?style=flat-square
33    :target: https://www.gratipay.com/klen/
34    :alt: Donate
35
36
37.. _documentation:
38
39Docs are available at https://pylama.readthedocs.org/. Pull requests with documentation enhancements and/or fixes are awesome and most welcome.
40
41
42.. _contents:
43
44.. contents::
45
46.. _requirements:
47
48Requirements:
49=============
50
51- Python (2.7, 3.4, 3.5, 3.6, 3.7)
52- To use JavaScript checker (``gjslint``) you need to install ``python-gflags`` with ``pip install python-gflags``.
53- If your tests are failing on Win platform you are missing: ``curses`` - http://www.lfd.uci.edu/~gohlke/pythonlibs/
54  (The curses library supplies a terminal-independent screen-painting and keyboard-handling facility for text-based terminals)
55
56
57.. _installation:
58
59Installation:
60=============
61**Pylama** could be installed using pip: ::
62::
63
64    $ pip install pylama
65
66
67.. _quickstart:
68
69Quickstart
70==========
71
72**Pylama** is easy to use and really fun for checking code quality.
73Just run `pylama` and get common output from all pylama plugins (pycodestyle_, PyFlakes_ and etc)
74
75Recursive check the current directory. ::
76
77    $ pylama
78
79Recursive check a path. ::
80
81    $ pylama <path_to_directory_or_file>
82
83Ignore errors ::
84
85    $ pylama -i W,E501
86
87.. note:: You could choose a group erros `D`,`E1` and etc or special errors `C0312`
88
89Choose code checkers ::
90
91    $ pylama -l "pycodestyle,mccabe"
92
93Choose code checkers for JavaScript::
94
95    $ pylama --linters=gjslint --ignore=E:0010 <path_to_directory_or_file>
96
97.. _options:
98
99Set Pylama (checkers) options
100=============================
101
102Command line options
103--------------------
104
105::
106
107    $ pylama --help
108
109    usage: pylama [-h] [--verbose] [--version]
110                  [--format {pep8,pycodestyle,pylint,parsable}] [--select SELECT]
111                  [--sort SORT] [--linters LINTERS] [--ignore IGNORE]
112                  [--skip SKIP] [--report REPORT] [--hook] [--concurrent]
113                  [--options FILE] [--force] [--abspath]
114                  [paths [paths ...]]
115
116    Code audit tool for python.
117
118    positional arguments:
119      paths                 Paths to files or directories for code check.
120
121    optional arguments:
122      -h, --help            show this help message and exit
123      --verbose, -v         Verbose mode.
124      --version             show program's version number and exit
125      --format {pep8,pycodestyle,pylint,parsable}, -f {pep8,pycodestyle,pylint,parsable}
126                            Choose errors format (pycodestyle, pylint, parsable).
127      --select SELECT, -s SELECT
128                            Select errors and warnings. (comma-separated list)
129      --sort SORT           Sort result by error types. Ex. E,W,D
130      --linters LINTERS, -l LINTERS
131                            Select linters. (comma-separated). Choices are mccabe,
132                            pep257,pydocstyle,pep8,pycodestyle,pyflakes,pylint,iso
133                            rt.
134      --ignore IGNORE, -i IGNORE
135                            Ignore errors and warnings. (comma-separated)
136      --skip SKIP           Skip files by masks (comma-separated, Ex.
137                            */messages.py)
138      --report REPORT, -r REPORT
139                            Send report to file [REPORT]
140      --hook                Install Git (Mercurial) hook.
141      --concurrent, --async
142                            Enable async mode. Useful for checking a lot of files.
143                            Unsupported with pylint.
144      --options FILE, -o FILE
145                            Specify configuration file. Looks for pylama.ini,
146                            setup.cfg, tox.ini, or pytest.ini in the current
147                            directory (default: None).
148      --force, -F           Force code checking (if linter doesn't allow)
149      --abspath, -a         Use absolute paths in output.
150
151
152.. _modeline:
153
154File modelines
155--------------
156
157You can set options for **Pylama** inside a source file. Use
158pylama *modeline* for this.
159
160Format: ::
161
162    # pylama:{name1}={value1}:{name2}={value2}:...
163
164
165::
166
167     .. Somethere in code
168     # pylama:ignore=W:select=W301
169
170
171Disable code checking for current file: ::
172
173     .. Somethere in code
174     # pylama:skip=1
175
176Those options have a higher priority.
177
178.. _skiplines:
179
180Skip lines (noqa)
181-----------------
182
183Just add `# noqa` in end of line to ignore.
184
185::
186
187    def urgent_fuction():
188        unused_var = 'No errors here' # noqa
189
190
191.. _config:
192
193Configuration file
194------------------
195
196**Pylama** looks for a configuration file in the current directory.
197
198The program searches for the first matching ini-style configuration file in
199the directories of command line argument. Pylama looks for the configuration
200in this order: ::
201
202    pylama.ini
203    setup.cfg
204    tox.ini
205    pytest.ini
206
207The "--option" / "-o" argument can be used to specify a configuration file.
208
209Pylama searches for sections whose names start with `pylama`.
210
211The "pylama" section configures global options like `linters` and `skip`.
212
213::
214
215    [pylama]
216    format = pylint
217    skip = */.tox/*,*/.env/*
218    linters = pylint,mccabe
219    ignore = F0401,C0111,E731
220
221Set Code-checkers' options
222--------------------------
223
224You could set options for special code checker with pylama configurations.
225
226::
227
228    [pylama:pyflakes]
229    builtins = _
230
231    [pylama:pycodestyle]
232    max_line_length = 100
233
234    [pylama:pylint]
235    max_line_length = 100
236    disable = R
237
238See code-checkers' documentation for more info. Let's notice that dashes are
239replaced by underscores (e.g. Pylint's "max-line-length" becomes
240"max_line_length").
241
242
243Set options for file (group of files)
244-------------------------------------
245
246You could set options for special file (group of files)
247with sections:
248
249The options have a higher priority than in the `pylama` section.
250
251::
252
253    [pylama:*/pylama/main.py]
254    ignore = C901,R0914,W0212
255    select = R
256
257    [pylama:*/tests.py]
258    ignore = C0110
259
260    [pylama:*/setup.py]
261    skip = 1
262
263
264Pytest integration
265==================
266
267Pylama has Pytest_ support. The package automatically registers itself as a pytest
268plugin during installation. Pylama also supports `pytest_cache` plugin.
269
270Check files with pylama ::
271
272    pytest --pylama ...
273
274Recommended way to set pylama options when using pytest — configuration
275files (see below).
276
277
278Writing a linter
279================
280
281You can write a custom extension for Pylama.
282Custom linter should be a python module. Name should be like 'pylama_<name>'.
283
284In 'setup.py', 'pylama.linter' entry point should be defined. ::
285
286    setup(
287        # ...
288        entry_points={
289            'pylama.linter': ['lintername = pylama_lintername.main:Linter'],
290        }
291        # ...
292    )
293
294'Linter' should be instance of 'pylama.lint.Linter' class.
295Must implement two methods:
296
297'allow' takes a path and returns true if linter can check this file for errors.
298'run' takes a path and meta keywords params and returns a list of errors.
299
300Example:
301--------
302
303Just a virtual 'WOW' checker.
304
305setup.py: ::
306
307    setup(
308        name='pylama_wow',
309        install_requires=[ 'setuptools' ],
310        entry_points={
311            'pylama.linter': ['wow = pylama_wow.main:Linter'],
312        }
313        # ...
314    )
315
316pylama_wow.py: ::
317
318    from pylama.lint import Linter as BaseLinter
319
320    class Linter(BaseLinter):
321
322        def allow(self, path):
323            return 'wow' in path
324
325        def run(self, path, **meta):
326            with open(path) as f:
327                if 'wow' in f.read():
328                    return [{
329                        lnum: 0,
330                        col: 0,
331                        text: 'Wow has been finded.',
332                        type: 'WOW'
333                    }]
334
335
336Run pylama from python code
337---------------------------
338::
339
340    from pylama.main import check_path, parse_options
341
342    # Use and/or modify 0 or more of the options defined as keys in the variable my_redefined_options below.
343    # To use defaults for any option, remove that key completely.
344    my_redefined_options = {
345        'linters': ['pep257', 'pydocstyle', 'pycodestyle', 'pyflakes' ...],
346        'ignore': ['D203', 'D213', 'D406', 'D407', 'D413' ...],
347        'select': ['R1705' ...],
348        'sort': 'F,E,W,C,D,...',
349        'skip': '*__init__.py,*/test/*.py,...',
350        'async': True,
351        'force': True
352        ...
353    }
354    # relative path of the directory in which pylama should check
355    my_path = '...'
356
357    options = parse_options([my_path], **my_redefined_options)
358    errors = check_path(options, rootdir='.')
359
360
361.. _bagtracker:
362
363Bug tracker
364-----------
365
366If you have any suggestions, bug reports or annoyances please report them to the issue tracker at https://github.com/klen/pylama/issues
367
368
369.. _contributing:
370
371Contributing
372------------
373
374Development of `pylama` happens at GitHub: https://github.com/klen/pylama
375
376
377.. _contributors:
378
379Contributors
380^^^^^^^^^^^^
381
382See AUTHORS_.
383
384
385.. _license:
386
387License
388-------
389
390Licensed under a `BSD license`_.
391
392
393.. _links:
394
395.. _AUTHORS: https://github.com/klen/pylama/blob/develop/AUTHORS
396.. _BSD license: http://www.linfo.org/bsdlicense.html
397.. _Mccabe: http://nedbatchelder.com/blog/200803/python_code_complexity_microtool.html
398.. _pydocstyle: https://github.com/PyCQA/pydocstyle/
399.. _pycodestyle: https://github.com/PyCQA/pycodestyle
400.. _PyFlakes: https://github.com/pyflakes/pyflakes
401.. _Pylint: http://pylint.org
402.. _Pytest: http://pytest.org
403.. _gjslint: https://developers.google.com/closure/utilities
404.. _klen: http://klen.github.io/
405.. _eradicate: https://github.com/myint/eradicate
406.. _Mypy: https://github.com/python/mypy
407
408.. |logo| image:: https://raw.github.com/klen/pylama/develop/docs/_static/logo.png
409                  :width: 100
410.. _Radon: https://github.com/rubik/radon
411
412