2
2
3
3
Style Guide Enforcement
4
4
=======================
5
- The following sections describe the use of `Flake8 `_ for `PEP8 `_ style
5
+ This topic describes the use of `Flake8 `_ for `PEP8 `_ style
6
6
enforcement and the minimum standards expected. PyAnsys libraries
7
7
are expected to be consistent with these guidelines.
8
8
@@ -27,7 +27,7 @@ Configuring Flake8
27
27
Flake8 supports configuring a specific set of style rules to
28
28
enforce. This configuration can be stored in your library in a
29
29
``setup.cfg ``, ``tox.ini ``, or ``.flake8 `` file. PyAnsys libraries
30
- store the flake8 configuration in a ``.flake8 `` file at the root of the
30
+ store the Flake8 configuration in a ``.flake8 `` file at the root of the
31
31
repository.
32
32
33
33
Here is an example of a ``.flake8 `` configuration file from a PyAnsys
@@ -44,48 +44,50 @@ library:
44
44
statistics = True
45
45
46
46
Flake8 has many options that can be set within the configuration file.
47
- A list of possible options can be found `here <https://flake8.pycqa.org/en/latest/user/options.html >`__.
47
+ For a list and descriptions, see this `Flake8 documentation topic
48
+ <https://flake8.pycqa.org/en/latest/user/options.html> `__.
48
49
49
- The above configuration defines the following options:
50
+ The example configuration defines the following options:
50
51
51
52
- ``exclude ``
52
- This denotes subdirectories and ``doc/_build ``, along with all
53
+ Denotes subdirectories and ``doc/_build ``, along with all
53
54
``__init__.py `` files to be excluded from the check.
54
55
55
56
- ``select ``
56
- This is a sequence of error codes that flake8 will report errors
57
+ Sequence of error codes that Flake8 will report errors
57
58
for. The set in the above configuration is a basic set of errors to
58
59
check for and is not an exhaustive list.
59
60
60
- A full list of error codes and their descriptions can be found `here <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html >`__.
61
+ For a full list of error codes and their descriptions, see this `Flake8
62
+ documentation topic <https://flake8.pycqa.org/en/3.9.2/user/error-codes.html> `__.
61
63
62
64
- ``count ``
63
- The total number of errors is printed at the end of the check.
65
+ Total number of errors to print at the end of the check.
64
66
65
67
- ``max-complexity ``
66
- This sets the maximum allowed McCabe complexity value for a block of code.
68
+ Sets the maximum allowed McCabe complexity value for a block of code.
67
69
The value of 10 was chosen because it is a common default.
68
70
69
71
- ``max-line-length ``
70
- This denotes the maximum line length for any one line of code.
72
+ Denotes the maximum line length for any one line of code.
71
73
The `PEP8 `_ standard advises a maximum line length of 79. Because
72
74
this is a bit limiting in some cases, the maximum line length
73
75
recommended for a PyAnsys library is 100.
74
76
75
77
- ``statistics ``
76
- This enables the number of occurrences of each error or warning code
78
+ Number of occurrences of each error or warning code
77
79
to be printed as a report at the end of the check.
78
80
79
81
80
82
Running Flake8
81
83
--------------
82
- First, to install flake8 , run:
84
+ First, to install Flake8 , run:
83
85
84
86
.. code ::
85
87
86
88
python -m pip install flake8
87
89
88
- Then, flake8 can be run from inside your project directory by executing:
90
+ Then, you can run Flake8 from inside your project directory by executing:
89
91
90
92
.. code ::
91
93
@@ -95,7 +97,7 @@ This uses the configuration defined in the ``.flake8`` file to
95
97
run the style checks on the appropriate files within the project and
96
98
report any errors.
97
99
98
- In PyAnsys libraries, flake8 is run as part of the CI/CD for code style.
100
+ In PyAnsys libraries, Flake8 is run as part of the CI/CD for code style.
99
101
This action is run as a required check on pull requests, preventing
100
102
code in violation of style rules from being merged into the code
101
103
base.
@@ -110,12 +112,12 @@ the formatting tool `black`_.
110
112
111
113
On completing a code change, and before committing, `black `_ can be
112
114
run to reformat the code, following the PEP8 guidelines enforced through
113
- flake8 . This will limit any manual code changes needed to address style
115
+ Flake8 . This will limit any manual code changes needed to address style
114
116
rules.
115
117
116
118
.. _black : https://black.readthedocs.io/en/stable/
117
119
118
- Optionally, it is possible to automate the use of `` black `` . This can be
120
+ Optionally, it is possible to automate the use of `black `_ . This can be
119
121
done with the tool `pre-commit `_. Setting up a `pre-commit hook
120
122
to run black <https://black.readthedocs.io/en/stable/integrations/source_version_control.html> `_
121
123
will automatically format the code before committing. This simple way of
@@ -128,7 +130,7 @@ PEP8 guidelines requires minimal manual effort.
128
130
Minimum Standards
129
131
~~~~~~~~~~~~~~~~~
130
132
The following section describes the minimum set of code style standards
131
- expected in an PyAnsys library.
133
+ expected in a PyAnsys library.
132
134
133
135
* `W191 `_ - **Indentation contains tabs. **
134
136
@@ -193,11 +195,11 @@ expected in an PyAnsys library.
193
195
* `E501 `_ - **Line too long. **
194
196
195
197
All code lines should not exceed 100 characters. The
196
- `PEP8 line length <https://www.python.org/dev/peps/pep-0008/#maximum-line-length >`_
197
- guidelines suggest a maximum line length of 79. Following this limit
198
+ `PEP8 line length guideline <https://www.python.org/dev/peps/pep-0008/#maximum-line-length >`_
199
+ suggests a maximum line length of 79. Following this limit
198
200
is not as necessary today due to modern screen sizes. The suggested maximum
199
201
length of 100 can be easier to accommodate and can still support
200
- viewing files side-by- side in code editors.
202
+ viewing files side by side in code editors.
201
203
202
204
* `F401 `_ - **Module imported but unused. **
203
205
0 commit comments