From fb03eef7fd49f57d1098dfa0bf75dc2a864d4f5e Mon Sep 17 00:00:00 2001 From: Russell Eck <36280534+Stockfoot@users.noreply.github.com> Date: Fri, 5 Jun 2020 13:47:14 -0600 Subject: [PATCH 1/3] Coding Style Guidline.rst Created a unified version of the Coding Style Guidelines Extracted rules from various pandas website information as well as submission scripts that verify style requirements Work in progress --- Coding Style Guidline.rst | 285 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 Coding Style Guidline.rst diff --git a/Coding Style Guidline.rst b/Coding Style Guidline.rst new file mode 100644 index 0000000000000..4b7eec5d9924d --- /dev/null +++ b/Coding Style Guidline.rst @@ -0,0 +1,285 @@ +pandas Coding Style Guide +========================= + +1 Background +------------ + +Writing good code is not just about what you write. It is also about how +you write it. During Continuous Integration testing, several tools will +be run to check your code for stylistic errors. Generating any warnings +will cause the test to fail. Thus, good style is a requirement for +submitting code to *pandas*. This document serves as a supplement to the +script demonstrating the proper coding style required for contributing +to *pandas*. + +2 Patterns +---------- + +2.1 Line Length +~~~~~~~~~~~~~~~ + +Line length is restricted to 80 characters to promote readability. + +2.2 Indentation +~~~~~~~~~~~~~~~ + +Indentations must be multiples of 4 + +For example: + +**Good:** + +:: + + if i == 0 + if x == 3 + x = 10 + +**Bad:** + +:: + + if i == 0 + if x == 3 + x = 10 + +2.3 Whitespaces Around Arithmetic Operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There must be whitespaces surrounding arithmetic operators + +**Good:** + +:: + + x = 3 + 5 / 2 + +**Bad:** + +:: + + x=3+5/2 + +2.4 Missing White Spaces After Commas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There must be a whitespace following a comma + +**Good:** + +:: + + myFunctionCall('a', 'b', 'c') + +**Bad:** + +:: + + myFunctionCall('a','b','c') + +2.5 Header File +~~~~~~~~~~~~~~~ + +Every header file must include a header guard to avoid name collision if +re-included. + +2.6 foo._class\_ +~~~~~~~~~~~~~~~~ + +**pandas** uses ‘type(foo)’ instead ‘foo.__class__’ as it is making the +code more readable. + +For example: + +**Good:** + +:: + + foo = "bar" + type(foo) + +**Bad:** + +:: + + foo = "bar" + foo.__class__ + +2.7 Bare Pytest Raises +~~~~~~~~~~~~~~~~~~~~~~ + +**Good:** + +:: + + with pytest.raise(ValueError, match="foo"): + # following code that raises ValueError + +**Bad:** + +:: + + with pytest.raise(ValueError): + # following code that raises ValueError + +3 String Formatting +------------------- + +3.1 Concatenated Strings +~~~~~~~~~~~~~~~~~~~~~~~~ + +3.1.1 f-strings +^^^^^^^^^^^^^^^ + +*pandas* uses f-strings formatting instead of ‘%’ and ‘.format()’ string +formatters. + +The convention of using f-strings on a string that is concatenated over +serveral lines, is to prefix only the lines containing the value needs +to be interpeted. + +For example: + +**Good:** + +:: + + foo = "old_function" + bar = "new_function" + + my_warning_message = ( + f"Warning, {foo} is deprecated, " + "please use the new and way better " + f"{bar}" + ) + +**Bad:** + +:: + + foo = "old_function" + bar = "new_function" + + my_warning_message = ( + f"Warning, {foo} is deprecated, " + f"please use the new and way better " + f"{bar}" + ) + +3.1.2 White Spaces +^^^^^^^^^^^^^^^^^^ + +Putting the white space only at the end of the previous line, so there +is no whitespace at the beggining of the concatenated string. + +For example: + +**Good:** + +:: + + example_string = ( + "Some long concatenated string, " + "with good placement of the " + "whitespaces" + ) + +**Bad:** + +:: + + example_string = ( + "Some long concatenated string," + " with bad placement of the" + " whitespaces" + ) + +3.2 Representation function (aka ‘repr()’) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*pandas* uses ‘repr()’ instead of ‘%r’ and ‘!r’. + +The use of ‘repr()’ will only happend when the value is not an obvious +string. + +For example: + +**Good:** + +:: + + value = str + f"Unknown recived value, got: {repr(value)}" + +**Bad:** + +:: + + value = str + f"Unknown recived type, got: '{type(value).__name__}'" + +4 Types +------- + +**pandas** strongly encourages the use of PEP 484 style type hints. New +development should contain type hints and pull requests to annotate +existing code are accepted as well! + +4.1 Imports +~~~~~~~~~~~ + +Types imports should follow the ``from typing import ...`` convention. + +**Good:** + +:: + + from typing import List, Optional, Union + + primes: List[int] = [] + +**Bad:** + +:: + + import typing + + primes: typing.List[int] = [] + +Optional should be used where applicable + +**Good:** + +:: + + maybe_primes: List[Optional[int]] = [] + +**Bad:** + +:: + + maybe_primes: List[Union[int, None]] = [] + +4.1.1 Redundant Imports +^^^^^^^^^^^^^^^^^^^^^^^ + +Should not import numpy and pandas + +**Example:** + +:: + + import numpy as np + import pandas as pd + +4.1.2 Unused Imports +^^^^^^^^^^^^^^^^^^^^ + +Unused imports must be removed prior to submission + +**Example:** + +:: + + import pandas as pdf + df = pd.DataFrame(np.ones((3, 3)), columns=('a', 'b', 'c')) From c726a00a4d75b938f112817e7768fe1873fc0763 Mon Sep 17 00:00:00 2001 From: Russell Eck <36280534+Stockfoot@users.noreply.github.com> Date: Mon, 22 Jun 2020 10:45:21 -0600 Subject: [PATCH 2/3] Removed Sections Enforced by Black --- Coding Style Guidline.rst | 68 ++------------------------------------- 1 file changed, 3 insertions(+), 65 deletions(-) diff --git a/Coding Style Guidline.rst b/Coding Style Guidline.rst index 4b7eec5d9924d..33b35989144fe 100644 --- a/Coding Style Guidline.rst +++ b/Coding Style Guidline.rst @@ -15,75 +15,13 @@ to *pandas*. 2 Patterns ---------- -2.1 Line Length -~~~~~~~~~~~~~~~ - -Line length is restricted to 80 characters to promote readability. - -2.2 Indentation -~~~~~~~~~~~~~~~ - -Indentations must be multiples of 4 - -For example: - -**Good:** - -:: - - if i == 0 - if x == 3 - x = 10 - -**Bad:** - -:: - - if i == 0 - if x == 3 - x = 10 - -2.3 Whitespaces Around Arithmetic Operators -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There must be whitespaces surrounding arithmetic operators - -**Good:** - -:: - - x = 3 + 5 / 2 - -**Bad:** - -:: - - x=3+5/2 - -2.4 Missing White Spaces After Commas -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There must be a whitespace following a comma - -**Good:** - -:: - - myFunctionCall('a', 'b', 'c') - -**Bad:** - -:: - - myFunctionCall('a','b','c') - -2.5 Header File +2.1 Header File ~~~~~~~~~~~~~~~ Every header file must include a header guard to avoid name collision if re-included. -2.6 foo._class\_ +2.2 foo._class\_ ~~~~~~~~~~~~~~~~ **pandas** uses ‘type(foo)’ instead ‘foo.__class__’ as it is making the @@ -105,7 +43,7 @@ For example: foo = "bar" foo.__class__ -2.7 Bare Pytest Raises +2.3 Bare Pytest Raises ~~~~~~~~~~~~~~~~~~~~~~ **Good:** From 0967ecab86f1c4939737cf20792f29e5099a77b5 Mon Sep 17 00:00:00 2001 From: Russell Eck <36280534+Stockfoot@users.noreply.github.com> Date: Wed, 1 Jul 2020 15:00:29 -0600 Subject: [PATCH 3/3] Removed Sections and Changed Code Block Directives --- Coding Style Guidline.rst | 54 +++++++++++++-------------------------- 1 file changed, 18 insertions(+), 36 deletions(-) diff --git a/Coding Style Guidline.rst b/Coding Style Guidline.rst index 33b35989144fe..a3e2bfb9ed89a 100644 --- a/Coding Style Guidline.rst +++ b/Coding Style Guidline.rst @@ -15,13 +15,7 @@ to *pandas*. 2 Patterns ---------- -2.1 Header File -~~~~~~~~~~~~~~~ - -Every header file must include a header guard to avoid name collision if -re-included. - -2.2 foo._class\_ +2.1 foo._class\_ ~~~~~~~~~~~~~~~~ **pandas** uses ‘type(foo)’ instead ‘foo.__class__’ as it is making the @@ -31,31 +25,31 @@ For example: **Good:** -:: +.. code-block:: python foo = "bar" type(foo) **Bad:** -:: +.. code-block:: python foo = "bar" foo.__class__ -2.3 Bare Pytest Raises +2.2 Bare Pytest Raises ~~~~~~~~~~~~~~~~~~~~~~ **Good:** -:: +.. code-block:: python with pytest.raise(ValueError, match="foo"): # following code that raises ValueError **Bad:** -:: +.. code-block:: python with pytest.raise(ValueError): # following code that raises ValueError @@ -80,7 +74,7 @@ For example: **Good:** -:: +.. code-block:: python foo = "old_function" bar = "new_function" @@ -93,7 +87,7 @@ For example: **Bad:** -:: +.. code-block:: python foo = "old_function" bar = "new_function" @@ -114,7 +108,7 @@ For example: **Good:** -:: +.. code-block:: python example_string = ( "Some long concatenated string, " @@ -124,7 +118,7 @@ For example: **Bad:** -:: +.. code-block:: python example_string = ( "Some long concatenated string," @@ -144,14 +138,14 @@ For example: **Good:** -:: +.. code-block:: python value = str f"Unknown recived value, got: {repr(value)}" **Bad:** -:: +.. code-block:: python value = str f"Unknown recived type, got: '{type(value).__name__}'" @@ -170,7 +164,7 @@ Types imports should follow the ``from typing import ...`` convention. **Good:** -:: +.. code-block:: python from typing import List, Optional, Union @@ -178,7 +172,7 @@ Types imports should follow the ``from typing import ...`` convention. **Bad:** -:: +.. code-block:: python import typing @@ -188,36 +182,24 @@ Optional should be used where applicable **Good:** -:: +.. code-block:: python maybe_primes: List[Optional[int]] = [] **Bad:** -:: +.. code-block:: python maybe_primes: List[Union[int, None]] = [] -4.1.1 Redundant Imports -^^^^^^^^^^^^^^^^^^^^^^^ - -Should not import numpy and pandas - -**Example:** - -:: - - import numpy as np - import pandas as pd - -4.1.2 Unused Imports +4.1.1 Unused Imports ^^^^^^^^^^^^^^^^^^^^ Unused imports must be removed prior to submission **Example:** -:: +.. code-block:: python import pandas as pdf df = pd.DataFrame(np.ones((3, 3)), columns=('a', 'b', 'c'))