mirror of
https://github.com/chipsec/chipsec
synced 2026-06-08 13:31:00 +00:00
Frinzell, Aaron
315 lines
9.4 KiB
ReStructuredText
315 lines
9.4 KiB
ReStructuredText
Python Coding Style Guide
|
|
=========================
|
|
|
|
CHIPSEC mostly follows the PEP8 with some exceptions. This attempts to highlight those as well as clarify others.
|
|
|
|
Consistency and readability are the goal but not at the expense of readability or functionality.
|
|
|
|
If in doubt, follow the existing code style and formatting.
|
|
|
|
|
|
#. PEP8
|
|
|
|
PEP 8 is a set of recommended code style guidelines (conventions) for Python.
|
|
|
|
`PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_
|
|
|
|
|
|
#. Linting tools
|
|
|
|
CHIPSEC includes a Flake8 configuration file
|
|
|
|
`CHIPSEC flake8 config <https://github.com/chipsec/chipsec/blob/master/.flake8>`_
|
|
|
|
|
|
#. Zen of Python
|
|
|
|
Great philosophy around Python building principles.
|
|
|
|
`PEP 20 <https://www.python.org/dev/peps/pep-0020/>`_
|
|
|
|
|
|
#. Headers and Comments
|
|
|
|
Use single line comments, a single hash/number sign/octothorpe '#'.
|
|
|
|
Should contain a space immediately after the '#'.
|
|
|
|
.. code-block:: python
|
|
|
|
# Good header comment
|
|
|
|
|
|
#. Single vs Double Quotes
|
|
|
|
Single quotes are encouraged but can vary with use case.
|
|
|
|
Avoid using backslashes '\\' in strings.
|
|
|
|
.. code-block:: python
|
|
|
|
'This is a preferred "string".'
|
|
"Also an acceptable 'string'."
|
|
|
|
"Avoid making this \"string\"."
|
|
|
|
|
|
#. Imports
|
|
|
|
Import order:
|
|
#. Python standard library
|
|
#. Third-party imports
|
|
#. CHIPSEC and local application imports
|
|
|
|
Avoid using ``import *`` or ``from import *``. This could pollute the namespace.
|
|
|
|
.. code-block:: python
|
|
|
|
# Good
|
|
import sys
|
|
from chipsec.module_common import BaseModule, ModuleResult
|
|
|
|
# Bad - using '*' and importing sys after local imports
|
|
import *
|
|
from chipsec.module_common import *
|
|
import sys
|
|
|
|
Avoid using ``from __future__ imports``. These may not work on older or all interpreter versions required in all supported environments.
|
|
|
|
|
|
#. Line Length
|
|
|
|
Maximum line length should be 120 characters.
|
|
|
|
If at or near this limit, consider rewriting (eg simplifying) the line instead of breaking it into multiple lines.
|
|
|
|
Long lines can be an indication that too many things are happening at once and/or difficult to read.
|
|
|
|
|
|
#. Class Names
|
|
|
|
``HAL`` and ``utilcmd`` **classes** should use **UpperCamelCase** (**PascalCase**)
|
|
Words and acronyms are capitalized with no spaces or underscores.
|
|
|
|
Test **module** class names MUST match the module name which are typically **snake_case**
|
|
|
|
|
|
#. Constants
|
|
|
|
Constants should use **CAPITALIZATION_WITH_UNDERSCORES**
|
|
|
|
|
|
#. Variable Names
|
|
|
|
Variable names should use **snake_case**
|
|
|
|
Lower-case text with underscores between words.
|
|
|
|
|
|
#. Local Variable Names (private)
|
|
|
|
Prefixed with an underscore, **_private_variable**
|
|
|
|
Not a hard rule but will help minimize any variable name collisions with upstream namespace.
|
|
|
|
|
|
#. Dunder (double underscore)
|
|
|
|
Avoid using ``__dunders__`` when naming variables. Should be used for functions that overwrite or add to classes and only as needed.
|
|
|
|
Dunders utilize double (two) underscore characters before and after the name.
|
|
|
|
|
|
#. Code Indents
|
|
|
|
CHIPSEC uses 4 space 'tabbed' indents.
|
|
|
|
No mixing spaces and tabs.
|
|
|
|
- 1 indent = 4 spaces
|
|
- No tabs
|
|
|
|
Recommend updating any IDE used to use 4 space indents by default to help avoid mixing tabs with spaces in the code.
|
|
|
|
|
|
#. Operator Precedence, Comparisons, and Parentheses
|
|
|
|
If in doubt, wrap evaluated operators into logical sections if using multiple operators or improves readability.
|
|
|
|
While not needed in most cases, it can improve readability and limit the possibility of 'left-to-right chaining' issues.
|
|
|
|
.. code-block:: python
|
|
|
|
# Preferred
|
|
if (test1 == True) or (test2 in data_list):
|
|
return True
|
|
|
|
# Avoid. Legal but behavior may not be immediately evident.
|
|
if True is False == False:
|
|
return False
|
|
|
|
|
|
#. Whitespace
|
|
|
|
No whitespace inside parentheses, brackets, or braces.
|
|
|
|
No whitespace before a comma, colon, or semicolons.
|
|
|
|
Use whitespace after a comma, colon, or semicolon.
|
|
|
|
Use whitespace around operators: +, -, \*, \**, /, //, %, =, ==, <, >, <=, >=, <>, !=, is, in, is not, not in, <<, >>, &, \|, ^
|
|
|
|
No trailing whitespace.
|
|
|
|
|
|
#. Non-ASCII Characters
|
|
|
|
If including any non-ASCII characters anywhere in a python file, include the python encoding comment at the beginning of the file.
|
|
|
|
.. code-block:: python
|
|
|
|
# -*- coding: utf-8 -*-
|
|
|
|
No non-ASCII class, function, or variable names.
|
|
|
|
|
|
#. Docstrings
|
|
|
|
Use three double-quotes for all docstrings.
|
|
|
|
.. code-block:: python
|
|
|
|
"""String description docstring."""
|
|
|
|
|
|
#. Semicolons
|
|
|
|
Do not use semicolons.
|
|
|
|
|
|
#. Try Except
|
|
|
|
Avoid using nested try-except.
|
|
|
|
The routine you are calling, may already be using one.
|
|
|
|
|
|
Type Hints
|
|
==========
|
|
|
|
Employing Type Hints is encouraged but any commits utilizing them must to be limited to the features supported by **Python 3.6.8**.
|
|
|
|
This is earliest version of Python utilized by CHIPSEC, the version of the EFI Shell Python.
|
|
|
|
For more information on Python Type Hints:
|
|
`PEP 483 - The Theory of Type Hints <https://peps.python.org/pep-0483/>`_
|
|
|
|
|
|
This table lists which Type Hint PEPs are in scope for CHIPSEC.
|
|
|
|
.. list-table:: PEP versions supported by CHIPSEC
|
|
:widths: 9 25 25 12 10
|
|
:header-rows: 1
|
|
|
|
* - PEP
|
|
- Title
|
|
- Summary
|
|
- Python Version
|
|
- Supported
|
|
* - `PEP 3107 <https://www.python.org/dev/peps/pep-3107/>`_
|
|
- Function Annotations
|
|
- Syntax for adding arbitrary metadata annotations to Python functions
|
|
- 3.0
|
|
- Yes
|
|
* - `PEP 362 <https://www.python.org/dev/peps/pep-0362/>`_
|
|
- Function Signature Object
|
|
- Contains all necessary information about a function and its parameters
|
|
- 3.3
|
|
- Yes
|
|
* - `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_
|
|
- Type Hints
|
|
- Standard syntax for type annotations
|
|
- 3.5
|
|
- Yes
|
|
* - `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_
|
|
- Syntax for Variable Annotations
|
|
- Adds syntax for annotating the types of variables
|
|
- 3.6
|
|
- Yes
|
|
* - `PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_
|
|
- Protocols: Structural subtyping (static duck typing)
|
|
- Specify type metadata for static type checkers and other third party tools
|
|
- 3.8
|
|
- No
|
|
* - `PEP 585 <https://www.python.org/dev/peps/pep-0585/>`_
|
|
- Type Hinting Generics In Standard Collections
|
|
- Enable support for the generics syntax in all standard collections currently available in the typing module
|
|
- 3.9
|
|
- No
|
|
* - `PEP 586 <https://www.python.org/dev/peps/pep-0586/>`_
|
|
- Literal Types
|
|
- Literal types indicate that some expression has literally a specific value(s).
|
|
- 3.8
|
|
- No
|
|
* - `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_
|
|
- Flexible function and variable annotations
|
|
- Adds an Annotated type to the typing module to decorate existing types with context-specific metadata.
|
|
- 3.9
|
|
- No
|
|
* - `PEP 598 <https://www.python.org/dev/peps/pep-0598/>`_
|
|
- TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys
|
|
- Support dictionary object with a specific set of string keys, each with a value of a specific type
|
|
- 3.8
|
|
- No
|
|
* - `PEP 604 <https://www.python.org/dev/peps/pep-0604/>`_
|
|
- Allow writing union types as X | Y
|
|
- Overload the | operator on types to allow writing Union[X, Y] as X | Y
|
|
- 3.10
|
|
- No
|
|
* - `PEP 612 <https://www.python.org/dev/peps/pep-0612/>`_
|
|
- Parameter Specification Variables
|
|
- Proposes typing.ParamSpec and typing.Concatenate to support forwarding parameter types of one callable over to another callable
|
|
- 3.10
|
|
- No
|
|
* - `PEP 613 <https://www.python.org/dev/peps/pep-0613/>`_
|
|
- Explicit Type Aliases
|
|
- Formalizes a way to explicitly declare an assignment as a type alias
|
|
- 3.10
|
|
- No
|
|
* - `PEP 646 <https://www.python.org/dev/peps/pep-0646/>`_
|
|
- Variadic Generics
|
|
- Introduce TypeVarTuple, enabling parameterisation with an arbitrary number of types
|
|
- 3.11
|
|
- No
|
|
* - `PEP 647 <https://www.python.org/dev/peps/pep-0647/>`_
|
|
- User-Defined Type Guards
|
|
- Specifies a way for programs to influence conditional type narrowing employed by a type checker based on runtime checks
|
|
- 3.11
|
|
- No
|
|
* - `PEP 655 <https://www.python.org/dev/peps/pep-0655/>`_
|
|
- Marking individual TypedDict items as required or potentially-missing
|
|
- Two new notations: Required[], which can be used on individual items of a TypedDict to mark them as required, and NotRequired[]
|
|
- 3.11
|
|
- No
|
|
* - `PEP 673 <https://www.python.org/dev/peps/pep-0673/>`_
|
|
- Self Type
|
|
- Methods that return an instance of their class
|
|
- 3.10
|
|
- No
|
|
* - `PEP 675 <https://www.python.org/dev/peps/pep-0675/>`_
|
|
- Arbitrary Literal String Type
|
|
- Introduces supertype of literal string types: LiteralString
|
|
- 3.11
|
|
- No
|
|
* - `PEP 681 <https://www.python.org/dev/peps/pep-0681/>`_
|
|
- Data Class Transforms
|
|
- Provides a way for third-party libraries to indicate that certain decorator functions, classes, and metaclasses provide behaviors similar to dataclasses
|
|
- 3.11
|
|
- No
|
|
* - `PEP 692 <https://www.python.org/dev/peps/pep-0692/>`_
|
|
- Using TypedDict for more precise kwargs typing
|
|
- A new syntax for specifying kwargs type as a TypedDict without breaking current behavior
|
|
- 3.12
|
|
- No
|
|
|