You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Remove references to {envbindir}
tox prepends the {env_bin_dir} to $PATH, so commands
will default to using the virtual environment first.
See: https://tox.wiki/en/4.4.11/config.html#commands
One of tox's core maintainers also discourages its use:
tox-dev/tox#2909 (comment)
* refactor: Write paths relative to git root, instead of package dir
Uses an inline plugin (toxfile.py) to make a computed config
value avaiable to tox environments.
* refactor: Rename {toxinidir} to {tox_root}
{toxinidir} is an alias for {tox_root}, but {tox_root} is:
* More clear: {tox_root} isn't necessarily where the ini file is
* Shorter
* refactor: Flatten some commands that are no longer super long
* refactor: Make a pytest section
* refactor: Remove `changedir = {tox_root}`
This is the default behavior, see:
https://tox.wiki/en/4.4.11/config.html#change_dir-external
* fix: {distdir} is deprecated
See: https://tox.wiki/en/latest/upgrading.html#removed-tox-ini-keys
* fix: Remove --ignore-installed from pip command
--ignore-installed can break a python installation if multiple
conflicting versions of a package are installed
* refactor: Add descriptions to all tox environments
* fix: Remove ineffective platform config
platform = linux: linux
macos: darwin
windows: win32
Setting the above in the base environment has no effect:
* None of the environments have {linux,macos,windows} in the
name, so the platform config is always empty.
* chore: Bump `tox` to `>4.4.11` and no longer install `tox-monorepo`
tox4 natively solves what `tox-monorepo` was written to solve:
`--root` lets you set `toxinidir` independently of the config
file in use.
4.4.11 was chosen as the cutoff since it was the first release to
include a fix to `--root` that prevented `{work_dir}` from being
changed when `{toxinidir}` was changed by `--root`.
`tox-monorepo` should no longer be needed
* docs: Update CONTRIBUTING.md to use tox 4 commands
* References to tox-monorepo were removed
* Replaced discussion of `tox -l` with tox4's `tox list`
* Updated examples to use `--root`
* docs: Make `azure-media-{videoanalyzer,analytics}-edge`'s DevTips.md point to CONTRIBUTING.md for tox
* docs: Remove remaining references to tox-monorepo
* doc: Use `--root` throughout documentation
* engsys: Make tox_harness set `{toxinidir}` when invoking tox
* engsys: Set required tox version in config
* docs: Use the new url for tox docs
* docs: Add a callout that TOX_* environment variables control defaults
* TOX_CONFIG_DIR can be used to permanently set --conf
* TOX_ROOT_DIR can be used to permanently set --root
* update packaging requirement everywhere it is used.
* fix cspell
* docs: Use `tox run` syntax throughout documentation
* engsys: Use `tox run` syntax in tox_harness.py
* docs: Replace – (U+2013 : EN DASH) with - (ASCII code 45)
* update pytest requirements + coverage.
* update virtualenv
* more conflicts resolved
* bringing in urllib3 restriction, aligning ci_tools.txt with test_tools.txt
* check_call requires a list of type string. if we append ['blah', 'blah'] we are actually inserting another array. just use regular array concatenation
* engsys: Tox uses `run` for serial execution and `run-parallel` for parallel`
* azure-core: Use `@pytest_asyncio.fixture` to mark an asyncio fixture
See https://pytest-asyncio.readthedocs.io/en/latest/concepts.html#strict-mode
* pin coverage to newer version with no conflicts
* identify issue with missing code coverage being caused by wrongly named namespace (Azure#30344)
* remove fix of dotfile!
* apply black formatting to resolve failing analyze step
* tox installing tox. probably not a good thing :)
* engsys: Remove `tox` from `azure-media-analytics-edge` dev_requirements
* align regression version of ci/test_tools.txt
* new coverage format requires that the package sources be present when combining .coverage files. amend our tox tree cleanup to exclude the whl directory when running coverage.
* ensure that missing hidden folder can't break cleanup operation
* ensure coverage isn't generated on whl_no_aio
* ensure that coverage is generated without wonky package paths
---------
Co-authored-by: scbedd <45376673+scbedd@users.noreply.github.com>
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+49-27Lines changed: 49 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,13 +11,13 @@ If you want to contribute to a file that is generated (header contains `Code gen
11
11
12
12
The Azure SDK team's Python CI leverages the tool `tox` to distribute tests to virtual environments, handle test dependency installation, and coordinate tooling reporting during PR/CI builds. This means that a dev working locally can reproduce _exactly_ what the build machine is doing.
13
13
14
-
[A Brief Overview of Tox](https://tox.readthedocs.io/en/latest/)
14
+
[A Brief Overview of Tox](https://tox.wiki/en/latest/)
15
15
16
16
#### A Monorepo and Tox in Harmony
17
17
18
18
Traditionally, the `tox.ini` file for a package sits _alongside the setup.py_ in source code. The `azure-sdk-for-python` necessarily does not adhere to this policy. There are over one-hundred packages contained here-in. That's a lot of `tox.ini` files to maintain!
19
19
20
-
Instead, the CI system leverages an tox plugin called `tox-monorepo`. This plugin allows `tox` to act as if the `tox.ini` is located in whatever directory you executed tox in!
20
+
Instead, the CI system leverages the `--root` argument which is new to `tox4`. The `--root` argument allows `tox` to act as if the `tox.ini` is located in whatever directory you specify!
21
21
22
22
#### Tox Environments
23
23
@@ -32,40 +32,62 @@ Internally `tox` leverages `virtualenv` to create each test environment's virtua
32
32
33
33
This means that once the `tox` workflow is in place, all tests will be executed _within a virtual environment._
34
34
35
-
To see the default environments from a specific `tox.ini` file, use the command `tox -l` in the same directory as the file itself.
36
-
37
-
> sdk-for-python/eng/tox> tox -l
38
-
39
-
```
40
-
41
-
whl
42
-
sdist
43
-
35
+
You can use the command `tox list` to list all the environments provided by a `tox.ini` file. You can either use that command in the
36
+
same directory as the file itself, or use the `--conf` argument to specify the path to it directly.
37
+
38
+
39
+
Sample output of `tox list`:
40
+
41
+
```
42
+
sdk-for-python/eng/tox> tox list
43
+
default environments:
44
+
whl -> Builds a wheel and runs tests
45
+
sdist -> Builds a source distribution and runs tests
46
+
47
+
additional environments:
48
+
pylint -> Lints a package with a pinned version of pylint
49
+
next-pylint -> Lints a package with pylint (version 2.15.8)
50
+
mypy -> Typechecks a package with mypy (version 1.0.0)
51
+
next-mypy -> Typechecks a package with the latest version of mypy
52
+
pyright -> Typechecks a package with pyright (version 1.1.287)
53
+
next-pyright -> Typechecks a package with the latest version of static type-checker pyright
54
+
verifytypes -> Verifies the "type completeness" of a package with pyright
55
+
whl_no_aio -> Builds a wheel without aio and runs tests
56
+
develop -> Tests a package
57
+
sphinx -> Builds a package's documentation with sphinx
58
+
depends -> Ensures all modules in a target package can be successfully imported
59
+
verifywhl -> Verify directories included in whl and contents in manifest file
60
+
verifysdist -> Verify directories included in sdist and contents in manifest file. Also ensures that py.typed configuration is correct within the setup.py
61
+
devtest -> Tests a package against dependencies installed from a dev index
62
+
latestdependency -> Tests a package against the released, upper-bound versions of its azure dependencies
63
+
mindependency -> Tests a package against the released, lower-bound versions of its azure dependencies
64
+
apistub -> Generate an api stub of a package ( for https://apiview.dev )
65
+
bandit -> Runs bandit, a tool to find common security issues, against a package
66
+
samples -> Runs a package's samples
67
+
breaking -> Runs the breaking changes checker against a package
44
68
```
45
69
46
-
Unfortunately, the command `tox -l` only returns the _default_ test builds. The common `tox.ini` file also supports `pylint` and `mypy` environments.
47
-
48
70
### Example Usage of the common Azure SDK For Python `tox.ini`
49
71
50
72
Basic usage of `tox` within this monorepo is:
51
73
52
-
1.`pip install tox<4 tox-monorepo`
53
-
2.`cd` to target package folder
54
-
3. run `tox -c path/to/tox.ini`
74
+
1.`pip install tox<5`
75
+
2. Run `tox run -e ENV_NAME -c path/to/tox.ini --root path/to/python_package`
76
+
***Note**: You can use environment variables to provide defaults for tox config values
77
+
* With `TOX_CONFIG_FILE` set to the absolute path of `tox.ini`, you can avoid needing `-c path/to/tox.ini` in your tox invocations
78
+
* With `TOX_ROOT_DIR` set to the absolute path to your python package, you can avoid needing `--root path/to/python_package`
55
79
56
80
The common `tox.ini` location is `eng/tox/tox.ini` within the repository.
57
81
58
82
If at any time you want to blow away the tox created virtual environments and start over, simply append `-r` to any tox invocation!
59
83
60
84
#### Example `azure-core` mypy
61
85
62
-
1.`cd` to `sdk/core/azure-core`
63
-
2. Run `tox -e mypy -c ../../../eng/tox/tox.ini`
86
+
1. Run `tox run -e mypy -c ../../../eng/tox/tox.ini --root sdk/core/azure-core`
64
87
65
88
#### Example `azure-storage-blob` tests
66
89
67
-
1.`cd` to `sdk/storage/azure-storage-blob`
68
-
2. Execute `tox -c ../../../eng/tox/tox.ini`
90
+
2. Execute `tox run -c ../../../eng/tox/tox.ini --root sdk/storage/azure-storage-blob`
69
91
70
92
Note that we didn't provide an `environment` argument for this example. Reason here is that the _default_ environment selected by our common `tox.ini` file is one that runs `pytest`.
71
93
@@ -75,7 +97,7 @@ Used for test execution across the spectrum of all the platforms we want to supp
75
97
* Installs the wheel, runs tests using the wheel
76
98
77
99
```
78
-
\> tox -e whl -c <path to tox.ini>
100
+
\> tox run -e whl -c <path to tox.ini> --root <path to python package>
79
101
80
102
```
81
103
@@ -87,30 +109,30 @@ Used for the local dev loop.
87
109
88
110
```
89
111
90
-
\> tox -e sdist -c <path to tox.ini>
112
+
\> tox run -e sdist -c <path to tox.ini> --root <path to python package>
91
113
92
114
```
93
115
94
116
#### `pylint` environment
95
117
Pylint install and run.
96
118
97
119
```
98
-
\> tox -e pylint -c <path to tox.ini>
120
+
\> tox run -e pylint -c <path to tox.ini> --root <path to python package>
99
121
```
100
122
101
123
102
124
#### `mypy` environment
103
125
Mypy install and run.
104
126
105
127
```
106
-
\> tox -e mypy -c <path to tox.ini>
128
+
\> tox run -e mypy -c <path to tox.ini> --root <path to python package>
107
129
```
108
130
109
131
#### `sphinx` environment
110
132
Generate sphinx doc for this package.
111
133
112
134
```
113
-
\> tox -e sphinx -c <path to tox.ini>
135
+
\> tox run -e sphinx -c <path to tox.ini> --root <path to python package>
114
136
```
115
137
116
138
### Custom Pytest Arguments
@@ -120,7 +142,7 @@ Generate sphinx doc for this package.
120
142
[Tox Documentation on Positional Arguments](https://tox.wiki/en/latest/config.html#substitutions-for-positional-arguments-in-commands)
121
143
122
144
**Example: Invoke tox, breaking into the debugger on failure**
123
-
`tox -e whl -c ../../../eng/tox/tox.ini -- --pdb`
145
+
`tox run -e whl -c <path to tox.ini> --root <path to python package> -- --pdb`
124
146
125
147
### Performance Testing
126
148
@@ -150,7 +172,7 @@ a. cd to package root folder
150
172
b. run tox environment devtest
151
173
152
174
```
153
-
\> tox -e devtest -c <path to tox.ini>
175
+
\> tox run -e devtest -c <path to tox.ini> --root <path to python package>
154
176
```
155
177
156
178
This tox test( devtest) will fail if installed dependent packages are not dev build version.
Copy file name to clipboardExpand all lines: doc/dev/dev_setup.md
+3-4Lines changed: 3 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,11 +33,11 @@ or execute the various commands available in the toolbox.
33
33
34
34
4. Setup your development environment
35
35
36
-
Install the development requirements for a specific library (located in the `dev_requirements.txt` file at the root of the library), [Tox][tox], [Tox monorepo][tox_monorepo] and an editable install of your library. For example, to install requirements for `azure-ai-formrecognizer`:
36
+
Install the development requirements for a specific library (located in the `dev_requirements.txt` file at the root of the library), [Tox][tox] and an editable install of your library. For example, to install requirements for `azure-ai-formrecognizer`:
37
37
```
38
38
azure-sdk-for-python> cd sdk/formrecognizer/azure-ai-formrecognizer
.../azure-sdk-for-python/sdk/eventgrid/azure-eventgrid>tox run -e pylint -c ../../../eng/tox/tox.ini --root .
28
28
29
29
If you don't want to use tox, you can also install and run pylint on its own:
30
30
@@ -58,9 +58,9 @@ In addition to being a part of the CI, the custom pylint checkers are also integ
58
58
59
59
There is now a new step on the CI pipeline called `Run Pylint Next`. This is merely a duplicate of the `Run Pylint` step with the exception that `Run Pylint Next` uses the latest version of pylint and the latest version of the custom pylint checkers.
60
60
61
-
This next-pylint enviornment can also be run locally through tox:
61
+
This next-pylint environment can also be run locally through tox:
62
62
63
-
tox -e next-pylint -c ../../../eng/tox/tox.ini
63
+
tox run -e next-pylint -c ../../../eng/tox/tox.ini --root <path to python package>
64
64
65
65
The errors generated by the `Run Pylint Next` step will not break your weekly test pipelines, but make sure to fix the warnings so that your client library is up to date for the next pylint release.
Copy file name to clipboardExpand all lines: doc/dev/sample_guide.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -52,13 +52,13 @@ The given `START`/`END` keywords can be used in a [sphinx literalinclude][sphinx
52
52
[Literalinclude example][literalinclude]
53
53
54
54
The rendered code snippets are sensitive to the indentation in the sample file. Adjust the `dedent` accordingly to ensure the sample is captured accurately and not accidentally trimmed.
55
-
You can preview how published reference documentation will look by running [tox][tox]: `tox -e sphinx -c ../../../eng/tox/tox.ini`.
55
+
You can preview how published reference documentation will look by running [tox][tox]: `tox run -e sphinx -c ../../../eng/tox/tox.ini --root <path to python package>`.
56
56
57
57
## Test run samples in CI live tests
58
58
Per the [Python guidelines][snippet_guidelines], sample code and snippets should be test run in CI to ensure they remain functional. Samples should be run in the package's live test pipeline which is scheduled to run daily.
59
59
To ensure samples do get tested as part of regular CI runs, add these [lines][live_tests] to the package's tests.yml.
60
60
61
-
You can test this CI step locally first, by utilizing [tox][tox] and running `tox -e samples -c ../../../eng/tox/tox.ini` at the package-level.
61
+
You can test this CI step locally first, by utilizing [tox][tox] and running `tox run -e samples -c ../../../eng/tox/tox.ini --root <path to python package>`.
62
62
63
63
The `Test Samples` step in CI will rely on the resources provisioned and environment variables used for running the package's tests.
Copy file name to clipboardExpand all lines: doc/dev/tests.md
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -123,20 +123,20 @@ If you have print statements in your tests for debugging you can add the `-s` fl
123
123
124
124
## Tox
125
125
126
-
The Python SDK uses the [tox project](https://tox.readthedocs.io/en/latest/) to automate releases, run tests, run linters, and build our documentation. The `tox.ini` file is located at `azure-sdk-for-python/eng/tox/tox.ini` for reference. You do not need to make any changes to the tox file for tox to work with your project. Tox will create a directory (`.tox`) in the head of your branch. The first time you run tox commands it may take several moments, but subsequent runs will be quicker. To install tox run the following command from within your virtual environment.
127
-
`(env) > pip install tox tox-monorepo`.
126
+
The Python SDK uses the [tox project](https://tox.wiki/en/latest/) to automate releases, run tests, run linters, and build our documentation. The `tox.ini` file is located at `azure-sdk-for-python/eng/tox/tox.ini` for reference. You do not need to make any changes to the tox file for tox to work with your project. Tox will create a directory (`.tox`) in the head of your branch. The first time you run tox commands it may take several moments, but subsequent runs will be quicker. To install tox run the following command from within your virtual environment.
127
+
`(env) > pip install tox<5`.
128
128
129
129
To run a tox command from your directory use the following commands:
0 commit comments