Skip to main content
Version: 0.18.21

Code style guide

Note

This style guide will be enforced for all incoming PRs. However, certain legacy areas within the repo do not yet fully adhere to the style guide. We welcome PRs to bring these areas up to code.

Code

  • Methods are almost always named using snake_case.

  • Methods that behave as operators (e.g. comparison or equality) are named using camelCase. These methods are rare and should be changed with great caution. Please reach out to us if you see the need for a change of this kind.

  • Experimental methods should log an experimental warning when called: “Warning: some_method is experimental. Methods, APIs, and core behavior may change in the future.”

  • Experimental classes should log an experimental warning when initialized: “Warning: great_expectations.some_module.SomeClass is experimental. Methods, APIs, and core behavior may change in the future.”

  • Docstrings are highly recommended. We use the Sphinx’s Napoleon extension to build documentation from Google-style docstrings.

Tasks

Common developer tasks such as linting, formatting, type-checking are defined in tasks.py and runnable via the invoke task runner library.

To see the available task run invoke --list from the project root.

Terminal
$ invoke --list
Available tasks:

fmt Run code formatter.
hooks Run and manage pre-commit hooks.
lint Run code linter
sort Sort module imports.
type-coverage Check total type-hint coverage compared to `develop`.
upgrade Run code syntax upgrades.

For detailed usage guide, invoke <TASK-NAME> --help

Terminal
$ invoke fmt --help
Usage: inv[oke] [--core-opts] fmt [--options] [other tasks here ...]

Docstring:
Run code formatter.

Options:
-c, --check Only checks for needed changes without writing back. Exit with error code if changes needed.
-e STRING, --exclude=STRING Exclude files or directories
-p STRING, --path=STRING Target path. (Default: .)
-s, --[no-]sort Disable import sorting. Runs by default.

Linting

Our CI system will check using black, and ruff.

If you have already committed files but are seeing errors during the continuous integration tests, you can run tests manually:

Terminal input
black <PATH/TO/YOUR/CHANGES>
ruff <PATH/TO/YOUR/CHANGES> --fix

Type Checking

Our CI system will perform static type-checking using mypy.

contrib and other select great_expectations packages are excluded from type-checking. See the mypy section in pyproject.toml for more details.

To verify your code will pass the CI type-checker, run invoke type-check --install-types. Or run mypy directly against the packages listed above.

Expectations

  • Use unambiguous Expectation names, even if they’re a bit longer, e.g. expect_columns_to_match_ordered_list instead of expect_columns_to_be.

  • Avoid abbreviations, e.g. column_index instead of column_idx.

  • Expectation names should be prefixed to reflect their base classes:

Base classprefix
Expectationexpect_...
BatchExpectationexpect_table_...
ColumnMapExpectationexpect_column_values_...
ColumnAggregateExpectationexpect_column_...
ColumnPairMapExpectationexpect_column_pair_values...
MultiColumnMapExpectationexpect_multicolumn_values...