class IPython(PythonToolBase):
options_scope = "ipython"
help = "The IPython enhanced REPL (https://ipython.org/)."
default_version = "ipython==7.16.1" # The last version to support Python 3.6.
default_main = ConsoleScript("ipython")
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.subsystems",
"ipython.lock")
default_lockfile_path = "src/python/pants/backend/python/subsystems/ipython.lock"
default_lockfile_url = git_url(default_lockfile_path)
ignore_cwd = BoolOption(
"--ignore-cwd",
advanced=True,
default=True,
help=softwrap("""
Whether to tell IPython not to put the CWD on the import path.
Normally you want this to be True, so that imports come from the hermetic
environment Pants creates.
However IPython<7.13.0 doesn't support this option, so if you're using an earlier
version (e.g., because you have Python 2.7 code) then you will need to set this to False,
and you may have issues with imports from your CWD shading the hermetic environment.
"""),
)
class Black(PythonToolBase):
options_scope = "black"
help = "The Black Python code formatter (https://black.readthedocs.io/)."
# TODO: simplify `test_works_with_python39()` to stop using a VCS version.
default_version = "black==20.8b1"
default_extra_requirements = ["setuptools"]
default_main = ConsoleScript("black")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6"]
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=(
f"Don't use Black when running `{register.bootstrap.pants_bin_name} fmt` and "
f"`{register.bootstrap.pants_bin_name} lint`"
),
)
register(
"--args",
type=list,
member_type=shell_str,
help=(
"Arguments to pass directly to Black, e.g. "
f'`--{cls.options_scope}-args="--target-version=py37 --quiet"`'
),
)
register(
"--config",
type=file_option,
default=None,
advanced=True,
help="Path to Black's pyproject.toml config file",
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> Tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> Optional[str]:
return cast(Optional[str], self.options.config)
@property
def config_request(self) -> ConfigFilesRequest:
return ConfigFilesRequest(
specified=self.config,
check_content={"pyproject.toml": b"[tool.black]"},
option_name=f"[{self.options_scope}].config",
)
class Lambdex(PythonToolBase):
options_scope = "lambdex"
help = "A tool for turning .pex files into AWS Lambdas (https://github.com/wickman/lambdex)."
default_version = "lambdex==0.1.4"
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6"]
default_main = ConsoleScript("lambdex")
class Black(PythonToolBase):
options_scope = "black"
name = "Black"
help = "The Black Python code formatter (https://black.readthedocs.io/)."
default_version = "black==22.1.0"
default_main = ConsoleScript("black")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.black", "black.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/black/black.lock"
default_lockfile_url = git_url(default_lockfile_path)
default_extra_requirements = ['typing-extensions>=3.10.0.0; python_version < "3.10"']
skip = SkipOption("fmt", "lint")
args = ArgsListOption(example="--target-version=py37 --quiet")
export = ExportToolOption()
config = FileOption(
"--config",
default=None,
advanced=True,
help=lambda cls: softwrap(
f"""
Path to a TOML config file understood by Black
(https://github.com/psf/black#configuration-format).
Setting this option will disable `[{cls.options_scope}].config_discovery`. Use
this option if the config is located in a non-standard location.
"""
),
)
config_discovery = BoolOption(
"--config-discovery",
default=True,
advanced=True,
help=lambda cls: softwrap(
f"""
If true, Pants will include any relevant pyproject.toml config files during runs.
Use `[{cls.options_scope}].config` instead if your config is in a
non-standard location.
"""
),
)
def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
# Refer to https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#where-black-looks-for-the-file
# for how Black discovers config.
candidates = {os.path.join(d, "pyproject.toml"): b"[tool.black]" for d in ("", *dirs)}
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=self.config_discovery,
check_content=candidates,
)
class Isort(PythonToolBase):
options_scope = "isort"
help = "The Python import sorter tool (https://timothycrosley.github.io/isort/)."
default_version = "isort[pyproject]>=5.5.1,<5.6"
default_extra_requirements = ["setuptools"]
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6"]
default_main = ConsoleScript("isort")
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use isort when running `{register.bootstrap.pants_bin_name} fmt` and "
f"`{register.bootstrap.pants_bin_name} lint`."),
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to isort, e.g. "
f'`--{cls.options_scope}-args="--case-sensitive --trailing-comma"`.'
),
)
register(
"--config",
type=list,
member_type=file_option,
advanced=True,
help="Path to `isort.cfg` or alternative isort config file(s).",
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> Tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> Tuple[str, ...]:
return tuple(self.options.config)
@property
def config_request(self) -> ConfigFilesRequest:
return ConfigFilesRequest(
specified=self.config,
check_existence=[".isort.cfg"],
check_content={"pyproject.toml": b"[tool.isort]"},
option_name=f"[{self.options_scope}].config",
)
class Bandit(PythonToolBase):
options_scope = "bandit"
help = "A tool for finding security issues in Python code (https://bandit.readthedocs.io)."
default_version = "bandit>=1.6.2,<1.7"
# `setuptools<45` is for Python 2 support. `stevedore` is because the 3.0 release breaks Bandit.
default_extra_requirements = ["setuptools<45", "stevedore<3"]
default_main = ConsoleScript("bandit")
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
f"Don't use Bandit when running `{register.bootstrap.pants_bin_name} lint`",
)
register(
"--args",
type=list,
member_type=shell_str,
help=(
f"Arguments to pass directly to Bandit, e.g. "
f'`--{cls.options_scope}-args="--skip B101,B308 --confidence"`'
),
)
register(
"--config",
type=file_option,
default=None,
advanced=True,
help=("Path to a Bandit YAML config file "
"(https://bandit.readthedocs.io/en/latest/config.html)."),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> str | None:
return cast("str | None", self.options.config)
@property
def config_request(self) -> ConfigFilesRequest:
# Refer to https://bandit.readthedocs.io/en/latest/config.html. Note that there are no
# default locations for Bandit config files.
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"{self.options_scope}.config")
class Lambdex(PythonToolBase):
options_scope = "lambdex"
help = "A tool for turning .pex files into AWS Lambdas (https://github.com/wickman/lambdex)."
default_version = "lambdex==0.1.3"
# TODO(John Sirois): Remove when we can upgrade to a version of lambdex with
# https://github.com/wickman/lambdex/issues/6 fixed.
default_extra_requirements = ["setuptools>=50.3.0,<50.4"]
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.5"]
default_main = ConsoleScript("lambdex")
def test_pex_binary_validation() -> None:
def create_tgt(*, script: str | None = None, entry_point: str | None = None) -> PexBinary:
return PexBinary(
{PexScriptField.alias: script, PexEntryPointField.alias: entry_point},
Address("", target_name="t"),
)
with pytest.raises(InvalidTargetException):
create_tgt(script="foo", entry_point="foo")
assert create_tgt(script="foo")[PexScriptField].value == ConsoleScript("foo")
assert create_tgt(entry_point="foo")[PexEntryPointField].value == EntryPoint("foo")
def main(self) -> MainSpecification:
is_default_console_script = self.options.is_default("console_script")
is_default_entry_point = self.options.is_default("entry_point")
if not is_default_console_script and not is_default_entry_point:
raise OptionsError(
f"Both [{self.scope}].console-script={self.options.console_script} and "
f"[{self.scope}].entry-point={self.options.entry_point} are configured but these "
f"options are mutually exclusive. Please pick one.")
if not is_default_console_script:
return ConsoleScript(cast(str, self.options.console_script))
if not is_default_entry_point:
return EntryPoint.parse(cast(str, self.options.entry_point))
return self.default_main
class Flake8(PythonToolBase):
options_scope = "flake8"
help = "The Flake8 Python linter (https://flake8.pycqa.org/)."
default_version = "flake8>=3.7.9,<3.9"
default_extra_requirements = [
"setuptools<45; python_full_version == '2.7.*'",
"setuptools; python_version > '2.7'",
]
default_main = ConsoleScript("flake8")
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
f"Don't use Flake8 when running `{register.bootstrap.pants_bin_name} lint`",
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to Flake8, e.g. "
f'`--{cls.options_scope}-args="--ignore E123,W456 --enable-extensions H111"`'
),
)
register(
"--config",
type=file_option,
default=None,
advanced=True,
help="Path to `.flake8` or alternative Flake8 config file",
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> Tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> Optional[str]:
return cast(Optional[str], self.options.config)
class Lambdex(PythonToolBase):
options_scope = "lambdex"
help = "A tool for turning .pex files into Function-as-a-Service artifacts (https://github.com/pantsbuild/lambdex)."
default_version = "lambdex==0.1.6"
default_main = ConsoleScript("lambdex")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<3.10"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.subsystems",
"lambdex.lock")
default_lockfile_path = "src/python/pants/backend/python/subsystems/lambdex.lock"
default_lockfile_url = git_url(default_lockfile_path)
class PyUpgrade(PythonToolBase):
options_scope = "pyupgrade"
help = (
"Upgrade syntax for newer versions of the language (https://github.com/asottile/pyupgrade)."
)
default_version = "pyupgrade>=2.29.0,<2.30"
default_main = ConsoleScript("pyupgrade")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.pyupgrade",
"lockfile.txt")
default_lockfile_path = "src/python/pants/backend/python/lint/pyupgrade/lockfile.txt"
default_lockfile_url = git_url(default_lockfile_path)
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use pyupgrade when running `{register.bootstrap.pants_bin_name} fmt` and "
f"`{register.bootstrap.pants_bin_name} lint`."),
)
register(
"--args",
type=list,
default=[],
member_type=shell_str,
help=
(f"Arguments to pass directly to pyupgrade, e.g. "
f'`--{cls.options_scope}-args="--py39-plus --keep-runtime-typing"`'
),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> tuple[str, ...]:
return tuple(self.options.args)
class PyOxidizer(PythonToolBase):
options_scope = "pyoxidizer"
name = "PyOxidizer"
help = softwrap("""
The PyOxidizer utility for packaging Python code in a Rust binary
(https://pyoxidizer.readthedocs.io/en/stable/pyoxidizer.html).
Used with the `pyoxidizer_binary` target.
""")
default_version = "pyoxidizer==0.18.0"
default_main = ConsoleScript("pyoxidizer")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.8,<4"]
args = ArgsListOption(example="--release")
def main(self) -> MainSpecification:
is_default_console_script = self.options.is_default("console_script")
is_default_entry_point = self.options.is_default("entry_point")
if not is_default_console_script and not is_default_entry_point:
raise OptionsError(
softwrap(f"""
Both [{self.options_scope}].console-script={self.console_script} and
[{self.options_scope}].entry-point={self.entry_point} are configured
but these options are mutually exclusive. Please pick one.
"""))
if not is_default_console_script:
assert self.console_script is not None
return ConsoleScript(self.console_script)
if not is_default_entry_point:
assert self.entry_point is not None
return EntryPoint.parse(self.entry_point)
return self.default_main
class Autoflake(PythonToolBase):
options_scope = "autoflake"
name = "Autoflake"
help = "The Autoflake Python code formatter (https://github.com/myint/autoflake)."
default_version = "autoflake==1.4"
default_main = ConsoleScript("autoflake")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.autoflake", "autoflake.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/autoflake/autoflake.lock"
default_lockfile_url = git_url(default_lockfile_path)
skip = SkipOption("fmt", "lint")
args = ArgsListOption(example="--target-version=py37 --quiet")
class Docformatter(PythonToolBase):
options_scope = "docformatter"
help = "The Python docformatter tool (https://github.com/myint/docformatter)."
default_version = "docformatter>=1.4,<1.5"
default_main = ConsoleScript("docformatter")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.docformatter",
"lockfile.txt")
default_lockfile_path = "src/python/pants/backend/python/lint/docformatter/lockfile.txt"
default_lockfile_url = git_url(default_lockfile_path)
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use docformatter when running `{register.bootstrap.pants_bin_name} fmt` "
f"and `{register.bootstrap.pants_bin_name} lint`."),
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to docformatter, e.g. "
f'`--{cls.options_scope}-args="--wrap-summaries=100 --pre-summary-newline"`.'
),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> Tuple[str, ...]:
return tuple(self.options.args)
class Autoflake(PythonToolBase):
options_scope = "autoflake"
help = "The Autoflake Python code formatter (https://github.com/myint/autoflake)."
default_version = "autoflake==1.4"
default_main = ConsoleScript("autoflake")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.autoflake",
"lockfile.txt")
default_lockfile_path = "src/python/pants/backend/python/lint/autoflake/lockfile.txt"
default_lockfile_url = git_url(default_lockfile_path)
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use Autoflake when running `{register.bootstrap.pants_bin_name} fmt` and "
f"`{register.bootstrap.pants_bin_name} lint`"),
)
register(
"--args",
type=list,
member_type=shell_str,
help=(
"Arguments to pass directly to Autoflake, e.g. "
f'`--{cls.options_scope}-args="--target-version=py37 --quiet"`'
),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> tuple[str, ...]:
return tuple(self.options.args)
class Docformatter(PythonToolBase):
options_scope = "docformatter"
name = "docformatter"
help = "The Python docformatter tool (https://github.com/myint/docformatter)."
default_version = "docformatter>=1.4,<1.5"
default_main = ConsoleScript("docformatter")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.docformatter",
"docformatter.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/docformatter/docformatter.lock"
default_lockfile_url = git_url(default_lockfile_path)
skip = SkipOption("fmt", "lint")
args = ArgsListOption(example="--wrap-summaries=100 --pre-summary-newline")
class Bandit(PythonToolBase):
options_scope = "bandit"
name = "Bandit"
help = "A tool for finding security issues in Python code (https://bandit.readthedocs.io)."
# When upgrading, check if Bandit has started using PEP 517 (a `pyproject.toml` file). If so,
# remove `setuptools` from `default_extra_requirements`.
default_version = "bandit>=1.7.0,<1.8"
default_extra_requirements = [
"setuptools",
# GitPython 3.1.20 was yanked because it breaks Python 3.8+, but Poetry's lockfile
# generation still tries to use it. Upgrade this to the newest version once released or
# when switching away from Poetry.
"GitPython==3.1.18",
]
default_main = ConsoleScript("bandit")
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.bandit", "bandit.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/bandit/bandit.lock"
default_lockfile_url = git_url(default_lockfile_path)
skip = SkipOption("lint")
args = ArgsListOption(example="--skip B101,B308 --confidence")
config = FileOption(
"--config",
default=None,
advanced=True,
help=(
"Path to a Bandit YAML config file "
"(https://bandit.readthedocs.io/en/latest/config.html)."
),
)
@property
def config_request(self) -> ConfigFilesRequest:
# Refer to https://bandit.readthedocs.io/en/latest/config.html. Note that there are no
# default locations for Bandit config files.
return ConfigFilesRequest(
specified=self.config, specified_option_name=f"{self.options_scope}.config"
)
class PyUpgrade(PythonToolBase):
options_scope = "pyupgrade"
name = "pyupgrade"
help = (
"Upgrade syntax for newer versions of the language (https://github.com/asottile/pyupgrade)."
)
default_version = "pyupgrade>=2.31.0,<2.32"
default_main = ConsoleScript("pyupgrade")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.pyupgrade",
"pyupgrade.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/pyupgrade/pyupgrade.lock"
default_lockfile_url = git_url(default_lockfile_path)
skip = SkipOption("fmt", "lint")
args = ArgsListOption(example="--py39-plus --keep-runtime-typing")
class ClangFormat(PythonToolBase):
options_scope = "clang-format"
name = "ClangFormat"
help = softwrap(
"""
The clang-format utility for formatting C/C++ (and others) code
(https://clang.llvm.org/docs/ClangFormat.html). The clang-format binaries
are retrieved from PyPi (https://pypi.org/project/clang-format/).
"""
)
default_version = "clang-format==14.0.3"
default_main = ConsoleScript("clang-format")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
skip = SkipOption("fmt", "lint")
args = ArgsListOption(example="--version")
register_lockfile = True
default_lockfile_resource = ("pants.backend.cc.lint.clangformat", "clangformat.lock")
default_lockfile_path = "src/python/pants/backend/cc/lint/clangformat/clangformat.lock"
default_lockfile_url = git_url(default_lockfile_path)
export = ExportToolOption()
def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
"""clang-format will use the closest configuration file to the file currently being
formatted, so add all of them."""
config_files = (
".clang-format",
"_clang-format",
)
check_existence = [os.path.join(d, file) for file in config_files for d in ("", *dirs)]
return ConfigFilesRequest(
discovery=True,
check_existence=check_existence,
)
class Docformatter(PythonToolBase):
options_scope = "docformatter"
help = "The Python docformatter tool (https://github.com/myint/docformatter)."
default_version = "docformatter>=1.3.1,<1.4"
default_main = ConsoleScript("docformatter")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython==2.7.*", "CPython>=3.4,<3.9"]
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use docformatter when running `{register.bootstrap.pants_bin_name} fmt` "
f"and `{register.bootstrap.pants_bin_name} lint`."),
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to docformatter, e.g. "
f'`--{cls.options_scope}-args="--wrap-summaries=100 --pre-summary-newline"`.'
),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> Tuple[str, ...]:
return tuple(self.options.args)
class Isort(PythonToolBase):
options_scope = "isort"
help = "The Python import sorter tool (https://timothycrosley.github.io/isort/)."
default_version = "isort[pyproject]>=5.5.1,<5.6"
default_extra_requirements = ["setuptools"]
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6"]
default_main = ConsoleScript("isort")
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use isort when running `{register.bootstrap.pants_bin_name} fmt` and "
f"`{register.bootstrap.pants_bin_name} lint`."),
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to isort, e.g. "
f'`--{cls.options_scope}-args="--case-sensitive --trailing-comma"`.'
),
)
register(
"--config",
# TODO: Figure out how to deprecate this being a list in favor of a single string.
# Thanks to config autodiscovery, this option should only be used because you want
# Pants to explicitly set `--settings`, which only works w/ 1 config file.
# isort 4 users should instead use autodiscovery to support multiple config files.
# Deprecating this could be tricky, but should be possible thanks to the implicit
# add syntax.
#
# When deprecating, also deprecate the user manually setting `--settings` with
# `[isort].args`.
type=list,
member_type=file_option,
advanced=True,
help=
("Path to config file understood by isort "
"(https://pycqa.github.io/isort/docs/configuration/config_files/).\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
f"this option if the config is located in a non-standard location.\n\n"
"If using isort 5+ and you specify only 1 config file, Pants will configure "
"isort's argv to point to your config file."),
)
register(
"--config-discovery",
type=bool,
default=True,
advanced=True,
help=
("If true, Pants will include any relevant config files during "
"runs (`.isort.cfg`, `pyproject.toml`, `setup.cfg`, `tox.ini` and `.editorconfig`)."
f"\n\nUse `[{cls.options_scope}].config` instead if your config is in a "
f"non-standard location."),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> tuple[str, ...]:
return tuple(self.options.config)
def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
# Refer to https://pycqa.github.io/isort/docs/configuration/config_files/.
check_existence = []
check_content = {}
for d in ("", *dirs):
check_existence.append(os.path.join(d, ".isort.cfg"))
check_content.update({
os.path.join(d, "pyproject.toml"): b"[tool.isort]",
os.path.join(d, "setup.cfg"): b"[isort]",
os.path.join(d, "tox.ini"): b"[isort]",
os.path.join(d, ".editorconfig"): b"[*.py]",
})
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=cast(bool, self.options.config_discovery),
check_existence=check_existence,
check_content=check_content,
)
class CoverageSubsystem(PythonToolBase):
options_scope = "coverage-py"
help = "Configuration for Python test coverage measurement."
default_version = "coverage[toml]>=5.5,<5.6"
default_main = ConsoleScript("coverage")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.subsystems",
"coverage_py_lockfile.txt")
default_lockfile_path = "src/python/pants/backend/python/subsystems/coverage_py_lockfile.txt"
default_lockfile_url = git_url(default_lockfile_path)
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--filter",
type=list,
member_type=str,
default=None,
help=
("A list of Python modules or filesystem paths to use in the coverage report, e.g. "
"`['helloworld_test', 'helloworld/util/dirutil'].\n\nBoth modules and directory "
"paths are recursive: any submodules or child paths, respectively, will be "
"included.\n\nIf you leave this off, the coverage report will include every file "
"in the transitive closure of the address/file arguments; for example, `test ::` "
"will include every Python file in your project, whereas "
"`test project/app_test.py` will include `app_test.py` and any of its transitive "
"dependencies."),
)
register(
"--report",
type=list,
member_type=CoverageReportType,
default=[CoverageReportType.CONSOLE],
help="Which coverage report type(s) to emit.",
)
register(
"--output-dir",
type=str,
default=str(PurePath("dist", "coverage", "python")),
advanced=True,
help=
"Path to write the Pytest Coverage report to. Must be relative to build root.",
)
register(
"--config",
type=file_option,
default=None,
advanced=True,
help=
("Path to an INI or TOML config file understood by coverage.py "
"(https://coverage.readthedocs.io/en/stable/config.html).\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
f"this option if the config is located in a non-standard location."
),
)
register(
"--config-discovery",
type=bool,
default=True,
advanced=True,
help=
("If true, Pants will include any relevant config files during runs "
"(`.coveragerc`, `setup.cfg`, `tox.ini`, and `pyproject.toml`)."
f"\n\nUse `[{cls.options_scope}].config` instead if your config is in a "
f"non-standard location."),
)
register(
"--global-report",
type=bool,
default=False,
help=
("If true, Pants will generate a global coverage report.\n\nThe global report will "
"include all Python source files in the workspace and not just those depended on "
"by the tests that were run."),
)
register(
"--fail-under",
type=float,
default=None,
help=
("Fail if the total combined coverage percentage for all tests is less than this "
"number.\n\nUse this instead of setting fail_under in a coverage.py config file, "
"as the config will apply to each test separately, while you typically want this "
"to apply to the combined coverage for all tests run."
"\n\nNote that you must generate at least one (non-raw) coverage report for this "
"check to trigger.\n\nNote also that if you specify a non-integral value, you must "
"also set [report] precision properly in the coverage.py config file to make use "
"of the decimal places. See https://coverage.readthedocs.io/en/latest/config.html ."
),
)
@property
def filter(self) -> tuple[str, ...]:
return tuple(self.options.filter)
@property
def reports(self) -> tuple[CoverageReportType, ...]:
return tuple(self.options.report)
@property
def output_dir(self) -> PurePath:
return PurePath(self.options.output_dir)
@property
def config(self) -> str | None:
return cast("str | None", self.options.config)
@property
def config_request(self) -> ConfigFilesRequest:
# Refer to https://coverage.readthedocs.io/en/stable/config.html.
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=cast(bool, self.options.config_discovery),
check_existence=[".coveragerc"],
check_content={
"setup.cfg": b"[coverage:",
"tox.ini": b"[coverage:]",
"pyproject.toml": b"[tool.coverage",
},
)
@property
def global_report(self) -> bool:
return cast(bool, self.options.global_report)
@property
def fail_under(self) -> int:
return cast(int, self.options.fail_under)
class Yapf(PythonToolBase):
options_scope = "yapf"
help = "A formatter for Python files (https://github.com/google/yapf)."
default_version = "yapf==0.31.0"
default_extra_requirements = ["toml"]
default_main = ConsoleScript("yapf")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.6"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.yapf",
"lockfile.txt")
default_lockfile_path = "src/python/pants/backend/python/lint/yapf/lockfile.txt"
default_lockfile_url = git_url(default_lockfile_path)
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
(f"Don't use yapf when running `{register.bootstrap.pants_bin_name} fmt` and "
f"`{register.bootstrap.pants_bin_name} lint`."),
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to yapf, e.g. "
f'`--{cls.options_scope}-args="--no-local-style"`.\n\n'
"Certain arguments, specifically `--recursive`, `--in-place`, and "
"`--parallel`, will be ignored because Pants takes care of finding "
"all the relevant files and running the formatting in parallel."),
)
register(
"--config",
type=file_option,
default=None,
advanced=True,
help=
("Path to style file understood by yapf "
"(https://github.com/google/yapf#formatting-style/).\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
f"this option if the config is located in a non-standard location."
),
)
register(
"--config-discovery",
type=bool,
default=True,
advanced=True,
help=
("If true, Pants will include any relevant config files during "
"runs (`.style.yapf`, `pyproject.toml`, and `setup.cfg`)."
f"\n\nUse `[{cls.options_scope}].config` instead if your config is in a "
f"non-standard location."),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> str | None:
return cast("str | None", self.options.config)
def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
# Refer to https://github.com/google/yapf#formatting-style.
check_existence = []
check_content = {}
for d in ("", *dirs):
check_existence.append(os.path.join(d, ".yapfignore"))
check_content.update({
os.path.join(d, "pyproject.toml"): b"[tool.yapf",
os.path.join(d, "setup.cfg"): b"[yapf]",
os.path.join(d, ".style.yapf"): b"[style]",
})
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=cast(bool, self.options.config_discovery),
check_existence=check_existence,
check_content=check_content,
)
class Flake8(PythonToolBase):
options_scope = "flake8"
help = "The Flake8 Python linter (https://flake8.pycqa.org/)."
default_version = "flake8>=3.7.9,<3.9"
default_extra_requirements = [
"setuptools<45; python_full_version == '2.7.*'",
"setuptools; python_version > '2.7'",
]
default_main = ConsoleScript("flake8")
@classmethod
def register_options(cls, register):
super().register_options(register)
register(
"--skip",
type=bool,
default=False,
help=
f"Don't use Flake8 when running `{register.bootstrap.pants_bin_name} lint`",
)
register(
"--args",
type=list,
member_type=shell_str,
help=
("Arguments to pass directly to Flake8, e.g. "
f'`--{cls.options_scope}-args="--ignore E123,W456 --enable-extensions H111"`'
),
)
register(
"--config",
type=file_option,
default=None,
advanced=True,
help=
("Path to an INI config file understood by Flake8 "
"(https://flake8.pycqa.org/en/latest/user/configuration.html).\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
f"this option if the config is located in a non-standard location."
),
)
register(
"--config-discovery",
type=bool,
default=True,
advanced=True,
help=
("If true, Pants will include any relevant config files during "
"runs (`.flake8`, `flake8`, `setup.cfg`, and `tox.ini`)."
f"\n\nUse `[{cls.options_scope}].config` instead if your config is in a "
f"non-standard location."),
)
@property
def skip(self) -> bool:
return cast(bool, self.options.skip)
@property
def args(self) -> tuple[str, ...]:
return tuple(self.options.args)
@property
def config(self) -> str | None:
return cast("str | None", self.options.config)
@property
def config_request(self) -> ConfigFilesRequest:
# See https://flake8.pycqa.org/en/latest/user/configuration.html#configuration-locations
# for how Flake8 discovers config files.
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=cast(bool, self.options.config_discovery),
check_existence=["flake8", ".flake8"],
check_content={
"setup.cfg": b"[flake8]",
"tox.ini": b"[flake8]"
},
)
class TwineSubsystem(PythonToolBase):
options_scope = "twine"
name = "Twine"
help = "The utility for publishing Python distributions to PyPi and other Python repositories."
default_version = "twine>=3.7.1,<3.8"
default_main = ConsoleScript("twine")
# This explicit dependency resolves a weird behavior in poetry, where it would include a sys
# platform constraint on "Windows" when this was included transitively from the twine
# requirements.
# See: https://github.com/pantsbuild/pants/pull/13594#issuecomment-968154931
default_extra_requirements = ["colorama>=0.4.3"]
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.subsystems",
"twine.lock")
default_lockfile_path = "src/python/pants/backend/python/subsystems/twine.lock"
default_lockfile_url = git_url(default_lockfile_path)
skip = SkipOption("publish")
args = ArgsListOption(example="--skip-existing")
config = FileOption(
"--config",
default=None,
advanced=True,
help=lambda cls:
("Path to a .pypirc config file to use. "
"(https://packaging.python.org/specifications/pypirc/)\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
"this option if the config is located in a non-standard location."),
)
config_discovery = BoolOption(
"--config-discovery",
default=True,
advanced=True,
help=lambda cls:
("If true, Pants will include all relevant config files during runs "
"(`.pypirc`).\n\n"
f"Use `[{cls.options_scope}].config` instead if your config is in a "
"non-standard location."),
)
ca_certs_path = StrOption(
"--ca-certs-path",
advanced=True,
default="<inherit>",
help=
("Path to a file containing PEM-format CA certificates used for verifying secure "
"connections when publishing python distributions.\n\n"
'Uses the value from `[GLOBAL].ca_certs_path` by default. Set to `"<none>"` to '
"not use the default CA certificate."),
)
def config_request(self) -> ConfigFilesRequest:
# Refer to https://twine.readthedocs.io/en/latest/#configuration for how config files are
# discovered.
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=self.config_discovery,
check_existence=[".pypirc"],
)
def ca_certs_digest_request(
self, default_ca_certs_path: str | None) -> CreateDigest | None:
ca_certs_path: str | None = self.ca_certs_path
if ca_certs_path == "<inherit>":
ca_certs_path = default_ca_certs_path
if not ca_certs_path or ca_certs_path == "<none>":
return None
# The certs file will typically not be in the repo, so we can't digest it via a PathGlobs.
# Instead we manually create a FileContent for it.
ca_certs_content = Path(ca_certs_path).read_bytes()
chrooted_ca_certs_path = os.path.basename(ca_certs_path)
return CreateDigest((FileContent(chrooted_ca_certs_path,
ca_certs_content), ))
class MyPy(PythonToolBase):
options_scope = "mypy"
name = "MyPy"
help = "The MyPy Python type checker (http://mypy-lang.org/)."
default_version = "mypy==0.910"
default_main = ConsoleScript("mypy")
# See `mypy/rules.py`. We only use these default constraints in some situations.
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.typecheck.mypy",
"mypy.lock")
default_lockfile_path = "src/python/pants/backend/python/typecheck/mypy/mypy.lock"
default_lockfile_url = git_url(default_lockfile_path)
uses_requirements_from_source_plugins = True
skip = SkipOption("check")
args = ArgsListOption(example="--python-version 3.7 --disallow-any-expr")
config = FileOption(
"--config",
default=None,
advanced=True,
help=lambda cls:
("Path to a config file understood by MyPy "
"(https://mypy.readthedocs.io/en/stable/config_file.html).\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
f"this option if the config is located in a non-standard location."),
)
config_discovery = BoolOption(
"--config-discovery",
default=True,
advanced=True,
help=lambda cls:
("If true, Pants will include any relevant config files during "
"runs (`mypy.ini`, `.mypy.ini`, and `setup.cfg`)."
f"\n\nUse `[{cls.options_scope}].config` instead if your config is in a "
f"non-standard location."),
)
_source_plugins = TargetListOption(
"--source-plugins",
advanced=True,
help=
("An optional list of `python_sources` target addresses to load first-party "
"plugins.\n\n"
"You must also set `plugins = path.to.module` in your `mypy.ini`, and "
"set the `[mypy].config` option in your `pants.toml`.\n\n"
"To instead load third-party plugins, set the option `[mypy].extra_requirements` "
"and set the `plugins` option in `mypy.ini`."
"Tip: it's often helpful to define a dedicated 'resolve' via "
"`[python].resolves` for your MyPy plugins such as 'mypy-plugins' "
"so that the third-party requirements used by your plugin, like `mypy`, do not "
"mix with the rest of your project. Read that option's help message for more info "
"on resolves."),
)
extra_type_stubs = StrListOption(
"--extra-type-stubs",
advanced=True,
help=
("Extra type stub requirements to install when running MyPy.\n\n"
"Normally, type stubs can be installed as typical requirements, such as putting "
"them in `requirements.txt` or using a `python_requirement` target."
"Alternatively, you can use this option so that the dependencies are solely "
"used when running MyPy and are not runtime dependencies.\n\n"
"Expects a list of pip-style requirement strings, like "
"`['types-requests==2.25.9']`."),
)
@property
def config_request(self) -> ConfigFilesRequest:
# Refer to https://mypy.readthedocs.io/en/stable/config_file.html.
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"{self.options_scope}.config",
discovery=self.config_discovery,
check_existence=["mypy.ini", ".mypy.ini"],
check_content={
"setup.cfg": b"[mypy",
"pyproject.toml": b"[tool.mypy"
},
)
@property
def source_plugins(self) -> UnparsedAddressInputs:
return UnparsedAddressInputs(self._source_plugins, owning_address=None)
def check_and_warn_if_python_version_configured(
self, config: FileContent | None) -> bool:
"""Determine if we can dynamically set `--python-version` and warn if not."""
configured = []
if config and b"python_version" in config.content:
configured.append(
f"`python_version` in {config.path} (which is used because of either config "
"discovery or the `[mypy].config` option)")
if "--py2" in self.args:
configured.append("`--py2` in the `--mypy-args` option")
if any(arg.startswith("--python-version") for arg in self.args):
configured.append("`--python-version` in the `--mypy-args` option")
if configured:
formatted_configured = " and you set ".join(configured)
logger.warning(
f"You set {formatted_configured}. Normally, Pants would automatically set this "
"for you based on your code's interpreter constraints "
f"({doc_url('python-interpreter-compatibility')}). Instead, it will "
"use what you set.\n\n"
"(Automatically setting the option allows Pants to partition your targets by their "
"constraints, so that, for example, you can run MyPy on Python 2-only code and "
"Python 3-only code at the same time. This feature may no longer work.)"
)
return bool(configured)
class Pylint(PythonToolBase):
options_scope = "pylint"
name = "Pylint"
help = "The Pylint linter for Python code (https://www.pylint.org/)."
default_version = "pylint>=2.11.0,<2.12"
default_main = ConsoleScript("pylint")
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.pylint",
"pylint.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/pylint/pylint.lock"
default_lockfile_url = git_url(default_lockfile_path)
uses_requirements_from_source_plugins = True
skip = SkipOption("lint")
args = ArgsListOption(
example="--ignore=foo.py,bar.py --disable=C0330,W0311")
config = FileOption(
"--config",
default=None,
advanced=True,
help=lambda cls:
("Path to a config file understood by Pylint "
"(http://pylint.pycqa.org/en/latest/user_guide/run.html#command-line-options).\n\n"
f"Setting this option will disable `[{cls.options_scope}].config_discovery`. Use "
f"this option if the config is located in a non-standard location."),
)
config_discovery = BoolOption(
"--config-discovery",
default=True,
advanced=True,
help=lambda cls:
("If true, Pants will include any relevant config files during "
"runs (`.pylintrc`, `pylintrc`, `pyproject.toml`, and `setup.cfg`)."
f"\n\nUse `[{cls.options_scope}].config` instead if your config is in a "
f"non-standard location."),
)
_source_plugins = TargetListOption(
"--source-plugins",
advanced=True,
help=
("An optional list of `python_sources` target addresses to load first-party "
"plugins.\n\nYou must set the plugin's parent directory as a source root. For "
"example, if your plugin is at `build-support/pylint/custom_plugin.py`, add "
"'build-support/pylint' to `[source].root_patterns` in `pants.toml`. This is "
"necessary for Pants to know how to tell Pylint to discover your plugin. See "
f"{doc_url('source-roots')}\n\n"
f"You must also set `load-plugins=$module_name` in your Pylint config file.\n\n"
"While your plugin's code can depend on other first-party code and third-party "
"requirements, all first-party dependencies of the plugin must live in the same "
"directory or a subdirectory.\n\n"
"To instead load third-party plugins, set the "
"option `[pylint].extra_requirements` and set the `load-plugins` option in your "
"Pylint config.\n\n"
"Tip: it's often helpful to define a dedicated 'resolve' via "
"`[python].resolves` for your Pylint plugins such as 'pylint-plugins' "
"so that the third-party requirements used by your plugin, like `pylint`, do not "
"mix with the rest of your project. Read that option's help message for more info "
"on resolves."),
)
def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
# Refer to http://pylint.pycqa.org/en/latest/user_guide/run.html#command-line-options for
# how config files are discovered.
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=self.config_discovery,
check_existence=[
".pylinrc", *(os.path.join(d, "pylintrc") for d in ("", *dirs))
],
check_content={
"pyproject.toml": b"[tool.pylint]",
"setup.cfg": b"[pylint."
},
)
@property
def source_plugins(self) -> UnparsedAddressInputs:
return UnparsedAddressInputs(self._source_plugins, owning_address=None)
class Isort(PythonToolBase):
options_scope = "isort"
name = "isort"
help = "The Python import sorter tool (https://pycqa.github.io/isort/)."
default_version = "isort[pyproject,colors]>=5.9.3,<6.0"
default_main = ConsoleScript("isort")
register_interpreter_constraints = True
default_interpreter_constraints = ["CPython>=3.7,<4"]
register_lockfile = True
default_lockfile_resource = ("pants.backend.python.lint.isort",
"isort.lock")
default_lockfile_path = "src/python/pants/backend/python/lint/isort/isort.lock"
default_lockfile_url = git_url(default_lockfile_path)
skip = SkipOption("fmt", "lint")
args = ArgsListOption(example="--case-sensitive --trailing-comma")
export = ExportToolOption()
config = FileListOption(
"--config",
# TODO: Figure out how to deprecate this being a list in favor of a single string.
# Thanks to config autodiscovery, this option should only be used because you want
# Pants to explicitly set `--settings`, which only works w/ 1 config file.
# isort 4 users should instead use autodiscovery to support multiple config files.
# Deprecating this could be tricky, but should be possible thanks to the implicit
# add syntax.
#
# When deprecating, also deprecate the user manually setting `--settings` with
# `[isort].args`.
advanced=True,
help=lambda cls: softwrap(f"""
Path to config file understood by isort
(https://pycqa.github.io/isort/docs/configuration/config_files/).
Setting this option will disable `[{cls.options_scope}].config_discovery`. Use
this option if the config is located in a non-standard location.
If using isort 5+ and you specify only 1 config file, Pants will configure
isort's argv to point to your config file.
"""),
)
config_discovery = BoolOption(
"--config-discovery",
default=True,
advanced=True,
help=lambda cls: softwrap(f"""
If true, Pants will include any relevant config files during
runs (`.isort.cfg`, `pyproject.toml`, `setup.cfg`, `tox.ini` and `.editorconfig`).
Use `[{cls.options_scope}].config` instead if your config is in a
non-standard location.
"""),
)
def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
# Refer to https://pycqa.github.io/isort/docs/configuration/config_files/.
check_existence = []
check_content = {}
for d in ("", *dirs):
check_existence.append(os.path.join(d, ".isort.cfg"))
check_content.update({
os.path.join(d, "pyproject.toml"): b"[tool.isort]",
os.path.join(d, "setup.cfg"): b"[isort]",
os.path.join(d, "tox.ini"): b"[isort]",
os.path.join(d, ".editorconfig"): b"[*.py]",
})
return ConfigFilesRequest(
specified=self.config,
specified_option_name=f"[{self.options_scope}].config",
discovery=self.config_discovery,
check_existence=check_existence,
check_content=check_content,
)
