Python Version

All Python code, and PEP support, 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.

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.

  1. PEP8

    PEP 8 is a set of recommended code style guidelines (conventions) for Python.

    PEP 8

  2. Linting tools

    CHIPSEC includes a Flake8 configuration file

    CHIPSEC flake8 config

  3. Zen of Python

    Great philosophy around Python building principles.

    PEP 20

  4. Headers and Comments

    Use single line comments, a single hash/number sign/octothorpe ‘#’.

    Should contain a space immediately after the ‘#’.

    # Good header comment
    
  5. Single vs Double Quotes

    Single quotes are encouraged but can vary with use case.

    Avoid using backslashes ‘\’ in strings.

    'This is a preferred "string".'
    "Also an acceptable 'string'."
    
    "Avoid making this \"string\"."
    
  6. Imports

    Import order:
    1. Python standard library

    2. Third-party imports

    3. CHIPSEC and local application imports

    Avoid using import * or from import *. This could pollute the namespace.

    # Good
    import sys
    from chipsec.module_common import BaseModule
    from chipsec.library.returncode import 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.

  7. 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.

  8. 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

  9. Constants

    Constants should use CAPITALIZATION_WITH_UNDERSCORES

  10. Variable Names

    Variable names should use snake_case

    Lower-case text with underscores between words.

  11. 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.

  12. 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.

  13. 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.

  14. 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.

    # 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
    
  15. 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.

  16. 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.

    # -*- coding: utf-8 -*-
    

    No non-ASCII class, function, or variable names.

  17. Docstrings

    Use three double-quotes for all docstrings.

    """String description docstring."""
    
  18. Semicolons

    Do not use semicolons.

  19. Try Except

    Avoid using nested try-except.

    The routine you are calling, may already be using one.

  20. Avoid for-else and while-else loops

    The loop behavior for these can be counterintuitive.

    If they have to be used, make sure to properly document the expected behavior / work-flow.

f-Strings

PEP versions supported by CHIPSEC

PEP / bpo

Title

Summary

Python Version

Supported

PEP 498

Literal String Interpolation

Adds a new string formatting mechanism: Literal String Interpolation, f-strings

3.6

Yes

bpo 36817

Add = to f-strings for easier debugging

f-strings support = for self-documenting expressions

3.8

No

PEP 701

Syntactic formalization of f-strings

Lift some restrictions from PEP 498 and formalize grammar for f-strings

3.12

No

Type Hints

For more information on Python Type Hints:

PEP 483 - The Theory of Type Hints

This table lists which Type Hint PEPs are in scope for CHIPSEC.

PEP versions supported by CHIPSEC

PEP

Title

Summary

Python Version

Supported

PEP 3107

Function Annotations

Syntax for adding arbitrary metadata annotations to Python functions

3.0

Yes

PEP 362

Function Signature Object

Contains all necessary information about a function and its parameters

3.3

Yes

PEP 484

Type Hints

Standard syntax for type annotations

3.5

Yes

PEP 526

Syntax for Variable Annotations

Adds syntax for annotating the types of variables

3.6

Yes

PEP 544

Protocols: Structural subtyping (static duck typing)

Specify type metadata for static type checkers and other third-party tools

3.8

No

PEP 585

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

Literal Types

Literal types indicate that some expression has literally a specific value(s).

3.8

No

PEP 589

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 593

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 604

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

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

Explicit Type Aliases

Formalizes a way to explicitly declare an assignment as a type alias

3.10

No

PEP 646

Variadic Generics

Introduce TypeVarTuple, enabling parameterisation with an arbitrary number of types

3.11

No

PEP 647

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

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

Self Type

Methods that return an instance of their class

3.10

No

PEP 675

Arbitrary Literal String Type

Introduces supertype of literal string types: LiteralString

3.11

No

PEP 681

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

Using TypedDict for more precise kwargs typing

A new syntax for specifying kwargs type as a TypedDict without breaking current behavior

3.12

No

PEP 695

Type Parameter Syntax

A syntax for specifying type parameters within a generic class, function, or type alias. And introduces a new statement for declaring type aliases.

3.12

No

PEP 698

Override Decorator for Static Typing

Adds @override decorator to allow type checkers to prevent a class of bugs that occur when a base class changes methods that are inherited by derived classes.

3.12

No

Underscores in Numeric Literals

Underscores in Numeric Literals are supported, even encouraged, but not required. For consistency, follow the grouping examples presented in the PEP abstract.

PEP versions supported by CHIPSEC

PEP

Title

Summary

Python Version

Supported

PEP 515

Underscores in Numeric Literals

Extends Python’s syntax so that underscores can be used as visual separators for grouping purposes in numerical literals

3.6

Yes

Walrus Operator (:=)

At this time, Assignment Expressions (Walrus operator) are not supported.

PEP versions supported by CHIPSEC

PEP

Title

Summary

Python Version

Supported

PEP 572

Assignment Expressions

Adds a way to assign to variables within an expression

3.8

No

Deprecate distutils module support

Python 3.12 will deprecate and remove the distutils module. In order for CHIPSEC to support this and furture versions of Python, setuptools should be used instead of distutils.

The setuptools module has been updated to fully replace distutils but requires an up-to-date version.

  • Minimum setuptools version: 62.0.0 (requires Python >= 3.7)

  • Recommended setuptools version: latest

Note: If you get any setuptools.command.build errors, verify that you have (at least) the minimum setuptools version.

PEP versions supported by CHIPSEC

PEP / bpo

Title

Summary

Python Version

Supported

PEP 632

Deprecate distutils module

Mark the distutils module as deprecated (3.10) and then remove it (3.12)

3.12

Yes