Skip to content

Commit 290c76e

Browse files
nmariznmariz
committed
WL#15035: Enforce PEP 7 and PEP 8 coding style
This worklog enforces the coding style guide described in PEP 7 and PEP 8. Besides the code refactoring, it adds tooling configuration to aid the writing of new code. All files can be formatted using the black auto-formatter and isort. These tools can be run automatically by pre-commit if it's configured.
1 parent 26bb113 commit 290c76e

File tree

146 files changed

+21167
-15056
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

146 files changed

+21167
-15056
lines changed

‎.clang-format

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Copyright (c) 2022, Oracle and/or its affiliates.
2+
#
3+
# This program is free software; you can redistribute it and/or modify
4+
# it under the terms of the GNU General Public License, version 2.0, as
5+
# published by the Free Software Foundation.
6+
#
7+
# This program is also distributed with certain software (including
8+
# but not limited to OpenSSL) that is licensed under separate terms,
9+
# as designated in a particular file or component or in included license
10+
# documentation. The authors of MySQL hereby grant you an
11+
# additional permission to link the program and your derivative works
12+
# with the separately licensed software that they have included with
13+
# MySQL.
14+
#
15+
# Without limiting anything contained in the foregoing, this file,
16+
# which is part of MySQL Connector/Python, is also subject to the
17+
# Universal FOSS Exception, version 1.0, a copy of which can be found at
18+
# http://oss.oracle.com/licenses/universal-foss-exception.
19+
#
20+
# This program is distributed in the hope that it will be useful, but
21+
# WITHOUT ANY WARRANTY; without even the implied warranty of
22+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
23+
# See the GNU General Public License, version 2.0, for more details.
24+
#
25+
# You should have received a copy of the GNU General Public License
26+
# along with this program; if not, write to the Free Software Foundation, Inc.,
27+
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
28+
29+
# A clang-format style that approximates Python's PEP 7
30+
BasedOnStyle: Google
31+
AlwaysBreakAfterReturnType: All
32+
AllowShortIfStatementsOnASingleLine: false
33+
AlignAfterOpenBracket: Align
34+
BreakBeforeBraces: Stroustrup
35+
ColumnLimit: 95
36+
DerivePointerAlignment: false
37+
IndentWidth: 4
38+
Language: Cpp
39+
PointerAlignment: Right
40+
ReflowComments: true
41+
SpaceBeforeParens: ControlStatements
42+
SpacesInParentheses: false
43+
TabWidth: 4
44+
UseTab: Never
45+
SortIncludes: false

‎.coveragerc

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎.pre-commit-config.yaml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Copyright (c) 2022, Oracle and/or its affiliates.
2+
#
3+
# This program is free software; you can redistribute it and/or modify
4+
# it under the terms of the GNU General Public License, version 2.0, as
5+
# published by the Free Software Foundation.
6+
#
7+
# This program is also distributed with certain software (including
8+
# but not limited to OpenSSL) that is licensed under separate terms,
9+
# as designated in a particular file or component or in included license
10+
# documentation. The authors of MySQL hereby grant you an
11+
# additional permission to link the program and your derivative works
12+
# with the separately licensed software that they have included with
13+
# MySQL.
14+
#
15+
# Without limiting anything contained in the foregoing, this file,
16+
# which is part of MySQL Connector/Python, is also subject to the
17+
# Universal FOSS Exception, version 1.0, a copy of which can be found at
18+
# http://oss.oracle.com/licenses/universal-foss-exception.
19+
#
20+
# This program is distributed in the hope that it will be useful, but
21+
# WITHOUT ANY WARRANTY; without even the implied warranty of
22+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
23+
# See the GNU General Public License, version 2.0, for more details.
24+
#
25+
# You should have received a copy of the GNU General Public License
26+
# along with this program; if not, write to the Free Software Foundation, Inc.,
27+
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
28+
29+
repos:
30+
- repo: https://github.com/psf/black
31+
rev: 22.1.0
32+
hooks:
33+
- id: black
34+
- repo: https://github.com/pycqa/isort
35+
rev: 5.10.1
36+
hooks:
37+
- id: isort

‎CHANGES.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Full release notes:
1111
v8.0.30
1212
=======
1313

14+
- WL#15035: Enforce PEP 7 and PEP 8 coding style
1415
- WL#14822: Refactor the authentication plugin mechanism
1516

1617
v8.0.29

‎CONTRIBUTING.rst

Lines changed: 68 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,31 +30,91 @@ Contributing to this project is easy. You just need to follow these steps.
3030

3131
Thanks again for your wish to contribute to MySQL. We truly believe in the principles of open source development and appreciate any contributions to our projects.
3232

33-
Running Tests
34-
-------------
33+
Setting Up a Development Environment
34+
------------------------------------
3535

36-
Any code you contribute needs to pass our test suite. Please follow these steps to run our tests and validate your contributed code.
36+
The following tips provide all the technical directions you should follow when writing code and before actually submitting your contribution.
3737

38-
1) Make sure you have the necessary `prerequisites <https://dev.mysql.com/doc/dev/connector-python/8.0/installation.html#prerequisites>`_ for building the project and `Pylint <https://www.pylint.org/>`_ for code analysis and style
38+
1) Make sure you have the necessary `prerequisites <https://dev.mysql.com/doc/dev/connector-python/8.0/installation.html#prerequisites>`_ for building the project and `Pylint <https://www.pylint.org/>`_ for static code analysis
3939

4040
2) Clone MySQL Connector/Python
4141

4242
.. code-block:: bash
4343
4444
shell> git clone https://github.com/mysql/mysql-connector-python.git
4545
46-
3) Run the entire test suite
46+
Coding Style
47+
~~~~~~~~~~~~
48+
49+
Please follow the MySQL Connector/Python coding standards when contributing with code.
50+
51+
All files should be formatted using the `black <https://github.com/psf/black>`_ auto-formatter and `isort <https://pycqa.github.io/isort/>`_. This will be run by `pre-commit <https://pre-commit.com>`_ if it's configured.
52+
53+
For C files, the `PEP 7 <https://peps.python.org/pep-0007/>`_ should be followed. A ``.clang-format`` configuration is included in the source, so you can manually format the code using the `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_ tool.
54+
55+
Pre-commit Checks
56+
~~~~~~~~~~~~~~~~~
57+
58+
MySQL Connector/Python comes with a pre-commit config file, which manages Git pre-commit hooks. These hooks are useful for identifing issues before committing code.
59+
60+
To use the pre-commit hooks, you first need to install the `pre-commit <https://pre-commit.com>`_ package and then the git hooks:
61+
62+
.. code-block:: bash
63+
64+
shell> python -m pip install pre-commit
65+
shell> pre-commit install
66+
67+
The first time pre-commit runs, it will automatically download, install, and run the hooks. Running the hooks for the first time may be slow, but subsequent checks will be significantly faster.
68+
69+
Now, pre-commit will run on every commit.
70+
71+
Running Tests
72+
-------------
73+
74+
Any code you contribute needs to pass our test suite. Please follow these steps to run our tests and validate your contributed code.
75+
76+
Run the entire test suite:
4777

4878
.. code-block:: bash
4979
50-
shell> python unittests.py --with-mysql=<mysql-dir> --with-mysql-capi=<mysql-capi-dir> --with-protobuf-include-dir=<protobuf-include-dir> --with-protobuf-lib-dir=<protobuf-lib-dir> --with-protoc=<protoc-binary> --extra-link-args="-L<mysql-lib-dir> -lssl -lcrypto"
80+
shell> python unittests.py --with-mysql=<mysql-dir> --with-mysql-capi=<mysql-capi-dir> --with-protobuf-include-dir=<protobuf-include-dir> --with-protobuf-lib-dir=<protobuf-lib-dir> --with-protoc=<protoc-binary>
5181
52-
Example:
82+
Example:
5383

5484
.. code-block:: sh
5585
56-
shell> python unittests.py --with-mysql=/usr/local/mysql --with-mysql-capi=/usr/local/mysql --with-protobuf-include-dir=/usr/local/protobuf/include --with-protobuf-lib-dir=/usr/local/protobuf/lib --with-protoc=/usr/local/protobuf/bin/protoc --extra-link-args="-L/usr/local/mysql/lib -lssl -lcrypto"
86+
shell> python unittests.py --with-mysql=/usr/local/mysql --with-mysql-capi=/usr/local/mysql --with-protobuf-include-dir=/usr/local/protobuf/include --with-protobuf-lib-dir=/usr/local/protobuf/lib --with-protoc=/usr/local/protobuf/bin/protoc
87+
88+
Test Coverage
89+
-------------
90+
91+
When submitting a patch that introduces changes to the source code, you need to make sure that those changes are be accompanied by a proper set of tests that cover 100% of the affected code paths. This is easily auditable by generating proper test coverage HTML and stdout reports using the following commands:
92+
93+
1) Install the `coverage.py <https://github.com/nedbat/coveragepy>`_ package
94+
95+
.. code-block:: bash
96+
97+
shell> python -m pip install coverage
98+
99+
2) Use coverage run to run your test suite and gather data
100+
101+
.. code-block:: bash
102+
103+
shell> coverage run unittests.py --with-mysql=<mysql-dir> --with-mysql-capi=<mysql-capi-dir> --with-protobuf-include-dir=<protobuf-include-dir> --with-protobuf-lib-dir=<protobuf-lib-dir> --with-protoc=<protoc-binary>
104+
105+
3) Use ``coverage report`` to report on the results
106+
107+
.. code-block:: bash
108+
109+
shell> coverage report -m
110+
111+
4) For a nicer presentation, use ``coverage html`` to get annotated HTML listings
112+
113+
.. code-block:: bash
114+
115+
shell> coverage html
57116
117+
The HTML will be generated in ``build/coverage_html``.
58118

59119
Getting Help
60120
------------

0 commit comments

Comments
 (0)