Skip to main content
Version: 2.17 (deprecated)

python-infer

Options controlling which dependencies will be inferred for Python targets.

Backend: pants.backend.python

Config section: [python-infer]

Basic options​

ambiguity_resolution​

--python-infer-ambiguity-resolution=<AmbiguityResolution>
PANTS_PYTHON_INFER_AMBIGUITY_RESOLUTION
pants.toml
[python-infer]
ambiguity_resolution = <AmbiguityResolution>
one of: none, by_source_root
default: none

When multiple sources provide the same symbol, how to choose the provider to use.

none: Do not attempt to resolve this ambiguity. No dependency will be inferred, and warnings will be logged.

by_source_root: Choose the provider with the closest common ancestor to the consumer's source root. If the provider is under the same source root then this will be the source root itself. This is useful when multiple projects in different source roots provide the same symbols (because of repeated first-party module paths or overlapping requirements.txt) and you want to resolve the ambiguity locally in each project.

assets​

--[no-]python-infer-assets
PANTS_PYTHON_INFER_ASSETS
pants.toml
[python-infer]
assets = <bool>
default: False

Infer a target's asset dependencies based on strings that look like Posix filepaths, such as those given to open or pkgutil.get_data.

To ignore a false positive, you can either put # pants: no-infer-dep on the line of the string or put !{bad_address} in the dependencies field of your target.

assets_min_slashes​

--python-infer-assets-min-slashes=<int>
PANTS_PYTHON_INFER_ASSETS_MIN_SLASHES
pants.toml
[python-infer]
assets_min_slashes = <int>
default: 1

If --assets is True, treat valid-looking strings with at least this many forward slash characters as potential assets. E.g. 'data/databases/prod.db' will be treated as a potential candidate if this option is set to 2 but not to 3.

conftests​

--[no-]python-infer-conftests
PANTS_PYTHON_INFER_CONFTESTS
pants.toml
[python-infer]
conftests = <bool>
default: True

Infer a test target's dependencies on any conftest.py files in the current directory and ancestor directories.

entry_points​

--[no-]python-infer-entry-points
PANTS_PYTHON_INFER_ENTRY_POINTS
pants.toml
[python-infer]
entry_points = <bool>
default: True

Infer dependencies on targets' entry points, e.g. pex_binary's entry_point field, python_awslambda's handler field and python_distribution's entry_points field.

ignored_unowned_imports​

--python-infer-ignored-unowned-imports="['<str>', '<str>', ...]"
PANTS_PYTHON_INFER_IGNORED_UNOWNED_IMPORTS
pants.toml
[python-infer]
ignored_unowned_imports = [
    '<str>',
    '<str>',
    ...,
]
default: []

Unowned imports that should be ignored.

        If there are any unowned import statements and adding the `# pants: no-infer-dep`
        to the lines of the import is impractical, you can instead provide a list of imports
        that Pants should ignore. You can declare a specific import or a path to a package
        if you would like any of the package imports to be ignored.

        For example, you could ignore all the following imports of the code

            ```
            import src.generated.app
            from src.generated.app import load
            from src.generated.app import start
            from src.generated.client import connect
            ```

        by setting `ignored-unowned-imports=["src.generated.app", "src.generated.client.connect"]`.

imports​

--[no-]python-infer-imports
PANTS_PYTHON_INFER_IMPORTS
pants.toml
[python-infer]
imports = <bool>
default: True

Infer a target's imported dependencies by parsing import statements from sources.

To ignore a false positive, you can either put # pants: no-infer-dep on the line of the import or put !{bad_address} in the dependencies field of your target.

init_files​

--python-infer-init-files=<InitFilesInference>
PANTS_PYTHON_INFER_INIT_FILES
pants.toml
[python-infer]
init_files = <InitFilesInference>
one of: always, content_only, never
default: content_only

Infer a target's dependencies on any __init__.py files in the packages it is located in (recursively upward in the directory structure).

Even if this is set to never or content_only, Pants will still always include any ancestor __init__.py files in the sandbox. Only, they will not be "proper" dependencies, e.g. they will not show up in pants dependencies and their own dependencies will not be used.

By default, Pants only adds a "proper" dependency if there is content in the __init__.py file. This makes sure that dependencies are added when likely necessary to build, while also avoiding adding unnecessary dependencies. While accurate, those unnecessary dependencies can complicate setting metadata like the interpreter_constraints and resolve fields.

string_imports​

--[no-]python-infer-string-imports
PANTS_PYTHON_INFER_STRING_IMPORTS
pants.toml
[python-infer]
string_imports = <bool>
default: False

Infer a target's dependencies based on strings that look like dynamic dependencies, such as Django settings files expressing dependencies as strings.

To ignore a false positive, you can either put # pants: no-infer-dep on the line of the string or put !{bad_address} in the dependencies field of your target.

string_imports_min_dots​

--python-infer-string-imports-min-dots=<int>
PANTS_PYTHON_INFER_STRING_IMPORTS_MIN_DOTS
pants.toml
[python-infer]
string_imports_min_dots = <int>
default: 2

If --string-imports is True, treat valid-looking strings with at least this many dots in them as potential dynamic dependencies. E.g., 'foo.bar.Baz' will be treated as a potential dependency if this option is set to 2 but not if set to 3.

unowned_dependency_behavior​

--python-infer-unowned-dependency-behavior=<UnownedDependencyUsage>
PANTS_PYTHON_INFER_UNOWNED_DEPENDENCY_BEHAVIOR
pants.toml
[python-infer]
unowned_dependency_behavior = <UnownedDependencyUsage>
one of: error, warning, ignore
default: warning

How to handle imports that don't have an inferrable owner.

Usually when an import cannot be inferred, it represents an issue like Pants not being properly configured, e.g. targets not set up. Often, missing dependencies will result in confusing runtime errors like ModuleNotFoundError, so this option can be helpful to error more eagerly.

To ignore any false positives, either add # pants: no-infer-dep to the line of the import or put the import inside a try: except ImportError: block.

use_rust_parser​

--[no-]python-infer-use-rust-parser
PANTS_PYTHON_INFER_USE_RUST_PARSER
pants.toml
[python-infer]
use_rust_parser = <bool>
default: False

Use the new Rust-based, multithreaded, in-process dependency parser.

Pants 2.17 introduced a new paradigm to dependency parsing for Python by leveraging a Rust-based parser that's called in the same process as Pants itself, instead of farming out to one-python-process-per-file.

As a result of the switch, cold-cache performance improved by a factor of about 12x, while hot-cache had no difference. Additionally, Pants can now infer dependencies from Python scripts with syntax errors.

However, since this parser is completely different it has the potential of introducing differences in dependency inference. Although the Pants suite of tests only identified differences when using the # pants: no-infer-dep pragma, and string-based imports/assets, Out of an abundance of caution, this is behind a feature flag that will eventually be on-by-default then removed.

It is recommended that you run pants peek :: > before.json and then pants --python-infer-use-rust-parser peek :: > after.json and compare the two results. If all looks good, set use_rust_parser in [python-infer] in pants.toml. If you think there's a bug please file an issue: https://github.com/pantsbuild/pants/issues/new/choose.

Advanced options​

None

Deprecated options​

None

None