`.sourcery.yaml`: The Configuration File¶

This document describes the format of the Sourcery configuration file.

The file uses YAML syntax. If you are new to YAML check out "Learn YAML in 5 minutes".

Note

Sourcery reads User-level configuration settings from your system, and Project-level configuration settings from your project root directory. (See Configuration Sources for more detail.)

Hint

Sourcery doesn't automatically create a .sourcery.yaml file for you in each project, but you can quickly set one up by copying the default below, or by running the sourcery init command from the command line or from within VS Code.

Hint

You can configure a remote schema to enable autocompletion in your IDE. See Guides: IDE Autocompletion for more detail.

Fields Overview¶

All fields are optional.

Field	Type	Description
ignore	list of string	A list of files, directories, or patterns which Sourcery will not analyze.
rule_settings	object: Rule Settings	Configuration of rules to enable or disable.
rules	list of Rule	A list of additional, project-specific rules for Sourcery to apply.
rule_tags	object	Additional tags to create from rules or other tags.
metrics	object	Configuration of code quality metric behaviour.
github	object: GitHub	Github-specific configuration.
clone_detection	object: Clone Detection	Configuration for Sourcery's Clone Detection feature.
proxy	object: Proxy	Configuration for running Sourcery with a proxy.

Default¶

ignore:
    - .git
    - venv
    - .venv
    - env
    - .env
    - .tox
    - node_modules
    - vendor

rule_settings:
  enable: [default]
  disable: []
  rule_types:
    - refactoring
    - suggestion
    - comment
  python_version: '3.9'

rules: []

metrics:
  quality_threshold: 25.0

github:
  labels: []
  ignore_labels:
    - sourcery-ignore
  request_review: author
  sourcery_branch: sourcery/{base_branch}

clone_detection:
  min_lines: 3
  min_duplicates: 2
  identical_clones_only: false

proxy:
  no_ssl_verify: false

Fields¶

`ignore`¶

list of string (optional)

A list of files, directories, or patterns Sourcery will not analyze.

This affects the IDE plugins, the CLI, and GitHub.

Directories are recursively walked and all Python files within them will be ignored.

Wildcard patterns (glob style) like test_*.pyare supported.

Recursive globs using ** are not supported

Default

ignore:
    - .git
    - venv
    - .venv
    - env
    - .env
    - .tox
    - node_modules
    - vendor

Example

ignore:
  - setup.py     # ignore the `setup.py` file
  - .venv/       # ignore everything in the `.venv` directory
  - tests/       # ignore everything in the `tests` directory
  - data/*       # ignore all files in the `data` directory, but not in subdirectories
  - test_*.py    # ignore all Python test files
  - '*_test.py'  # strings beginning with * must be quoted

Info

Sourcery will always ignore the GitHub workflows directory, because third-party GitHub applications are not permitted to make changes to this directory.

`rule_settings`¶

object: rule_settings

Configuration of rules to enable or disable.

Default

rule_settings:
  enable: [default]
  disable: []
  rule_types:
    - refactoring
    - suggestion
    - comment
  python_version: '3.9'

Note

The default rules are the ones that are automatically run in the IDE and command line if there is no config.

Example

rule_settings:
  enable: [default]
  disable:
    - for-append-to-extend
    - raise-from-previous-error
  rule_types:
    - refactoring
    - suggestion
  python_version: 3.8

See Also

Reference: rule_settings Configuration

`rules`¶

list of Rule

A list of project-specific rules for Sourcery to apply.

Default

(Empty list)

Example

rules:
  - id: do-not-raise-not-implemented
    description: NotImplemented is not an Exception, raise NotImplementedError instead
    pattern: raise NotImplemented
    replacement: raise NotImplementedError
  - id: remove-open-r
    description: Files are opened in read mode `r` by default
    # This pattern uses a capture ${file} to capture the first argument
    pattern: open(${file}, "r")
    # The capture is substituted into the replacement
    replacement: open(${file})
    # Test that this rule is working as expected
    tests:
      - match: |
          with open("data.txt", "r") as file:
              data = file.read()
        expect: |
          with open("data.txt") as file:
              data = file.read()
      - no-match: |
          with open("data.txt", "w") as file:
              file.write(data)
    # The paths to include and exclude
    paths:
      # Paths to include
      include:
        - test/*.py
      # Exclude takes precedence over include so test/conftest.py is excluded
      exclude:
        - conftest.py

See Also

`rule_tags`¶

object

An object whose keys define new tags and whose values are arrays of rule IDs or other tags.

Default

None (no additional tags)

Example

rules:
  - id: tuple-literal
    description: Replace tuples created with `tuple()` with `()`
    pattern: tuple()
    replacement: ()
    tags:
    - stylistic

rule_tags:
  use-literals:
  - list-literal
  - tuple-literal

  use-comprehensions:
  - dict-comprehension
  - list-comprehension
  - set-comprehension

  critical-rules:
  - use-literals
  - use-comprehensions

  pre-commit-rules:
  - stylistic
  - critical-rules

`metrics`¶

Configuration for Sourcery's code quality metrics.

metrics supports one subfield, quality_threshold, which can take a value between 0 and 100. If the code quality of a function falls below this threshold, Sourcery will highlight the function in your IDE.

Default

metrics:
  quality_threshold: 25.0

Example

metrics:
  quality_threshold: 30.0

Hint

You can control whether or not Sourcery's metrics are displayed in your IDE by toggling the switch within the IDE plugin settings.

Hint

These warnings can also be disabled in the same way as refactorings - by adding low-code-quality to the list of disabled rules in the config file or by adding a # sourcery skip: low-code-quality comment to a particular function. See inline configuration for reference.

See Also

`github`¶

object: GitHub

Configuration specific to the Sourcery GitHub bot.

Default

github:
  ignore_labels:
    - sourcery-ignore
  request_review: author
  sourcery_branch: sourcery/{base_branch}

Example

github:
  ignore_labels:
    - sourcery-ignore
  labels:
    - build-ignore
  request_review:
    origin: owner
    forked: author
  sourcery_branch: sourcery/{base_branch}

See Also

Reference: GitHub Configuration

`clone_detection`¶

object: Clone Detection

Configuration for Sourcery's Clone Detection feature.

Default

github:
  clone_detection:
    min_lines: 3
    min_duplicates: 2
    identical_clones_only: false

Example

github:
  clone_detection:
    min_lines: 5
    identical_clones_only: true

See Also

Reference: Clone Detection Configuration

`proxy`¶

object: Proxy

Configuration options for running Sourcery using a proxy.

Default

proxy:
  no_ssl_verify: false

Example

proxy:
  url: https://user:password@host:port
  ssl_certs_file: /path/to/cafile.pem
  no_ssl_verify: false

See Also

Reference: Proxy Configuration

.sourcery.yaml: The Configuration File¶

Fields Overview¶

Default¶

Fields¶

ignore¶

rule_settings¶

rules¶

rule_tags¶

metrics¶

github¶

clone_detection¶

proxy¶

`.sourcery.yaml`: The Configuration File¶

`ignore`¶

`rule_settings`¶

`rules`¶

`rule_tags`¶

`metrics`¶

`github`¶

`clone_detection`¶

`proxy`¶