|
1 | 1 | # License: MIT |
2 | 2 | # Copyright © 2022 Frequenz Energy-as-a-Service GmbH |
3 | 3 |
|
4 | | -"""Automation for code quality checks and unit tests for the Frequenz SDK. |
| 4 | +"""Configuration file for nox.""" |
5 | 5 |
|
6 | | -This file specified all the checks that can be run from command line invocations |
7 | | -of `nox`. |
| 6 | +from frequenz.repo.config import RepositoryType, nox |
8 | 7 |
|
9 | | -The following checks are performed: |
10 | | -
|
11 | | -1. `formatting` :: checks that the code is formatted with `black` and the imports |
12 | | - are sorted with `isort`. |
13 | | -2. `mypy` :: type checks all source files with `mypy --strict`. |
14 | | -3. `pylint` :: lints all source files with `pylint`. |
15 | | -4. `docstrings` :: checks that all public functions have docstrings with |
16 | | - 1. a one-line imperative description at the top, followed by additional |
17 | | - description, using `pydocstyle`. |
18 | | - 2. function parameters, return values, and raised exceptions are documented |
19 | | - following the google style guide for these items: |
20 | | - https://google.github.io/styleguide/pyguide.html#doc-function-args, using |
21 | | - `darglint`. |
22 | | -5. `pytest_min` :: run all unittests using `pytest`, with the oldest supported |
23 | | - versions of all dependencies installed. |
24 | | -6. `pytest_max` :: run all unittests using `pytest`, with the latest supported |
25 | | - versions of all dependencies installed. |
26 | | -
|
27 | | -Usage: |
28 | | -
|
29 | | -1. Run all checks in a *new* venv. |
30 | | -
|
31 | | - nox |
32 | | -
|
33 | | -2. Run all checks in an *exising* venv. This would be much faster if venv for |
34 | | - all tests exist already. If they don't exist, new venvs will be created. |
35 | | -
|
36 | | - nox -R |
37 | | -
|
38 | | -3. Run a subset of available checks: |
39 | | -
|
40 | | - nox -e mypy pylint # create new venvs for specified checks. |
41 | | - nox -R -e mypy pylint # reuse venvs for specified checks if available. |
42 | | -
|
43 | | -4. The `pytest_min` and `pytest_max` checks run `pytest` on all available tests, |
44 | | - including test coverage generation. But this can be slow for fast local |
45 | | - test-devlop cycles, and so `pytest` can also be invoked with optional custom |
46 | | - arguments, in which case, only the specified arguments are passed to |
47 | | - `pytest`. This can be done as follows: |
48 | | -
|
49 | | - nox -R -e pytest_min [-- <args for pytest>] |
50 | | - nox -R -e pytest_min -- -s -x tests/timeseries/test_logical_meter.py |
51 | | -""" |
52 | | - |
53 | | -from __future__ import annotations |
54 | | - |
55 | | -from typing import Any, Iterable |
56 | | - |
57 | | -import nox |
58 | | -import toml |
59 | | - |
60 | | -DEFAULT_PATH_PACKAGES = { |
61 | | - "benchmarks": "benchmarks", |
62 | | - "docs": "docs", |
63 | | - "examples": "examples", |
64 | | - "src": "frequenz.sdk", |
65 | | - "tests": "tests", |
66 | | - "noxfile.py": "noxfile", |
67 | | -} |
68 | | -"""A list of path to be used by default and its corresponding package name. |
69 | | -
|
70 | | -The package name is needed for mypy, as it takes packages when full import |
71 | | -checking needs to be done. |
72 | | -""" |
73 | | - |
74 | | - |
75 | | -def min_dependencies() -> list[str]: |
76 | | - """Extract the minimum dependencies from pyproject.toml. |
77 | | -
|
78 | | - Raises: |
79 | | - RuntimeError: If minimun dependencies are not properly |
80 | | - set in pyproject.toml. |
81 | | -
|
82 | | - Returns: |
83 | | - the minimun dependencies defined in pyproject.toml. |
84 | | -
|
85 | | - """ |
86 | | - with open("pyproject.toml", "r", encoding="utf-8") as toml_file: |
87 | | - data = toml.load(toml_file) |
88 | | - |
89 | | - dependencies = data.get("project", {}).get("dependencies", {}) |
90 | | - if not dependencies: |
91 | | - raise RuntimeError(f"No dependencies found in file: {toml_file.name}") |
92 | | - |
93 | | - min_deps: list[str] = [] |
94 | | - for dep in dependencies: |
95 | | - min_dep = dep.split(",")[0] |
96 | | - if any(op in min_dep for op in (">=", "==")): |
97 | | - min_deps.append(min_dep.replace(">=", "==")) |
98 | | - else: |
99 | | - raise RuntimeError(f"Minimum requirement is not set: {dep}") |
100 | | - return min_deps |
101 | | - |
102 | | - |
103 | | -def _source_file_paths(session: nox.Session) -> list[str]: |
104 | | - """Return the file paths to run the checks on. |
105 | | -
|
106 | | - If positional arguments are present in the nox session, we use those as the |
107 | | - file paths, and if not, we use all source files. |
108 | | -
|
109 | | - Args: |
110 | | - session: the nox session. |
111 | | -
|
112 | | - Returns: |
113 | | - the file paths to run the checks on. |
114 | | - """ |
115 | | - if session.posargs: |
116 | | - return session.posargs |
117 | | - return list(DEFAULT_PATH_PACKAGES.keys()) |
118 | | - |
119 | | - |
120 | | -# Run all checks except `ci_checks` by default. When running locally with just |
121 | | -# `nox` or `nox -R`, these are the checks that will run. |
122 | | -nox.options.sessions = [ |
123 | | - "formatting", |
124 | | - "mypy", |
125 | | - "pylint", |
126 | | - "docstrings", |
127 | | - "pytest_min", |
128 | | - "pytest_max", |
129 | | -] |
130 | | - |
131 | | - |
132 | | -@nox.session |
133 | | -def ci_checks_max(session: nox.Session) -> None: |
134 | | - """Run all checks with max dependencies in a single session. |
135 | | -
|
136 | | - This is faster than running the checks separately, so it is suitable for CI. |
137 | | -
|
138 | | - This does NOT run pytest_min, so that needs to be run separately as well. |
139 | | -
|
140 | | - Args: |
141 | | - session: the nox session. |
142 | | - """ |
143 | | - session.install("-e", ".[dev]") |
144 | | - |
145 | | - formatting(session, False) |
146 | | - mypy(session, False) |
147 | | - pylint(session, False) |
148 | | - docstrings(session, False) |
149 | | - pytest_max(session, False) |
150 | | - |
151 | | - |
152 | | -@nox.session |
153 | | -def formatting(session: nox.Session, install_deps: bool = True) -> None: |
154 | | - """Check code formatting with black and isort. |
155 | | -
|
156 | | - Args: |
157 | | - session: the nox session. |
158 | | - install_deps: True if dependencies should be installed. |
159 | | - """ |
160 | | - if install_deps: |
161 | | - session.install("-e", ".[format]") |
162 | | - |
163 | | - paths = _source_file_paths(session) |
164 | | - session.run("black", "--check", *paths) |
165 | | - session.run("isort", "--diff", "--check", *paths) |
166 | | - |
167 | | - |
168 | | -@nox.session |
169 | | -def mypy(session: nox.Session, install_deps: bool = True) -> None: |
170 | | - """Check type hints with mypy. |
171 | | -
|
172 | | - Args: |
173 | | - session: the nox session. |
174 | | - install_deps: True if dependencies should be installed. |
175 | | - """ |
176 | | - if install_deps: |
177 | | - # install the package itself as editable, so that it is possible to do |
178 | | - # fast local tests with `nox -R -e mypy`. |
179 | | - session.install("-e", ".[mypy]") |
180 | | - |
181 | | - def _flatten(iterable: Iterable[Iterable[Any]]) -> Iterable[Any]: |
182 | | - return [item for sublist in iterable for item in sublist] |
183 | | - |
184 | | - args = ( |
185 | | - session.posargs |
186 | | - if session.posargs |
187 | | - else _flatten(("-p", p) for p in DEFAULT_PATH_PACKAGES.values()) |
188 | | - ) |
189 | | - |
190 | | - session.run( |
191 | | - "mypy", |
192 | | - "--install-types", |
193 | | - "--namespace-packages", |
194 | | - "--non-interactive", |
195 | | - "--explicit-package-bases", |
196 | | - "--strict", |
197 | | - *args, |
198 | | - ) |
199 | | - |
200 | | - |
201 | | -@nox.session |
202 | | -def pylint(session: nox.Session, install_deps: bool = True) -> None: |
203 | | - """Check for code smells with pylint. |
204 | | -
|
205 | | - Args: |
206 | | - session: the nox session. |
207 | | - install_deps: True if dependencies should be installed. |
208 | | - """ |
209 | | - if install_deps: |
210 | | - # install the package itself as editable, so that it is possible to do |
211 | | - # fast local tests with `nox -R -e pylint`. |
212 | | - session.install("-e", ".[pylint]") |
213 | | - |
214 | | - paths = _source_file_paths(session) |
215 | | - session.run( |
216 | | - "pylint", |
217 | | - "--extension-pkg-whitelist=pydantic", |
218 | | - *paths, |
219 | | - ) |
220 | | - |
221 | | - |
222 | | -@nox.session |
223 | | -def docstrings(session: nox.Session, install_deps: bool = True) -> None: |
224 | | - """Check docstring tone with pydocstyle and param descriptions with darglint. |
225 | | -
|
226 | | - Args: |
227 | | - session: the nox session. |
228 | | - install_deps: True if dependencies should be installed. |
229 | | - """ |
230 | | - if install_deps: |
231 | | - session.install("-e", ".[docs-lint]") |
232 | | - |
233 | | - paths = _source_file_paths(session) |
234 | | - session.run("pydocstyle", *paths) |
235 | | - |
236 | | - # Darglint checks that function argument and return values are documented. |
237 | | - # This is needed only for the `src` dir, so we exclude the other top level |
238 | | - # dirs that contain code, unless some paths were specified by argument, in |
239 | | - # which case we use those untouched. |
240 | | - darglint_paths = session.posargs or filter( |
241 | | - lambda path: not (path.startswith("tests") or path.startswith("benchmarks")), |
242 | | - _source_file_paths(session), |
243 | | - ) |
244 | | - session.run( |
245 | | - "darglint", |
246 | | - "-v2", # for verbose error messages. |
247 | | - *darglint_paths, |
248 | | - ) |
249 | | - |
250 | | - |
251 | | -@nox.session |
252 | | -def pytest_max(session: nox.Session, install_deps: bool = True) -> None: |
253 | | - """Test the code against max dependency versions with pytest. |
254 | | -
|
255 | | - Args: |
256 | | - session: the nox session. |
257 | | - install_deps: True if dependencies should be installed. |
258 | | - """ |
259 | | - if install_deps: |
260 | | - # install the package itself as editable, so that it is possible to do |
261 | | - # fast local tests with `nox -R -e pytest_max`. |
262 | | - session.install("-e", ".[pytest]") |
263 | | - |
264 | | - _pytest_impl(session, "max") |
265 | | - |
266 | | - |
267 | | -@nox.session |
268 | | -def pytest_min(session: nox.Session, install_deps: bool = True) -> None: |
269 | | - """Test the code against min dependency versions with pytest. |
270 | | -
|
271 | | - Args: |
272 | | - session: the nox session. |
273 | | - install_deps: True if dependencies should be installed. |
274 | | - """ |
275 | | - if install_deps: |
276 | | - # install the package itself as editable, so that it is possible to do |
277 | | - # fast local tests with `nox -R -e pytest_min`. |
278 | | - session.install("-e", ".[pytest]", *min_dependencies()) |
279 | | - |
280 | | - _pytest_impl(session, "min") |
281 | | - |
282 | | - |
283 | | -def _pytest_impl(session: nox.Session, max_or_min_deps: str) -> None: |
284 | | - session.run( |
285 | | - "pytest", |
286 | | - "-W=all", |
287 | | - "-vv", |
288 | | - "--cov=frequenz.sdk", |
289 | | - "--cov-report=term", |
290 | | - f"--cov-report=html:.htmlcov-{max_or_min_deps}", |
291 | | - *session.posargs, |
292 | | - ) |
| 8 | +nox.configure(RepositoryType.LIB) |
0 commit comments