Configuration

The preferred way to configure pycroscope is using the pyproject.toml configuration file:

[tool.pycroscope]
# Paths pycroscope should check by default
paths = ["my_module/"]
# Paths to import from
import_paths = ["."]

# Enable or disable some checks
possibly_undefined_name = true
duplicate_dict_key = false

# Output style for reported errors ("detailed" or "concise")
output_format = "concise"

# But re-enable it for a specific module
[[tool.pycroscope.overrides]]
module = "my_module.submodule"
duplicate_dict_key = true

It is recommended to always set the following configuration options:

  • paths: A list of paths (relative to the location of the pyproject.toml file) that pycroscope should check by default.

  • import_paths: A list of paths (also relative to the configuration file) that pycroscope should use as roots when trying to import files it is checking. If this is not set, pycroscope will use entries from sys.path, which may produce unexpected results.

Other supported configuration options are listed below.

Almost all configuration options can be overridden for individual modules or packages. To set a module-specific configuration, add an entry to the tool.pycroscope.overrides list (as in the example above), and set the module key to the fully qualified name of the module or package.

To see the current value of all configuration options, pass the --display-options command-line option:

$ python -m pycroscope --config-file pyproject.toml --display-options
Options:
    add_import (value: True)
    ...

To extend another configuration file, use the extend_config key:

[tool.pycroscope]
extend_config = "../path/to/other/pyproject.toml"

Options set in the included config file have lower priority.

To use a local typeshed checkout instead of typeshed-client’s bundled copy, set typeshed_path:

[tool.pycroscope]
typeshed_path = "../typeshed"

Most configuration options can also be set on the command line. Run pycroscope --help to see these options.

Additional configuration options

  • additional_base_providers (default: ()): Sets functions that provide additional (virtual) base classes for a class. These are used for the purpose of type checking. For example, if the following is configured to be used as a base provider: def provider(typ: type) -> Set[type]: if typ is B: return {A} return set() Then to the type checker B is a subclass of A.

  • allow_duplicate_values (default: []): For subclasses of these classes, we do not error if multiple attributes have the same value. This overrides CheckForDuplicateValues.

  • async_proxy_decorators (default: []): Decorators that are equivalent to asynq.async_proxy.

  • asynq_decorators (default: []): Decorators that are equivalent to asynq.asynq.

  • check_for_duplicate_values (default: [<enum 'Enum'>]): For subclasses of these classes, we error if multiple attributes have the same value. This is used for the duplicate_enum check.

  • class_attribute_transformers (default: []): Transform certain class attributes. Instances of this option are callables that take an object found among a class’s attributes and return either None (if the value should not be transformed) or a pair of a get and set type. To disallow setting the value, return pycroscope.value.NO_RETURN_VALUE. If multiple transformers match an object, the first one is used.

  • classes_checked_for_asynq (default: ()): Normally, asynq calls to asynq functions are only enforced in functions that are already asynq. In subclasses of classes listed here, all asynq functions must be called asynq.

  • classes_safe_to_instantiate (default: [<class 'pycroscope.extensions.CustomCheck'>, <class 'pycroscope.value.Value'>, <class 'pycroscope.value.Extension'>, <class 'pycroscope.stacked_scopes.Composite'>, <class 'pycroscope.value.KVPair'>, <class 'pycroscope.value.TypedDictEntry'>, <class 'pycroscope.value.Predicate'>, <class 'range'>, <class 'tuple'>, <class 'typing.TypeVar'>, <class 'typing.TypeVarTuple'>, <class 'typing.ParamSpec'>, <class 'typing.NewType'>, <class 'typing.TypeAliasType'>, <class 'typing.TypeVar'>, <class 'typing.TypeVarTuple'>, <class 'typing.ParamSpec'>, <class 'typing.NewType'>, <class 'typing.TypeAliasType'>, <class '_py_warnings.deprecated'>]): We will instantiate instances of these classes if we can infer the value of all of their arguments. This is useful mostly for classes that are commonly instantiated with static arguments.

  • comprehension_length_inference_limit (default: 25): If we iterate over something longer than this, we don’t try to infer precise types for comprehensions. Increasing this can hurt performance.

  • constructor_hooks (default: ()): Customize the constructor signature for a class. These hooks may return either a function that pycroscope will use the signature of, an inspect Signature object, or a pycroscope Signature object. The function or signature should take a self parameter.

  • disallow_calls_to_dunders (default: ()): Set of dunder methods (e.g., ‘{”lshift”}’) that pycroscope is not allowed to call on objects.

  • disallowed_imports (default: ()): List of imports that will trigger an error. Entries may be top-level modules (e.g., “os”) or dotted submodule paths (e.g., “os.path”).

  • enforce_no_unused (default: False; global): If True, an error is raised when pycroscope finds any unused objects.

  • enforce_no_unused_attributes (default: False; global): If True, an error is raised when pycroscope finds any unused class attributes.

  • enforce_no_unused_call_patterns (default: False; global): If True, an error is raised when pycroscope finds unused callable patterns. This check is experimental and still has various known bugs.

  • extra_builtins (default: ['__IPYTHON__']): Even if these variables are undefined, no errors are shown.

  • for_loop_always_entered (default: False): If True, we assume that for loops are always entered at least once, which affects the potentially_undefined_name check. This will miss some bugs but also remove some annoying false positives.

  • functions_safe_to_call (default: [<built-in function sorted>, <function namedtuple at 0x7655a621fb60>, <function NamedTuple at 0x7655a5cec670>, <function TypedDict at 0x7655a5cec930>, <function dataclass_transform at 0x7655a5cefab0>, <function NamedTuple at 0x7655a5cec670>, typing_extensions.TypedDict, <function dataclass_transform at 0x7655a5cefab0>]): We will instantiate instances of these classes if we can infer the value of all of their arguments. This is useful mostly for classes that are commonly instantiated with static arguments.

  • ignore_none_attributes (default: False): If True, we ignore None when type checking attribute access on a Union type.

  • ignore_unused (default: ()): If any of these functions returns True, we will exclude this object from the unused object check. The arguments are the module the object was found in, the attribute used to access it, and the object itself.

  • ignore_unused_attribute_predicates (default: []; config-file only): Predicates that suppress specific unused class-attribute reports. Each predicate receives the declaring class and attribute name. If it returns True, the unused-attribute report is skipped.

  • ignored_callees (default: [call, <class 'unittest.mock.MagicMock'>, <class 'unittest.mock.Mock'>]): Calls to these aren’t checked for argument validity.

  • ignored_end_of_reference (default: ['call_count', 'assert_has_calls', 'reset_mock', 'called', 'assert_called_once', 'assert_called_once_with', 'assert_called_with', 'count', 'assert_any_call', 'assert_not_called']): When these attributes are accessed but they don’t exist, the error is ignored.

  • ignored_for_incompatible_overrides (default: ['__init__', '__eq__', '__ne__']): These attributes are not checked for incompatible overrides.

  • ignored_paths (default: (); config-file only): Attribute accesses on these do not result in errors.

  • ignored_types_for_attribute_checking (default: [<class 'object'>, <class 'abc.ABC'>]): Used in the check for object attributes that are accessed but not set. In general, the check will only alert about attributes that don’t exist when it has visited all the base classes of the class with the possibly missing attribute. However, these classes are never going to be visited (since they’re builtin), but they don’t set any attributes that we rely on.

  • ignored_unused_attribute_paths (default: []): Fully-qualified attribute paths to suppress in unused-attribute results. Each entry should look like package.module.ClassName.attribute.

  • ignored_unused_attributes (default: ['_abc_cache', '_abc_negative_cache', '__abstractmethods__', '_abc_negative_cache_version', '_abc_registry', '__module__', '__doc__', '__init__', '__dict__', '__weakref__', '__enter__', '__exit__', '__metaclass__']): When these attributes are unused, they are not listed as such by the unused attribute finder.

  • ignored_unused_class_attributes (default: []; config-file only): List of pairs of (class, set of attribute names). When these attribute names are seen as unused on a child or base class of the class, they are not listed.

  • known_attribute_hook (default: [<function _default_transformer at 0x7655a3d64a90>]): Allows hooking into the inferred value for an attribute on a literal.

  • known_signatures (default: []): Provide hardcoded signatures (and potentially impl functions) for particular objects. Each entry in the list must be a function that takes an ArgSpecCache instance and returns a mapping from Python object to pycroscope.signature.Signature.

  • maximum_positional_args (default: 10): If calls have more than this many positional arguments, attempt to turn them into keyword arguments.

  • methods_not_checked_for_asynq (default: ()): Async batching in these component methods isn’t checked even when they exist on a class in ClassesCheckedForAsynq.

  • non_asynq_modules (default: ['multiprocessing']): We ignore _async methods in these modules.

  • output_format (default: 'detailed'): Output format for reported errors ("detailed" or "concise").

  • partial_call_decorators (default: [<class 'property'>]): Decorators that should use partial-call semantics when applied.

  • reexport_config (default: (); global): Callbacks that can configure the ImplicitReexportTracker, usually by setting names as explicitly exported.

  • safe_decorators_for_nested_functions (default: [<class 'classmethod'>, <class 'staticmethod'>]): These decorators can safely be applied to nested functions.

  • stub_path (default: ()): Extra paths in which to look for stubs.

  • transform_globals (default: [<function _anything_to_any at 0x7655a34b2140>]): Transform global variables.

  • typeshed_path (default: None; global): Path to a typeshed checkout to use instead of typeshed_client’s bundled copy. The path may either contain VERSIONS directly or have a stdlib/ subdirectory containing VERSIONS.

  • unimportable_modules (default: []): Do not attempt to import these modules if they are imported within a function.

  • union_simplification_limit (default: 100): We may simplify unions with more than this many values.

  • unwrap_class (default: ()): Provides functions that can unwrap decorated classes. For example, if your codebase commonly uses a decorator that wraps classes in a Wrapper subclass with a .wrapped attribute, you may define an unwrapper like this: def unwrap_class(typ: type) -> type: if issubclass(typ, Wrapper) and typ is not Wrapper: return typ.wrapped return typ

  • variable_name_values (default: (); global): List of pycroscope.value.VariableNameValue instances that create pseudo-types associated with certain variable names.