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