Skip to content

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

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.
refactor object: Refactor Configuration of rules to include or skip.
rules list of Rule A list of additional, customisable rules for Sourcery to apply.
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: []

refactor:
  include: []
  skip: []
  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) are supported.

Default

ignore:
  - .github/workflows/*

Example

ignore:
  - setup.py       # ignore the `setup.py` file
  - data           # ignore all files in the `data` directory
  - .venv          # ignore all files in the `.venv` directory
  - tests          # ignore all python files in the `tests` directory
  - '*_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.

refactor

object: Refactor

Configuration of rules to include or skip.

Default

refactor:
  include: []
  skip: []
  rule_types:
    - refactoring
    - suggestion
    - comment
  python_version: '3.9'

Example

refactor:
  skip:
    - for-append-to-extend
    - raise-from-previous-error
  rule_types:
    - refactoring
    - suggestion
  python_version: 3.8

See Also

rules

list of Rule

A list of additional, customisable 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

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 skipped in the same way as refactorings - by adding low-code-quality to the list of skipped refactorings 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

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

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