Skip to content

Commit

Permalink
Update mypy and pytest documentation to refer to install_from_resolve…
Browse files Browse the repository at this point in the history
… (Cherry pick of #18791) (#18858)

Following from #18781, I found a few more places where the documentation
for tool configuration was out of date. Thanks!
  • Loading branch information
bweber-rebellion authored Apr 30, 2023
1 parent c12f37e commit 07da95c
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 18 deletions.
28 changes: 20 additions & 8 deletions docs/markdown/Python/python-goals/python-check-goal.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,14 +46,17 @@ config = "build-support/mypy.ini"

### Change the MyPy version

Use the `version` option in the `[mypy]` scope:
Use the `install_from_resolve` option in the `[mypy]` scope:

```toml pants.toml
[python.resolves]
mypy = "3rdparty/python/mypy.lock"

[mypy]
version = "mypy==0.910"
install_from_resolve = "mypy"
```

If you change this option, Pants's default lockfile for MyPy will not work. Either set the `lockfile` option to a custom path or `"<none>"` to opt out. See [Third-party dependencies](doc:python-third-party-dependencies#tool-lockfiles).
See [Lockfiles for tools](doc:python-lockfiles#lockfiles-for-tools).

### Incrementally adopt MyPy with `skip_mypy=True`

Expand Down Expand Up @@ -120,7 +123,7 @@ python_sources(name="lib")

### Third-party type stubs

You can install third-party type stubs (e.g. `types-requests`) like [normal Python requirements](doc:python-third-party-dependencies). Pants will infer a dependency on both the type stub and the actual dependency, e.g. both `types-requests` and `requests`, which you can confirm by running `pants dependencies path/to/f.py`.
You can install third-party type stubs (for example, `types-requests`) like [normal Python requirements](doc:python-third-party-dependencies). Pants will infer a dependency on both the type stub and the actual dependency, for example, both `types-requests` and `requests`, which you can confirm by running `pants dependencies path/to/f.py`.

You can also install the type stub via the option `[mypy].extra_type_stubs`, which ensures
the stubs are only used when running MyPy and are not included when, for example,
Expand All @@ -130,25 +133,34 @@ the stubs are only used when running MyPy and are not included when, for example
```toml pants.toml
[mypy]
extra_type_stubs = ["types-requests==2.25.12"]
# Set this to a path, then run `pants generate-lockfiles --resolve=mypy-extra-type-stubs`.
# Set this to a path, then run `pants generate-lockfiles --resolve=mypy-extra-type-stubs`.
extra_type_stubs_lockfile = "3rdparty/python/mypy_extra_type_stubs.lock
```
### Add a third-party plugin
Add the plugin to the `extra_requirements` option in the `[mypy]` scope, then update your `mypy.ini` to load the plugin:
Add the plugin to the `requirements` option in the `[mypy]` scope, and create a `requirements.txt` file for the version. Then specify the resolve that the requirements should be installed from:
```toml pants.toml
[python.resolves]
mypy = "3rdparty/python/mypy-lock.txt"

[mypy]
extra_requirements.add = ["pydantic==1.6.1"]
install_from_resolve = "mypy"
```
```Text mypy-requirements.txt
pydantic==1.6.1
```

Then update your `mypy.ini` to load the plugin:

```text mypy.ini
[mypy]
plugins =
pydantic.mypy
```

If you change this option, Pants's default lockfile for MyPy will not work. Either set the `lockfile` option to a custom path or `"<none>"` to opt out. See [Third-party dependencies](doc:python-third-party-dependencies#tool-lockfiles).
For more information, see [Lockfiles for tools](doc:python-lockfiles#lockfiles-for-tools).

For some plugins, like `django-stubs`, you may need to always load certain source files, such as a `settings.py` file. You can make sure that this source file is always used by hijacking the `source_plugins` option, which allows you to specify targets whose `sources` should always be used when running MyPy. See the below section for more information about source plugins.

Expand Down
25 changes: 15 additions & 10 deletions docs/markdown/Python/python-goals/python-test-goal.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,20 +33,25 @@ Examples
Pytest version and plugins
--------------------------

To change the Pytest version, set the `version` option in the `[pytest]` scope.

To install any [plugins](https://docs.pytest.org/en/latest/plugins.html), add the pip requirement string to `extra_requirements` in the `[pytest]` scope, like this:
To change the Pytest version, set the `install_from_resolve` option in the `[pytest]` scope. You may also add [plugins](https://docs.pytest.org/en/latest/plugins.html) including the plugins in the resolve:

```toml pants.toml
[python.resolves]
pytest = "3rdparty/python/pytest-lock.txt"

[pytest]
version = "pytest>=5.4"
extra_requirements.add = [
"pytest-django>=3.9.0,<4",
"pytest-rerunfailures==9.0",
]
install_from_resolve = "pytest"
```

Then, add a `requirements.txt` file specifying the version of `pytest` and other plugins:

```Text pytest-requirements.txt
pytest>=5.4
pytest-django>=3.9.0,<4
pytest-rerunfailures==9.0
```

If you change either `version` or `extra_requirements`, Pants's default lockfile for Pytest will not work. Either set the `lockfile` option to a custom path or `"<none>"` to opt out. See [Third-party dependencies](doc:python-third-party-dependencies#tool-lockfiles).
Finally, generate the relevant lockfile with `pants generate-lockfiles --resolve=pytest`. For more information, see [Lockfiles for tools](doc:python-lockfiles#lockfiles-for-tools).

Alternatively, if you only want to install the plugin for certain tests, you can add the plugin to the `dependencies` field of your `python_test` / `python_tests` target. See [Third-party dependencies](doc:python-third-party-dependencies) for how to install Python dependencies. For example:

Expand Down Expand Up @@ -524,7 +529,7 @@ Coverage will report data on any files encountered during the tests. You can fil
> By default, coverage.py will only report on files encountered during the tests' run. This means
> that your coverage score may be misleading; even with a score of 100%, you may have files
> without any tests.
>
>
> Instead, you can set `global_report = true`:
>
> ```toml pants.toml
Expand Down

0 comments on commit 07da95c

Please sign in to comment.