Skip to content

Commit d24d5d9

Browse files
Pierre-SassoulasDanielNoord
Pierre-Sassoulas
and
DanielNoord
authored
Burst run's documentation between user guide and dev guide,(#6658)
* [doc] Merge run help from the FAQ to the user guide doc * Rename run to API for dev doc Co-authored-by: Daniël van Noord <[email protected]>
1 parent d27c622 commit d24d5d9

File tree

6 files changed

+141
-158
lines changed

6 files changed

+141
-158
lines changed

‎doc/development_guide/api/epylint.rst

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
=======
2+
epylint
3+
=======
4+
5+
To silently run epylint on a ``module_name.py`` module, and get its standard output and error:
6+
7+
.. sourcecode:: python
8+
9+
from pylint import epylint as lint
10+
11+
(pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', return_std=True)
12+
13+
It is also possible to include additional Pylint options in the first argument to ``py_run``:
14+
15+
.. sourcecode:: python
16+
17+
from pylint import epylint as lint
18+
19+
(pylint_stdout, pylint_stderr) = lint.py_run('module_name.py --disable C0114', return_std=True)
20+
21+
The options ``--msg-template="{path}:{line}: {category} ({msg_id}, {symbol}, {obj}) {msg}"`` and
22+
``--reports=n`` are set implicitly inside the ``epylint`` module.

‎doc/development_guide/api/index.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
###
2+
API
3+
###
4+
5+
You can call ``Pylint``, ``epylint``, ``symilar`` and ``pyreverse`` from another
6+
Python program thanks to their APIs:
7+
8+
.. sourcecode:: python
9+
10+
from pylint import run_pylint, run_epylint, run_pyreverse, run_symilar
11+
12+
run_pylint("--disable=C", "myfile.py")
13+
run_epylint(...)
14+
run_pyreverse(...)
15+
run_symilar(...)
16+
17+
18+
.. toctree::
19+
:maxdepth: 1
20+
:hidden:
21+
22+
pylint
23+
epylint

‎doc/development_guide/api/pylint.rst

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
=======
2+
Pylint
3+
=======
4+
5+
As you would launch the command line
6+
------------------------------------
7+
8+
You can use the ``run_pylint`` function, which is the same function
9+
called by the command line (using ``sys.argv``). You can supply
10+
arguments yourself:
11+
12+
.. sourcecode:: python
13+
14+
from pylint import run_pylint
15+
16+
run_pylint(argv=["--disable=line-too-long", "myfile.py"])
17+
18+
19+
Recover the result in a stream
20+
------------------------------
21+
22+
You can also use ``pylint.lint.Run`` directly if you want to do something that
23+
can't be done using only pylint's command line options. Here's the basic example:
24+
25+
.. sourcecode:: python
26+
27+
from pylint.lint import Run
28+
29+
Run(argv=["--disable=line-too-long", "myfile.py"])
30+
31+
With ``Run`` it is possible to invoke pylint programmatically with a
32+
reporter initialized with a custom stream:
33+
34+
.. sourcecode:: python
35+
36+
from io import StringIO
37+
38+
from pylint.lint import Run
39+
from pylint.reporters.text import TextReporter
40+
41+
pylint_output = StringIO() # Custom open stream
42+
reporter = TextReporter(pylint_output)
43+
Run(["test_file.py"], reporter=reporter, do_exit=False)
44+
print(pylint_output.getvalue()) # Retrieve and print the text report
45+
46+
The reporter can accept any stream object as as parameter. In this example,
47+
the stream outputs to a file:
48+
49+
.. sourcecode:: python
50+
51+
from pylint.lint import Run
52+
from pylint.reporters.text import TextReporter
53+
54+
with open("report.out", "w") as f:
55+
reporter = TextReporter(f)
56+
Run(["test_file.py"], reporter=reporter, do_exit=False)
57+
58+
This would be useful to capture pylint output in an open stream which
59+
can be passed onto another program.
60+
61+
If your program expects that the files being linted might be edited
62+
between runs, you will need to clear pylint's inference cache:
63+
64+
.. sourcecode:: python
65+
66+
from pylint.lint import pylinter
67+
pylinter.MANAGER.clear_cache()

‎doc/development_guide/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ Development
88

99
contribute
1010
testing
11+
api/index
1112
profiling

‎doc/faq.rst

+2-52
Original file line numberDiff line numberDiff line change
@@ -24,35 +24,7 @@ Pylint uses git. To get the latest version of Pylint from the repository, simply
2424
3. Running Pylint
2525
=================
2626

27-
3.1 Can I give pylint a file as an argument instead of a module?
28-
----------------------------------------------------------------
29-
30-
Pylint expects the name of a package or module as its argument. As a
31-
convenience, you can give it a file name if it's possible to guess a module name from
32-
the file's path using the python path. Some examples:
33-
34-
"pylint mymodule.py" should always work since the current working
35-
directory is automatically added on top of the python path
36-
37-
"pylint directory/mymodule.py" will work if "directory" is a python
38-
package (i.e. has an __init__.py file), an implicit namespace package
39-
or if "directory" is in the python path.
40-
41-
"pylint /whatever/directory/mymodule.py" will work if either:
42-
43-
- "/whatever/directory" is in the python path
44-
45-
- your cwd is "/whatever/directory"
46-
47-
- "directory" is a python package and "/whatever" is in the python
48-
path
49-
50-
- "directory" is an implicit namespace package and is in the python path.
51-
52-
- "directory" is a python package and your cwd is "/whatever" and so
53-
on...
54-
55-
3.2 Where is the persistent data stored to compare between successive runs?
27+
3.1 Where is the persistent data stored to compare between successive runs?
5628
---------------------------------------------------------------------------
5729

5830
Analysis data are stored as a pickle file in a directory which is
@@ -71,7 +43,7 @@ localized using the following rules:
7143
* ".pylint.d" directory in the current directory
7244

7345

74-
3.3 How do I find the option name corresponding to a specific command line option?
46+
3.2 How do I find the option name corresponding to a specific command line option?
7547
----------------------------------------------------------------------------------
7648

7749
You can generate a sample configuration file with ``--generate-toml-config``.
@@ -82,28 +54,6 @@ For example::
8254

8355
pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-toml-config
8456

85-
3.5 I need to run pylint over all modules and packages in my project directory.
86-
-------------------------------------------------------------------------------
87-
88-
By default the ``pylint`` command only accepts a list of python modules and packages. Using a
89-
directory which is not a package results in an error::
90-
91-
pylint mydir
92-
************* Module mydir
93-
mydir/__init__.py:1:0: F0010: error while code parsing: Unable to load file mydir/__init__.py:
94-
[Errno 2] No such file or directory: 'mydir/__init__.py' (parse-error)
95-
96-
To execute pylint over all modules and packages under the directory, the ``--recursive=y`` option must
97-
be provided. This option makes ``pylint`` attempt to discover all modules (files ending with ``.py`` extension)
98-
and all packages (all directories containing a ``__init__.py`` file).
99-
Those modules and packages are then analyzed::
100-
101-
pylint --recursive=y mydir
102-
103-
When ``--recursive=y`` option is used, modules and packages are also accepted as parameters::
104-
105-
pylint --recursive=y mydir mymodule mypackage
106-
10757
4. Message Control
10858
==================
10959

‎doc/user_guide/run.rst

+26-106
Original file line numberDiff line numberDiff line change
@@ -2,126 +2,46 @@
22
Running Pylint
33
================
44

5-
From the command line
6-
---------------------
5+
On module packages or directories
6+
---------------------------------
77

88
Pylint is meant to be called from the command line. The usage is ::
99

1010
pylint [options] modules_or_packages
1111

12-
You should give Pylint the name of a python package or module, or some number
13-
of packages or modules. Pylint
14-
``will not import`` this package or module, though uses Python internals
15-
to locate them and as such is subject to the same rules and configuration.
16-
You should pay attention to your ``PYTHONPATH``, since it is a common error
17-
to analyze an installed version of a module instead of the
18-
development version.
19-
20-
It is also possible to analyze Python files, with a few
21-
restrictions. The thing to keep in mind is that Pylint will try to
22-
convert the file name to a module name, and only be able to process
23-
the file if it succeeds. ::
24-
25-
pylint mymodule.py
26-
27-
should always work since the current working
28-
directory is automatically added on top of the python path ::
29-
30-
pylint directory/mymodule.py
31-
32-
will work if ``directory`` is a python package (i.e. has an __init__.py
33-
file or it is an implicit namespace package) or if "directory" is in the
34-
python path.
35-
36-
By default, pylint will exit with an error when one of the arguments is a directory which is not
37-
a python package. In order to run pylint over all modules and packages within the provided
38-
subtree of a directory, the ``--recursive=y`` option must be provided.
39-
40-
For more details on this see the :ref:`faq`.
41-
42-
From another python program
43-
---------------------------
44-
45-
It is also possible to call Pylint from another Python program,
46-
thanks to the ``Run()`` function in the ``pylint.lint`` module
47-
(assuming Pylint options are stored in a list of strings ``pylint_options``) as:
48-
49-
.. sourcecode:: python
50-
51-
import pylint.lint
52-
pylint_opts = ['--disable=line-too-long', 'myfile.py']
53-
pylint.lint.Run(pylint_opts)
54-
55-
Another option would be to use the ``run_pylint`` function, which is the same function
56-
called by the command line. You can either patch ``sys.argv`` or supply arguments yourself:
57-
58-
.. sourcecode:: python
59-
60-
import pylint
61-
62-
sys.argv = ["pylint", "your_file"]
63-
pylint.run_pylint()
64-
# Or:
65-
pylint.run_pylint(argv=["your_file"])
12+
By default the ``pylint`` command only accepts a list of python modules and packages. Using a
13+
directory which is not a package results in an error::
6614

67-
To silently run Pylint on a ``module_name.py`` module,
68-
and get its standard output and error:
15+
pylint mydir
16+
************* Module mydir
17+
mydir/__init__.py:1:0: F0010: error while code parsing: Unable to load file mydir/__init__.py:
18+
[Errno 2] No such file or directory: 'mydir/__init__.py' (parse-error)
6919

70-
.. sourcecode:: python
20+
When ``--recursive=y`` option is used, modules and packages are also accepted as parameters::
7121

72-
from pylint import epylint as lint
22+
pylint --recursive=y mydir mymodule mypackage
7323

74-
(pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', return_std=True)
24+
This option makes ``pylint`` attempt to discover all modules (files ending with ``.py`` extension)
25+
and all packages (all directories containing a ``__init__.py`` file).
7526

76-
It is also possible to include additional Pylint options in the first argument to ``py_run``:
77-
78-
.. sourcecode:: python
79-
80-
from pylint import epylint as lint
81-
82-
(pylint_stdout, pylint_stderr) = lint.py_run('module_name.py --disable C0114', return_std=True)
83-
84-
The options ``--msg-template="{path}:{line}: {category} ({msg_id}, {symbol}, {obj}) {msg}"`` and
85-
``--reports=n`` are set implicitly inside the ``epylint`` module.
86-
87-
Finally, it is possible to invoke pylint programmatically with a
88-
reporter initialized with a custom stream:
89-
90-
.. sourcecode:: python
91-
92-
from io import StringIO
93-
94-
from pylint.lint import Run
95-
from pylint.reporters.text import TextReporter
96-
97-
pylint_output = StringIO() # Custom open stream
98-
reporter = TextReporter(pylint_output)
99-
Run(["test_file.py"], reporter=reporter, do_exit=False)
100-
print(pylint_output.getvalue()) # Retrieve and print the text report
101-
102-
The reporter can accept any stream object as as parameter. In this example,
103-
the stream outputs to a file:
104-
105-
.. sourcecode:: python
106-
107-
from pylint.lint import Run
108-
from pylint.reporters.text import TextReporter
109-
110-
with open("report.out", "w") as f:
111-
reporter = TextReporter(f)
112-
Run(["test_file.py"], reporter=reporter, do_exit=False)
113-
114-
This would be useful to capture pylint output in an open stream which
115-
can be passed onto another program.
27+
Pylint **will not import** this package or module, though uses Python internals
28+
to locate them and as such is subject to the same rules and configuration.
29+
You should pay attention to your ``PYTHONPATH``, since it is a common error
30+
to analyze an installed version of a module instead of the development version.
11631

117-
If your program expects that the files being linted might be edited
118-
between runs, you will need to clear pylint's inference cache:
32+
On files
33+
--------
11934

120-
.. sourcecode:: python
35+
It is also possible to analyze Python files, with a few restrictions. As a convenience,
36+
you can give it a file name if it's possible to guess a module name from the file's
37+
path using the python path. Some examples:
12138

122-
from pylint.lint import pylinter
123-
pylinter.MANAGER.clear_cache()
39+
``pylint mymodule.py`` should always work since the current working
40+
directory is automatically added on top of the python path
12441

42+
``pylint directory/mymodule.py`` will work if: ``directory`` is a python
43+
package (i.e. has an ``__init__.py`` file), an implicit namespace package
44+
or if ``directory`` is in the python path.
12545

12646
Command line options
12747
--------------------

0 commit comments

Comments
 (0)