Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/hypothesis/_settings.py: 74%

1# This file is part of Hypothesis, which may be found at 

2# https://github.com/HypothesisWorks/hypothesis/ 

3# 

4# Copyright the Hypothesis Authors. 

5# Individual contributors are listed in AUTHORS.rst and the git log. 

6# 

7# This Source Code Form is subject to the terms of the Mozilla Public License, 

8# v. 2.0. If a copy of the MPL was not distributed with this file, You can 

9# obtain one at https://mozilla.org/MPL/2.0/. 

10 

11"""The settings module configures runtime options for Hypothesis. 

12 

13Either an explicit settings object can be used or the default object on 

14this module can be modified. 

15""" 

16 

17import contextlib 

18import datetime 

19import inspect 

20import os 

21import warnings 

22from collections.abc import Collection, Generator, Sequence 

23from enum import Enum, EnumMeta, IntEnum, unique 

24from typing import ( 

25 TYPE_CHECKING, 

26 Any, 

27 ClassVar, 

28 Optional, 

29 TypeVar, 

30 Union, 

31) 

32 

33from hypothesis.errors import ( 

34 HypothesisDeprecationWarning, 

35 InvalidArgument, 

36) 

37from hypothesis.internal.conjecture.providers import AVAILABLE_PROVIDERS 

38from hypothesis.internal.reflection import get_pretty_function_description 

39from hypothesis.internal.validation import check_type, try_convert 

40from hypothesis.utils.conventions import not_set 

41from hypothesis.utils.dynamicvariables import DynamicVariable 

42 

43if TYPE_CHECKING: 

44 from hypothesis.database import ExampleDatabase 

45 

46__all__ = ["settings"] 

47 

48T = TypeVar("T") 

49all_settings: list[str] = [ 

50 "max_examples", 

51 "derandomize", 

52 "database", 

53 "verbosity", 

54 "phases", 

55 "stateful_step_count", 

56 "report_multiple_bugs", 

57 "suppress_health_check", 

58 "deadline", 

59 "print_blob", 

60 "backend", 

61] 

62 

63 

64@unique 

65class Verbosity(IntEnum): 

66 """Options for the |settings.verbosity| argument to |@settings|.""" 

67 

68 quiet = 0 

69 """ 

70 Hypothesis will not print any output, not even the final falsifying example. 

71 """ 

72 

73 normal = 1 

74 """ 

75 Standard verbosity. Hypothesis will print the falsifying example, alongside 

76 any notes made with |note| (only for the falsfying example). 

77 """ 

78 

79 verbose = 2 

80 """ 

81 Increased verbosity. In addition to everything in |Verbosity.normal|, Hypothesis 

82 will print each example as it tries it, as well as any notes made with |note| 

83 for every example. Hypothesis will also print shrinking attempts. 

84 """ 

85 

86 debug = 3 

87 """ 

88 Even more verbosity. Useful for debugging Hypothesis internals. You probably 

89 don't want this. 

90 """ 

91 

92 def __repr__(self) -> str: 

93 return f"Verbosity.{self.name}" 

94 

95 

96@unique 

97class Phase(IntEnum): 

98 """Options for the |settings.phases| argument to |@settings|.""" 

99 

100 explicit = 0 

101 """ 

102 Controls whether explicit examples are run. 

103 """ 

104 

105 reuse = 1 

106 """ 

107 Controls whether previous examples will be reused. 

108 """ 

109 

110 generate = 2 

111 """ 

112 Controls whether new examples will be generated. 

113 """ 

114 

115 target = 3 

116 """ 

117 Controls whether examples will be mutated for targeting. 

118 """ 

119 

120 shrink = 4 

121 """ 

122 Controls whether examples will be shrunk. 

123 """ 

124 

125 explain = 5 

126 """ 

127 Controls whether Hypothesis attempts to explain test failures. 

128 

129 The explain phase has two parts, each of which is best-effort - if Hypothesis 

130 can't find a useful explanation, we'll just print the minimal failing example. 

131 """ 

132 

133 def __repr__(self) -> str: 

134 return f"Phase.{self.name}" 

135 

136 

137class HealthCheckMeta(EnumMeta): 

138 def __iter__(self): 

139 deprecated = (HealthCheck.return_value, HealthCheck.not_a_test_method) 

140 return iter(x for x in super().__iter__() if x not in deprecated) 

141 

142 

143@unique 

144class HealthCheck(Enum, metaclass=HealthCheckMeta): 

145 """ 

146 A |HealthCheck| is proactively raised by Hypothesis when Hypothesis detects 

147 that your test has performance problems, which may result in less rigorous 

148 testing than you expect. For example, if your test takes a long time to generate 

149 inputs, or filters away too many inputs using |assume| or |filter|, Hypothesis 

150 will raise a corresponding health check. 

151 

152 A health check is a proactive warning, not an error. We encourage suppressing 

153 health checks where you have evaluated they will not pose a problem, or where 

154 you have evaluated that fixing the underlying issue is not worthwhile. 

155 

156 With the exception of |HealthCheck.function_scoped_fixture| and 

157 |HealthCheck.differing_executors|, all health checks warn about performance 

158 problems, not correctness errors. 

159 

160 Disabling health checks 

161 ----------------------- 

162 

163 Health checks can be disabled by |settings.suppress_health_check|. To suppress 

164 all health checks, you can pass ``suppress_health_check=list(HealthCheck)``. 

165 

166 .. seealso:: 

167 

168 See also the :doc:`/how-to/suppress-healthchecks` how-to. 

169 

170 Correctness health checks 

171 ------------------------- 

172 

173 Some health checks report potential correctness errors, rather than performance 

174 problems. 

175 

176 * |HealthCheck.function_scoped_fixture| indicates that a function-scoped 

177 pytest fixture is used by an |@given| test. Many Hypothesis users expect 

178 function-scoped fixtures to reset once per input, but they actually reset once 

179 per test. We proactively raise |HealthCheck.function_scoped_fixture| to 

180 ensure you have considered this case. 

181 * |HealthCheck.differing_executors| indicates that the same |@given| test has 

182 been executed multiple times with multiple distinct executors. 

183 

184 We recommend treating these particular health checks with more care, as 

185 suppressing them may result in an unsound test. 

186 """ 

187 

188 def __repr__(self) -> str: 

189 return f"{self.__class__.__name__}.{self.name}" 

190 

191 @classmethod 

192 def all(cls) -> list["HealthCheck"]: 

193 # Skipping of deprecated attributes is handled in HealthCheckMeta.__iter__ 

194 note_deprecation( 

195 "`HealthCheck.all()` is deprecated; use `list(HealthCheck)` instead.", 

196 since="2023-04-16", 

197 has_codemod=True, 

198 stacklevel=1, 

199 ) 

200 return list(HealthCheck) 

201 

202 data_too_large = 1 

203 """Checks if too many examples are aborted for being too large. 

204 

205 This is measured by the number of random choices that Hypothesis makes 

206 in order to generate something, not the size of the generated object. 

207 For example, choosing a 100MB object from a predefined list would take 

208 only a few bits, while generating 10KB of JSON from scratch might trigger 

209 this health check. 

210 """ 

211 

212 filter_too_much = 2 

213 """Check for when the test is filtering out too many examples, either 

214 through use of |assume| or |.filter|, or occasionally for Hypothesis 

215 internal reasons.""" 

216 

217 too_slow = 3 

218 """ 

219 Check for when input generation is very slow. Since Hypothesis generates 100 

220 (by default) inputs per test execution, a slowdown in generating each input 

221 can result in very slow tests overall. 

222 """ 

223 

224 return_value = 5 

225 """Deprecated; we always error if a test returns a non-None value.""" 

226 

227 large_base_example = 7 

228 """ 

229 Checks if the smallest natural input to your test is very large. This makes 

230 it difficult for Hypothesis to generate good inputs, especially when trying to 

231 shrink failing inputs. 

232 """ 

233 

234 not_a_test_method = 8 

235 """Deprecated; we always error if |@given| is applied 

236 to a method defined by :class:`python:unittest.TestCase` (i.e. not a test).""" 

237 

238 function_scoped_fixture = 9 

239 """Checks if |@given| has been applied to a test 

240 with a pytest function-scoped fixture. Function-scoped fixtures run once 

241 for the whole function, not once per example, and this is usually not what 

242 you want. 

243 

244 Because of this limitation, tests that need to set up or reset 

245 state for every example need to do so manually within the test itself, 

246 typically using an appropriate context manager. 

247 

248 Suppress this health check only in the rare case that you are using a 

249 function-scoped fixture that does not need to be reset between individual 

250 examples, but for some reason you cannot use a wider fixture scope 

251 (e.g. session scope, module scope, class scope). 

252 

253 This check requires the :ref:`Hypothesis pytest plugin<pytest-plugin>`, 

254 which is enabled by default when running Hypothesis inside pytest.""" 

255 

256 differing_executors = 10 

257 """Checks if |@given| has been applied to a test 

258 which is executed by different :ref:`executors<custom-function-execution>`. 

259 If your test function is defined as a method on a class, that class will be 

260 your executor, and subclasses executing an inherited test is a common way 

261 for things to go wrong. 

262 

263 The correct fix is often to bring the executor instance under the control 

264 of hypothesis by explicit parametrization over, or sampling from, 

265 subclasses, or to refactor so that |@given| is 

266 specified on leaf subclasses.""" 

267 

268 nested_given = 11 

269 """Checks if |@given| is used inside another 

270 |@given|. This results in quadratic generation and 

271 shrinking behavior, and can usually be expressed more cleanly by using 

272 :func:`~hypothesis.strategies.data` to replace the inner 

273 |@given|. 

274 

275 Nesting @given can be appropriate if you set appropriate limits for the 

276 quadratic behavior and cannot easily reexpress the inner function with 

277 :func:`~hypothesis.strategies.data`. To suppress this health check, set 

278 ``suppress_health_check=[HealthCheck.nested_given]`` on the outer 

279 |@given|. Setting it on the inner 

280 |@given| has no effect. If you have more than one 

281 level of nesting, add a suppression for this health check to every 

282 |@given| except the innermost one. 

283 """ 

284 

285 

286class duration(datetime.timedelta): 

287 """A timedelta specifically measured in milliseconds.""" 

288 

289 def __repr__(self) -> str: 

290 ms = self.total_seconds() * 1000 

291 return f"timedelta(milliseconds={int(ms) if ms == int(ms) else ms!r})" 

292 

293 

294def is_in_ci() -> bool: 

295 # GitHub Actions, Travis CI and AppVeyor have "CI" 

296 # Azure Pipelines has "TF_BUILD" 

297 # GitLab CI has "GITLAB_CI" 

298 return "CI" in os.environ or "TF_BUILD" in os.environ or "GITLAB_CI" in os.environ 

299 

300 

301default_variable = DynamicVariable[Optional["settings"]](None) 

302 

303 

304def _validate_choices(name: str, value: T, *, choices: Sequence[object]) -> T: 

305 if value not in choices: 

306 msg = f"Invalid {name}, {value!r}. Valid choices: {choices!r}" 

307 raise InvalidArgument(msg) 

308 return value 

309 

310 

311def _validate_max_examples(max_examples: int) -> int: 

312 check_type(int, max_examples, name="max_examples") 

313 if max_examples < 1: 

314 raise InvalidArgument( 

315 f"max_examples={max_examples!r} must be at least one. If you want " 

316 "to disable generation entirely, use phases=[Phase.explicit] instead." 

317 ) 

318 return max_examples 

319 

320 

321def _validate_database( 

322 database: Optional["ExampleDatabase"], 

323) -> Optional["ExampleDatabase"]: 

324 from hypothesis.database import ExampleDatabase 

325 

326 if database is None or isinstance(database, ExampleDatabase): 

327 return database 

328 raise InvalidArgument( 

329 "Arguments to the database setting must be None or an instance of " 

330 "ExampleDatabase. Use one of the database classes in " 

331 "hypothesis.database" 

332 ) 

333 

334 

335def _validate_phases(phases: Collection[Phase]) -> Sequence[Phase]: 

336 phases = tuple(phases) 

337 for phase in phases: 

338 if not isinstance(phase, Phase): 

339 raise InvalidArgument(f"{phase!r} is not a valid phase") 

340 return tuple(phase for phase in list(Phase) if phase in phases) 

341 

342 

343def _validate_stateful_step_count(stateful_step_count: int) -> int: 

344 check_type(int, stateful_step_count, name="stateful_step_count") 

345 if stateful_step_count < 1: 

346 raise InvalidArgument( 

347 f"stateful_step_count={stateful_step_count!r} must be at least one." 

348 ) 

349 return stateful_step_count 

350 

351 

352def _validate_suppress_health_check(suppressions): 

353 suppressions = try_convert(tuple, suppressions, "suppress_health_check") 

354 for health_check in suppressions: 

355 if not isinstance(health_check, HealthCheck): 

356 raise InvalidArgument( 

357 f"Non-HealthCheck value {health_check!r} of type {type(health_check).__name__} " 

358 "is invalid in suppress_health_check." 

359 ) 

360 if health_check in (HealthCheck.return_value, HealthCheck.not_a_test_method): 

361 note_deprecation( 

362 f"The {health_check.name} health check is deprecated, because this is always an error.", 

363 since="2023-03-15", 

364 has_codemod=False, 

365 stacklevel=2, 

366 ) 

367 return suppressions 

368 

369 

370def _validate_deadline( 

371 x: Union[int, float, datetime.timedelta, None], 

372) -> Optional[duration]: 

373 if x is None: 

374 return x 

375 invalid_deadline_error = InvalidArgument( 

376 f"deadline={x!r} (type {type(x).__name__}) must be a timedelta object, " 

377 "an integer or float number of milliseconds, or None to disable the " 

378 "per-test-case deadline." 

379 ) 

380 if isinstance(x, (int, float)): 

381 if isinstance(x, bool): 

382 raise invalid_deadline_error 

383 try: 

384 x = duration(milliseconds=x) 

385 except OverflowError: 

386 raise InvalidArgument( 

387 f"deadline={x!r} is invalid, because it is too large to represent " 

388 "as a timedelta. Use deadline=None to disable deadlines." 

389 ) from None 

390 if isinstance(x, datetime.timedelta): 

391 if x <= datetime.timedelta(0): 

392 raise InvalidArgument( 

393 f"deadline={x!r} is invalid, because it is impossible to meet a " 

394 "deadline <= 0. Use deadline=None to disable deadlines." 

395 ) 

396 return duration(seconds=x.total_seconds()) 

397 raise invalid_deadline_error 

398 

399 

400def _validate_backend(backend: str) -> str: 

401 if backend not in AVAILABLE_PROVIDERS: 

402 if backend == "crosshair": # pragma: no cover 

403 install = '`pip install "hypothesis[crosshair]"` and try again.' 

404 raise InvalidArgument(f"backend={backend!r} is not available. {install}") 

405 raise InvalidArgument( 

406 f"backend={backend!r} is not available - maybe you need to install a plugin?" 

407 f"\n Installed backends: {sorted(AVAILABLE_PROVIDERS)!r}" 

408 ) 

409 return backend 

410 

411 

412class settingsMeta(type): 

413 def __init__(cls, *args, **kwargs): 

414 super().__init__(*args, **kwargs) 

415 

416 @property 

417 def default(cls) -> Optional["settings"]: 

418 v = default_variable.value 

419 if v is not None: 

420 return v 

421 if getattr(settings, "_current_profile", None) is not None: 

422 assert settings._current_profile is not None 

423 settings.load_profile(settings._current_profile) 

424 assert default_variable.value is not None 

425 return default_variable.value 

426 

427 def __setattr__(cls, name: str, value: object) -> None: 

428 if name == "default": 

429 raise AttributeError( 

430 "Cannot assign to the property settings.default - " 

431 "consider using settings.load_profile instead." 

432 ) 

433 elif not name.startswith("_"): 

434 raise AttributeError( 

435 f"Cannot assign hypothesis.settings.{name}={value!r} - the settings " 

436 "class is immutable. You can change the global default " 

437 "settings with settings.load_profile, or use @settings(...) " 

438 "to decorate your test instead." 

439 ) 

440 super().__setattr__(name, value) 

441 

442 def __repr__(cls): 

443 return "hypothesis.settings" 

444 

445 

446class settings(metaclass=settingsMeta): 

447 """ 

448 A settings object controls the following aspects of test behavior: 

449 |~settings.max_examples|, |~settings.derandomize|, |~settings.database|, 

450 |~settings.verbosity|, |~settings.phases|, |~settings.stateful_step_count|, 

451 |~settings.report_multiple_bugs|, |~settings.suppress_health_check|, 

452 |~settings.deadline|, |~settings.print_blob|, and |~settings.backend|. 

453 

454 A settings object can be applied as a decorator to a test function, in which 

455 case that test function will use those settings. A test may only have one 

456 settings object applied to it. A settings object can also be passed to 

457 |settings.register_profile| or as a parent to another |settings|. 

458 

459 Attribute inheritance 

460 --------------------- 

461 

462 Settings objects are immutable once created. When a settings object is created, 

463 it uses the value specified for each attribute. Any attribute which is 

464 not specified will inherit from its value in the ``parent`` settings object. 

465 If ``parent`` is not passed, any attributes which are not specified will inherit 

466 from the currently active settings profile instead. 

467 

468 For instance, ``settings(max_examples=10)`` will have a ``max_examples`` of ``10``, 

469 and the value of all other attributes will be equal to its value in the 

470 currently active settings profile. 

471 

472 A settings object is immutable once created. Changes made from activating a new 

473 settings profile with |settings.load_profile| will be reflected in 

474 settings objects created after the profile was made active, but not in existing 

475 settings objects. 

476 

477 Built-in profiles 

478 ----------------- 

479 

480 While you can register additional profiles with |settings.register_profile|, 

481 Hypothesis comes with two built-in profiles: ``default`` and ``ci``. 

482 

483 The ``default`` profile is active by default, unless one of the ``CI``, 

484 ``TF_BUILD``, or ``GITLAB_CI`` environment variables are set (to any value), 

485 in which case the ``CI`` profile will be active by default. 

486 

487 The attributes of the currently active settings profile can be retrieved with 

488 ``settings()`` (so ``settings().max_examples`` is the currently active default 

489 for |settings.max_examples|). 

490 

491 The settings attributes for the built-in profiles are as follows: 

492 

493 .. code-block:: python 

494 

495 default = settings.register_profile( 

496 "default", 

497 max_examples=100, 

498 derandomize=False, 

499 database=not_set, # see settings.database for the default database 

500 verbosity=Verbosity.normal, 

501 phases=tuple(Phase), 

502 stateful_step_count=50, 

503 report_multiple_bugs=True, 

504 suppress_health_check=(), 

505 deadline=duration(milliseconds=200), 

506 print_blob=False, 

507 backend="hypothesis", 

508 ) 

509 

510 ci = settings.register_profile( 

511 "ci", 

512 parent=default, 

513 derandomize=True, 

514 deadline=None, 

515 database=None, 

516 print_blob=True, 

517 suppress_health_check=[HealthCheck.too_slow], 

518 ) 

519 

520 You can configure either of the built-in profiles with |settings.register_profile|: 

521 

522 .. code-block:: python 

523 

524 # run more examples in CI 

525 settings.register_profile( 

526 "ci", 

527 settings.get_profile("ci"), 

528 max_examples=1000, 

529 ) 

530 """ 

531 

532 _profiles: ClassVar[dict[str, "settings"]] = {} 

533 _current_profile: ClassVar[Optional[str]] = None 

534 

535 def __init__( 

536 self, 

537 parent: Optional["settings"] = None, 

538 *, 

539 # This looks pretty strange, but there's good reason: we want Mypy to detect 

540 # bad calls downstream, but not to freak out about the `= not_set` part even 

541 # though it's not semantically valid to pass that as an argument value. 

542 # The intended use is "like **kwargs, but more tractable for tooling". 

543 max_examples: int = not_set, # type: ignore 

544 derandomize: bool = not_set, # type: ignore 

545 database: Optional["ExampleDatabase"] = not_set, # type: ignore 

546 verbosity: "Verbosity" = not_set, # type: ignore 

547 phases: Collection["Phase"] = not_set, # type: ignore 

548 stateful_step_count: int = not_set, # type: ignore 

549 report_multiple_bugs: bool = not_set, # type: ignore 

550 suppress_health_check: Collection["HealthCheck"] = not_set, # type: ignore 

551 deadline: Union[int, float, datetime.timedelta, None] = not_set, # type: ignore 

552 print_blob: bool = not_set, # type: ignore 

553 backend: str = not_set, # type: ignore 

554 ) -> None: 

555 self._in_definition = True 

556 

557 if parent is not None: 

558 check_type(settings, parent, "parent") 

559 if derandomize not in (not_set, False): 

560 if database not in (not_set, None): # type: ignore 

561 raise InvalidArgument( 

562 "derandomize=True implies database=None, so passing " 

563 f"{database=} too is invalid." 

564 ) 

565 database = None 

566 

567 # fallback is None if we're creating the default settings object, and 

568 # the parent (or default settings object) otherwise 

569 self._fallback = parent or settings.default 

570 self._max_examples = ( 

571 self._fallback.max_examples # type: ignore 

572 if max_examples is not_set # type: ignore 

573 else _validate_max_examples(max_examples) 

574 ) 

575 self._derandomize = ( 

576 self._fallback.derandomize # type: ignore 

577 if derandomize is not_set # type: ignore 

578 else _validate_choices("derandomize", derandomize, choices=[True, False]) 

579 ) 

580 if database is not not_set: # type: ignore 

581 database = _validate_database(database) 

582 self._database = database 

583 self._cached_database = None 

584 self._verbosity = ( 

585 self._fallback.verbosity # type: ignore 

586 if verbosity is not_set # type: ignore 

587 else _validate_choices("verbosity", verbosity, choices=tuple(Verbosity)) 

588 ) 

589 self._phases = ( 

590 self._fallback.phases # type: ignore 

591 if phases is not_set # type: ignore 

592 else _validate_phases(phases) 

593 ) 

594 self._stateful_step_count = ( 

595 self._fallback.stateful_step_count # type: ignore 

596 if stateful_step_count is not_set # type: ignore 

597 else _validate_stateful_step_count(stateful_step_count) 

598 ) 

599 self._report_multiple_bugs = ( 

600 self._fallback.report_multiple_bugs # type: ignore 

601 if report_multiple_bugs is not_set # type: ignore 

602 else _validate_choices( 

603 "report_multiple_bugs", report_multiple_bugs, choices=[True, False] 

604 ) 

605 ) 

606 self._suppress_health_check = ( 

607 self._fallback.suppress_health_check # type: ignore 

608 if suppress_health_check is not_set # type: ignore 

609 else _validate_suppress_health_check(suppress_health_check) 

610 ) 

611 self._deadline = ( 

612 self._fallback.deadline # type: ignore 

613 if deadline is not_set 

614 else _validate_deadline(deadline) 

615 ) 

616 self._print_blob = ( 

617 self._fallback.print_blob # type: ignore 

618 if print_blob is not_set # type: ignore 

619 else _validate_choices("print_blob", print_blob, choices=[True, False]) 

620 ) 

621 self._backend = ( 

622 self._fallback.backend # type: ignore 

623 if backend is not_set # type: ignore 

624 else _validate_backend(backend) 

625 ) 

626 

627 self._in_definition = False 

628 

629 @property 

630 def max_examples(self): 

631 """ 

632 Once this many satisfying examples have been considered without finding any 

633 counter-example, Hypothesis will stop looking. 

634 

635 Note that we might call your test function fewer times if we find a bug early 

636 or can tell that we've exhausted the search space; or more if we discard some 

637 examples due to use of .filter(), assume(), or a few other things that can 

638 prevent the test case from completing successfully. 

639 

640 The default value is chosen to suit a workflow where the test will be part of 

641 a suite that is regularly executed locally or on a CI server, balancing total 

642 running time against the chance of missing a bug. 

643 

644 If you are writing one-off tests, running tens of thousands of examples is 

645 quite reasonable as Hypothesis may miss uncommon bugs with default settings. 

646 For very complex code, we have observed Hypothesis finding novel bugs after 

647 *several million* examples while testing :pypi:`SymPy <sympy>`. 

648 If you are running more than 100k examples for a test, consider using our 

649 :ref:`integration for coverage-guided fuzzing <fuzz_one_input>` - it really 

650 shines when given minutes or hours to run. 

651 

652 The default max examples is ``100``. 

653 """ 

654 return self._max_examples 

655 

656 @property 

657 def derandomize(self): 

658 """ 

659 If True, seed Hypothesis' random number generator using a hash of the test 

660 function, so that every run will test the same set of examples until you 

661 update Hypothesis, Python, or the test function. 

662 

663 This allows you to `check for regressions and look for bugs 

664 <https://blog.nelhage.com/post/two-kinds-of-testing/>`__ using separate 

665 settings profiles - for example running 

666 quick deterministic tests on every commit, and a longer non-deterministic 

667 nightly testing run. 

668 

669 The default is ``False``. If running on CI, the default is ``True`` instead. 

670 """ 

671 return self._derandomize 

672 

673 @property 

674 def database(self): 

675 """ 

676 An instance of |ExampleDatabase| that will be used to save examples to 

677 and load previous examples from. 

678 

679 If not set, a |DirectoryBasedExampleDatabase| is created in the current 

680 working directory under ``.hypothesis/examples``. If this location is 

681 unusable, e.g. due to the lack of read or write permissions, Hypothesis 

682 will emit a warning and fall back to an |InMemoryExampleDatabase|. 

683 

684 If ``None``, no storage will be used. 

685 

686 See the :ref:`database documentation <database>` for a list of database 

687 classes, and how to define custom database classes. 

688 """ 

689 from hypothesis.database import _db_for_path 

690 

691 # settings.database has two conflicting requirements: 

692 # * The default settings should respect changes to set_hypothesis_home_dir 

693 # in-between accesses 

694 # * `s.database is s.database` should be true, except for the default settings 

695 # 

696 # We therefore cache s.database for everything except the default settings, 

697 # which always recomputes dynamically. 

698 if self._fallback is None: 

699 # if self._fallback is None, we are the default settings, at which point 

700 # we should recompute the database dynamically 

701 assert self._database is not_set 

702 return _db_for_path(not_set) 

703 

704 # otherwise, we cache the database 

705 if self._cached_database is None: 

706 self._cached_database = ( 

707 self._fallback.database if self._database is not_set else self._database 

708 ) 

709 return self._cached_database 

710 

711 @property 

712 def verbosity(self): 

713 """ 

714 Control the verbosity level of Hypothesis messages. 

715 

716 To see what's going on while Hypothesis runs your tests, you can turn 

717 up the verbosity setting. 

718 

719 .. code-block:: pycon 

720 

721 >>> from hypothesis import settings, Verbosity 

722 >>> from hypothesis.strategies import lists, integers 

723 >>> @given(lists(integers())) 

724 ... @settings(verbosity=Verbosity.verbose) 

725 ... def f(x): 

726 ... assert not any(x) 

727 ... f() 

728 Trying example: [] 

729 Falsifying example: [-1198601713, -67, 116, -29578] 

730 Shrunk example to [-1198601713] 

731 Shrunk example to [-128] 

732 Shrunk example to [32] 

733 Shrunk example to [1] 

734 [1] 

735 

736 The four levels are |Verbosity.quiet|, |Verbosity.normal|, 

737 |Verbosity.verbose|, and |Verbosity.debug|. |Verbosity.normal| is the 

738 default. For |Verbosity.quiet|, Hypothesis will not print anything out, 

739 not even the final falsifying example. |Verbosity.debug| is basically 

740 |Verbosity.verbose| but a bit more so. You probably don't want it. 

741 

742 If you are using :pypi:`pytest`, you may also need to :doc:`disable 

743 output capturing for passing tests <pytest:how-to/capture-stdout-stderr>` 

744 to see verbose output as tests run. 

745 """ 

746 return self._verbosity 

747 

748 @property 

749 def phases(self): 

750 """ 

751 Control which phases should be run. 

752 

753 Hypothesis divides tests into logically distinct phases. 

754 

755 - |Phase.explicit|: Running explicit examples from |@example|. 

756 - |Phase.reuse|: Running examples from the database which previously failed. 

757 - |Phase.generate|: Generating new random examples. 

758 - |Phase.target|: Mutating examples for :ref:`targeted property-based 

759 testing <targeted>`. Requires |Phase.generate|. 

760 - |Phase.shrink|: Shrinking failing examples. 

761 - |Phase.explain|: Attempting to explain why a failure occurred. 

762 Requires |Phase.shrink|. 

763 

764 Following the first failure, Hypothesis will (usually, depending on 

765 which |Phase| is enabled) track which lines of code are always run on 

766 failing but never on passing inputs. On 3.12+, this uses 

767 :mod:`sys.monitoring`, while 3.11 and earlier uses :func:`python:sys.settrace`. 

768 For python 3.11 and earlier, we therefore automatically disable the explain 

769 phase on PyPy, or if you are using :pypi:`coverage` or a debugger. If 

770 there are no clearly suspicious lines of code, :pep:`we refuse the 

771 temptation to guess <20>`. 

772 

773 After shrinking to a minimal failing example, Hypothesis will try to find 

774 parts of the example -- e.g. separate args to |@given| 

775 -- which can vary freely without changing the result 

776 of that minimal failing example. If the automated experiments run without 

777 finding a passing variation, we leave a comment in the final report: 

778 

779 .. code-block:: python 

780 

781 test_x_divided_by_y( 

782 x=0, # or any other generated value 

783 y=0, 

784 ) 

785 

786 Just remember that the *lack* of an explanation sometimes just means that 

787 Hypothesis couldn't efficiently find one, not that no explanation (or 

788 simpler failing example) exists. 

789 

790 

791 The phases setting provides you with fine grained control over which of 

792 these run, with each phase corresponding to a value on the |Phase| enum. 

793 

794 The phases argument accepts a collection with any subset of these. e.g. 

795 ``settings(phases=[Phase.generate, Phase.shrink])`` will generate new examples 

796 and shrink them, but will not run explicit examples or reuse previous failures, 

797 while ``settings(phases=[Phase.explicit])`` will only run the explicit 

798 examples. 

799 """ 

800 

801 return self._phases 

802 

803 @property 

804 def stateful_step_count(self): 

805 """ 

806 The maximum number of times to call an additional |@rule| method in 

807 :ref:`stateful testing <stateful>` before we give up on finding a bug. 

808 

809 Note that this setting is effectively multiplicative with max_examples, 

810 as each example will run for a maximum of ``stateful_step_count`` steps. 

811 

812 The default stateful step count is ``50``. 

813 """ 

814 return self._stateful_step_count 

815 

816 @property 

817 def report_multiple_bugs(self): 

818 """ 

819 Because Hypothesis runs the test many times, it can sometimes find multiple 

820 bugs in a single run. Reporting all of them at once is usually very useful, 

821 but replacing the exceptions can occasionally clash with debuggers. 

822 If disabled, only the exception with the smallest minimal example is raised. 

823 

824 The default value is ``True``. 

825 """ 

826 return self._report_multiple_bugs 

827 

828 @property 

829 def suppress_health_check(self): 

830 """ 

831 Suppress the given |HealthCheck| exceptions. Those health checks will not 

832 be raised by Hypothesis. To suppress all health checks, you can pass 

833 ``suppress_health_check=list(HealthCheck)``. 

834 

835 Health checks are proactive warnings, not correctness errors, so we 

836 encourage suppressing health checks where you have evaluated they will 

837 not pose a problem, or where you have evaluated that fixing the underlying 

838 issue is not worthwhile. 

839 

840 .. seealso:: 

841 

842 See also the :doc:`/how-to/suppress-healthchecks` how-to. 

843 """ 

844 return self._suppress_health_check 

845 

846 @property 

847 def deadline(self): 

848 """ 

849 The maximum allowed duration of an individual test case, in milliseconds. 

850 You can pass an integer, float, or timedelta. If ``None``, the deadline 

851 is disabled entirely. 

852 

853 We treat the deadline as a soft limit in some cases, where that would 

854 avoid flakiness due to timing variability. 

855 

856 The default deadline is 200 milliseconds. If running on CI, the default is 

857 ``None`` instead. 

858 """ 

859 return self._deadline 

860 

861 @property 

862 def print_blob(self): 

863 """ 

864 If set to ``True``, Hypothesis will print code for failing examples that 

865 can be used with |@reproduce_failure| to reproduce the failing example. 

866 

867 The default value is ``False``. If running on CI, the default is ``True`` instead. 

868 """ 

869 return self._print_blob 

870 

871 @property 

872 def backend(self): 

873 """ 

874 .. warning:: 

875 

876 EXPERIMENTAL AND UNSTABLE - see :ref:`alternative-backends`. 

877 

878 The importable name of a backend which Hypothesis should use to generate 

879 primitive types. We support heuristic-random, solver-based, and fuzzing-based 

880 backends. 

881 """ 

882 return self._backend 

883 

884 def __call__(self, test: T) -> T: 

885 """Make the settings object (self) an attribute of the test. 

886 

887 The settings are later discovered by looking them up on the test itself. 

888 """ 

889 # Aliasing as Any avoids mypy errors (attr-defined) when accessing and 

890 # setting custom attributes on the decorated function or class. 

891 _test: Any = test 

892 

893 # Using the alias here avoids a mypy error (return-value) later when 

894 # ``test`` is returned, because this check results in type refinement. 

895 if not callable(_test): 

896 raise InvalidArgument( 

897 "settings objects can be called as a decorator with @given, " 

898 f"but decorated {test=} is not callable." 

899 ) 

900 if inspect.isclass(test): 

901 from hypothesis.stateful import RuleBasedStateMachine 

902 

903 if issubclass(_test, RuleBasedStateMachine): 

904 attr_name = "_hypothesis_internal_settings_applied" 

905 if getattr(test, attr_name, False): 

906 raise InvalidArgument( 

907 "Applying the @settings decorator twice would " 

908 "overwrite the first version; merge their arguments " 

909 "instead." 

910 ) 

911 setattr(test, attr_name, True) 

912 _test.TestCase.settings = self 

913 return test # type: ignore 

914 else: 

915 raise InvalidArgument( 

916 "@settings(...) can only be used as a decorator on " 

917 "functions, or on subclasses of RuleBasedStateMachine." 

918 ) 

919 if hasattr(_test, "_hypothesis_internal_settings_applied"): 

920 # Can't use _hypothesis_internal_use_settings as an indicator that 

921 # @settings was applied, because @given also assigns that attribute. 

922 descr = get_pretty_function_description(test) 

923 raise InvalidArgument( 

924 f"{descr} has already been decorated with a settings object.\n" 

925 f" Previous: {_test._hypothesis_internal_use_settings!r}\n" 

926 f" This: {self!r}" 

927 ) 

928 

929 _test._hypothesis_internal_use_settings = self 

930 _test._hypothesis_internal_settings_applied = True 

931 return test 

932 

933 def __setattr__(self, name: str, value: object) -> None: 

934 if not name.startswith("_") and not self._in_definition: 

935 raise AttributeError("settings objects are immutable") 

936 return super().__setattr__(name, value) 

937 

938 def __repr__(self) -> str: 

939 bits = sorted( 

940 f"{name}={getattr(self, name)!r}" 

941 for name in all_settings 

942 if (name != "backend" or len(AVAILABLE_PROVIDERS) > 1) # experimental 

943 ) 

944 return "settings({})".format(", ".join(bits)) 

945 

946 def show_changed(self) -> str: 

947 bits = [] 

948 for name in all_settings: 

949 value = getattr(self, name) 

950 if value != getattr(default, name): 

951 bits.append(f"{name}={value!r}") 

952 return ", ".join(sorted(bits, key=len)) 

953 

954 @staticmethod 

955 def register_profile( 

956 name: str, 

957 parent: Optional["settings"] = None, 

958 **kwargs: Any, 

959 ) -> None: 

960 """ 

961 Register a settings object as a settings profile, under the name ``name``. 

962 The ``parent`` and ``kwargs`` arguments to this method are as for 

963 |settings|. 

964 

965 If a settings profile already exists under ``name``, it will be overwritten. 

966 Registering a profile with the same name as the currently active profile 

967 will cause those changes to take effect in the active profile immediately, 

968 and do not require reloading the profile. 

969 

970 Registered settings profiles can be retrieved later by name with 

971 |settings.get_profile|. 

972 """ 

973 check_type(str, name, "name") 

974 # if we just pass the parent and no kwargs, like 

975 # settings.register_profile(settings(max_examples=10)) 

976 # then optimize out the pointless intermediate settings object which 

977 # would just forward everything to the parent. 

978 settings._profiles[name] = ( 

979 parent 

980 if parent is not None and not kwargs 

981 else settings(parent=parent, **kwargs) 

982 ) 

983 if settings._current_profile == name: 

984 settings.load_profile(name) 

985 

986 @staticmethod 

987 def get_profile(name: str) -> "settings": 

988 """ 

989 Returns the settings profile registered under ``name``. If no settings 

990 profile is registered under ``name``, raises |InvalidArgument|. 

991 """ 

992 check_type(str, name, "name") 

993 try: 

994 return settings._profiles[name] 

995 except KeyError: 

996 raise InvalidArgument(f"Profile {name!r} is not registered") from None 

997 

998 @staticmethod 

999 def load_profile(name: str) -> None: 

1000 """ 

1001 Makes the settings profile registered under ``name`` the active profile. 

1002 

1003 If no settings profile is registered under ``name``, raises |InvalidArgument|. 

1004 """ 

1005 check_type(str, name, "name") 

1006 settings._current_profile = name 

1007 default_variable.value = settings.get_profile(name) 

1008 

1009 

1010@contextlib.contextmanager 

1011def local_settings(s: settings) -> Generator[settings, None, None]: 

1012 with default_variable.with_value(s): 

1013 yield s 

1014 

1015 

1016def note_deprecation( 

1017 message: str, *, since: str, has_codemod: bool, stacklevel: int = 0 

1018) -> None: 

1019 if since != "RELEASEDAY": 

1020 date = datetime.date.fromisoformat(since) 

1021 assert datetime.date(2021, 1, 1) <= date 

1022 if has_codemod: 

1023 message += ( 

1024 "\n The `hypothesis codemod` command-line tool can automatically " 

1025 "refactor your code to fix this warning." 

1026 ) 

1027 warnings.warn(HypothesisDeprecationWarning(message), stacklevel=2 + stacklevel) 

1028 

1029 

1030default = settings( 

1031 max_examples=100, 

1032 derandomize=False, 

1033 database=not_set, # type: ignore 

1034 verbosity=Verbosity.normal, 

1035 phases=tuple(Phase), 

1036 stateful_step_count=50, 

1037 report_multiple_bugs=True, 

1038 suppress_health_check=(), 

1039 deadline=duration(milliseconds=200), 

1040 print_blob=False, 

1041 backend="hypothesis", 

1042) 

1043settings.register_profile("default", default) 

1044settings.load_profile("default") 

1045 

1046assert settings.default is not None 

1047 

1048CI = settings( 

1049 derandomize=True, 

1050 deadline=None, 

1051 database=None, 

1052 print_blob=True, 

1053 suppress_health_check=[HealthCheck.too_slow],