Skip to content

Configuration

Configuration is done in pyproject.toml, located in the project's top-level directory.

Default Configuration

pyproject.toml

[tool.structlint]
project_root = "."

[tool.structlint.docs]
allow_additional = false
file_per_class = ""
file_per_directory = "utils"
ignore = ":_[A-Z]"
keep_double_underscore = true
md_dir = "docs/md/api"

[tool.structlint.imports]
primitive_modules = ["regexes"]
external_allowed_everywhere = [
    "collections",
    "os",
    "pathlib",
    "re",
    "sys",
    "typing",
]
internal_allowed_everywhere = ["utils"]

[tool.structlint.imports.disallowed.internal]

[tool.scripts.imports.disallowed.external]

[tool.structlint.methods]
init = 0
abstract_property = 1
property = 2
abstract_private_property = 3
private_property = 4
abstract_dunder = 5
dunder = 6
abstract_classmethod = 7
classmethod = 8
abstract = 9
normal = 10
final = 11
abstract_static = 12
static = 13
abstract_private = 14
private = 15
mangled = 16

[tool.structlint.methods.regex]


[tool.structlint.tests]
unit_dir = "tests/unit"
use_filename_suffix = true
allow_additional = false
ignore = "_[A-Za-z]|__get_pydantic_core_schema__"
file_per_class = ""
file_per_directory = ""
function_per_class = ""
keep_double_underscore = true

Configuration for structlint Source Code

pyproject.toml

[tool.structlint]
source_directory = "src"

[tool.structlint.docs]
md_dir = "docs/md/api"
allow_additional = false
ignore = "exceptions.py|:_[A-Z]"
file_per_class = ""
file_per_directory = "linus|guido|grace|utils"
replace_double_underscore = false

[tool.structlint.imports]
primitive_modules = ["regexes"]
external_allowed_everywhere = [
    "collections",
    "os",
    "pathlib",
    "re",
    "sys",
    "typing",
]
internal_allowed_everywhere = ["regexes"]

[tool.structlint.imports.disallowed.internal]
utils = ["utils"]

[tool.scripts.imports.disallowed.external]
utils = ["pydantic"]

[tool.structlint.methods.builtins_order]
init = 0
abstract_property = 1
property = 2
abstract_private_property = 3
private_property = 4
abstract_dunder = 5
dunder = 6
abstract_classmethod = 7
classmethod = 8
abstract = 9
normal = 10
final = 11
abstract_static = 12
static = 13
abstract_private = 14
private = 15
mangled = 16

[tool.structlint.tests]
unit_dir = "tests/unit"
use_filename_suffix = true
allow_additional = false
ignore = ":test__[A-Z]|__init__$|_abcs|exceptions|__get_pydantic_core_schema__"
file_per_class = ""
file_per_directory = "linus|guido|grace|utils"
function_per_class = ""
replace_double_underscore = true

Example Custom Configuration

pyproject.toml

[tool.structlint.methods.custom_order]
"@model_validator|model_validate" = 0
"_pydantic_" = 0.01
" adapter(" = 0.011
"@field_validator" = 0.1
"model_serializ|model_dump" = 0.00001
"@field_serializer" = 0.3
"__call__" = 0.99
"check_.+" = 9
" read[^ ]+(" = 3.98
" write[^ ]+(" = 3.99
"[^_][a-z_]+_hook$" = 9

Configuration Options

Note: All options annotated with '{{structlint_REGEX}}' are TOML strings which must support compilation to valid regular expressions via the Python Standard Library's re.compile. However, unlike regular expressions, if the string is empty, it will be treated by structlint as matching nothing. Alternatively, a list of strings may be passed and they will be joined with | before compilation as a regular expression.

For example, the following are equivalent:

  • file_per_class = ["match_this", "or_this"]
  • file_per_class = "match_this|or_this"

Note that object paths are of the form "{{path}}:{{class_name}}.{{method_name}}" or "{{path}}:{{function_name}}", so regexes can be written accordingly.

[tool.structlint] (global configs for structlint)

  • checks: array[string]: default ["docs", "imports", "methods", "tests"]
  • source_root: string: default "src"
  • module_name: string: default derived from pyproject.toml

[tool.structlint.docs]

  • md_dir: string: default "docs/md/api":

    Directory in which the documentation markdown files reside.

  • allow_additional: true | false | {{structlint_REGEX}}:

    which 'unexpected' documentation objects (i.e. objects in the documentation lacking a direct correspondance in the source code) should be allowed.

  • ignore: structlint_REGEX: default ":_[A-Z]":

    Pattern to match all source paths and objects which are to not required to have a corresponding documentation entry.

  • file_per_class: structlint_REGEX: default "":

    Pattern to match all classes which are to receive their own documentation file.

  • file_per_directory: structlint_REGEX: default "":

    Pattern to match all directories which are to be compressed into a single documentation file.

[tool.structlint.imports]

For each of internal and external, only one of allowed and disallowed should be specified. Analogously to the behavior of firewall rules, specifying allowed imports will disallow everything not explicitly listed. Conversely, specifying disallowed imports will allow everything not explicitly listed.

If, contrary to these guidelines, both options are specified, structlint will emit a warning and ignore the disallow list.

[tool.structlint.imports.external.allowed]

table[string, array[string]]

  • {{IMPORTING_MODULE_NAME}} = {{IMPORT_NAME_ARRAY}}

[tool.structlint.imports.external.disallowed]

table[string, array[string]]

  • {{IMPORTING_MODULE_NAME}} = {{IMPORT_NAME_ARRAY}}

[tool.structlint.imports.internal.allowed]

table[string, array[string]]

  • {{IMPORTING_MODULE_NAME}} = {{IMPORT_NAME_ARRAY}}

[tool.structlint.imports.internal.disallowed]

table[string, array[string]]

  • {{IMPORTING_MODULE_NAME}} = {{IMPORT_NAME_ARRAY}}

[tool.structlint.methods]

  • normal: float: default 999.0

[tool.structlint.methods.builtins_order]

While these fields have default values, they should be included for readability if any custom patterns are passed in the next section, as ordering is purely relative.

  • init = {{ORDERING_FLOAT}}: default 0.0
  • abstract_property = {{ORDERING_FLOAT}}: default 1.0
  • property = {{ORDERING_FLOAT}}: default 2.0
  • abstract_private_property = {{ORDERING_FLOAT}}: default 3.0
  • private_property = {{ORDERING_FLOAT}}: default 4.0
  • abstract_dunder = {{ORDERING_FLOAT}}: default 5.0
  • dunder = {{ORDERING_FLOAT}}: default 6.0
  • abstract_classmethod = {{ORDERING_FLOAT}}: default 7.0
  • classmethod = {{ORDERING_FLOAT}}: default 8.0
  • abstract = {{ORDERING_FLOAT}}: default 9.0
  • normal = {{ORDERING_FLOAT}}: default 10.0
  • final = {{ORDERING_FLOAT}}: default 11.0
  • abstract_static = {{ORDERING_FLOAT}}: default 12.0
  • static = {{ORDERING_FLOAT}}: default 13.0
  • abstract_private = {{ORDERING_FLOAT}}: default 14.0
  • private = {{ORDERING_FLOAT}}: default 15.0
  • mangled = {{ORDERING_FLOAT}}: default 16.0

[tool.structlint.methods.custom_order]

A mapping assigning numerical values to regular expressions for purposes of method order enforcement.

The order of regular expressions matters here, because the value corresponding to the first matching regular expression is used. Thus, when multiple regular expressions can match the same method, the narrower expression should precede the broader expression. In accordance with this principle of "narrow before broad", custom regular expressions are matched against before the built-in regular expressions, which are mapped to the ordinal values declared in the previous section.

  • {{structlint_REGEX}} = {{ORDERING_FLOAT}}

[tool.structlint.tests]

  • unit_dir: string: default "tests/unit"

    Directory in which the unit tests reside.

  • use_filename_suffix: boolean: default true:

    Whether test files use the naming convention *_test.py; if false, then test_*.

  • allow_additional: true | false | {{structlint_REGEX}}: default: true

    Which 'unexpected' test objects (i.e. objects in the tests lacking a direct correspondance in the source code) should be allowed; default is to allow all.

  • ignore: structlint_REGEX: default: ":_[A-Za-z]|__get_pydantic_core_schema__"

    Pattern to filter out source paths and objects which are to be ignored.

  • file_per_class: structlint_REGEX:

    Pattern to match all classes which are to receive their own test file.

  • file_per_directory: structlint_REGEX:

    Pattern to match all directories which are to be collapsed into a single test file.

  • function_per_class: structlint_REGEX:

    Pattern to match all classes which should be mapped to a test function instead of a test class.

  • replace_double_underscore: boolean: default false:

    Whether double and triple underscores should be replaced with a single underscore in test file names and test object names. For example a method named _shuffle will make structlint expect a test method named test__shuffle if this is set to false and test_shuffle if it is set to true.