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 

294# see https://adamj.eu/tech/2020/03/09/detect-if-your-tests-are-running-on-ci 

295# initially from https://github.com/tox-dev/tox/blob/e911788a/src/tox/util/ci.py 

296_CI_VARS = { 

297 "CI": None, # GitHub Actions, Travis CI, and AppVeyor 

298 "TF_BUILD": "true", # Azure Pipelines 

299 "bamboo.buildKey": None, # Bamboo 

300 "BUILDKITE": "true", # Buildkite 

301 "CIRCLECI": "true", # Circle CI 

302 "CIRRUS_CI": "true", # Cirrus CI 

303 "CODEBUILD_BUILD_ID": None, # CodeBuild 

304 "GITHUB_ACTIONS": "true", # GitHub Actions 

305 "GITLAB_CI": None, # GitLab CI 

306 "HEROKU_TEST_RUN_ID": None, # Heroku CI 

307 "TEAMCITY_VERSION": None, # TeamCity 

308} 

309 

310 

311def is_in_ci() -> bool: 

312 return any( 

313 key in os.environ and (value is None or os.environ[key] == value) 

314 for key, value in _CI_VARS.items() 

315 ) 

316 

317 

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

319 

320 

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

322 if value not in choices: 

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

324 raise InvalidArgument(msg) 

325 return value 

326 

327 

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

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

330 if max_examples < 1: 

331 raise InvalidArgument( 

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

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

334 ) 

335 return max_examples 

336 

337 

338def _validate_database( 

339 database: Optional["ExampleDatabase"], 

340) -> Optional["ExampleDatabase"]: 

341 from hypothesis.database import ExampleDatabase 

342 

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

344 return database 

345 raise InvalidArgument( 

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

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

348 "hypothesis.database" 

349 ) 

350 

351 

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

353 phases = tuple(phases) 

354 for phase in phases: 

355 if not isinstance(phase, Phase): 

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

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

358 

359 

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

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

362 if stateful_step_count < 1: 

363 raise InvalidArgument( 

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

365 ) 

366 return stateful_step_count 

367 

368 

369def _validate_suppress_health_check(suppressions): 

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

371 for health_check in suppressions: 

372 if not isinstance(health_check, HealthCheck): 

373 raise InvalidArgument( 

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

375 "is invalid in suppress_health_check." 

376 ) 

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

378 note_deprecation( 

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

380 since="2023-03-15", 

381 has_codemod=False, 

382 stacklevel=2, 

383 ) 

384 return suppressions 

385 

386 

387def _validate_deadline( 

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

389) -> Optional[duration]: 

390 if x is None: 

391 return x 

392 invalid_deadline_error = InvalidArgument( 

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

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

395 "per-test-case deadline." 

396 ) 

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

398 if isinstance(x, bool): 

399 raise invalid_deadline_error 

400 try: 

401 x = duration(milliseconds=x) 

402 except OverflowError: 

403 raise InvalidArgument( 

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

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

406 ) from None 

407 if isinstance(x, datetime.timedelta): 

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

409 raise InvalidArgument( 

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

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

412 ) 

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

414 raise invalid_deadline_error 

415 

416 

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

418 if backend not in AVAILABLE_PROVIDERS: 

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

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

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

422 raise InvalidArgument( 

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

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

425 ) 

426 return backend 

427 

428 

429class settingsMeta(type): 

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

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

432 

433 @property 

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

435 v = default_variable.value 

436 if v is not None: 

437 return v 

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

439 assert settings._current_profile is not None 

440 settings.load_profile(settings._current_profile) 

441 assert default_variable.value is not None 

442 return default_variable.value 

443 

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

445 if name == "default": 

446 raise AttributeError( 

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

448 "consider using settings.load_profile instead." 

449 ) 

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

451 raise AttributeError( 

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

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

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

455 "to decorate your test instead." 

456 ) 

457 super().__setattr__(name, value) 

458 

459 def __repr__(cls): 

460 return "hypothesis.settings" 

461 

462 

463class settings(metaclass=settingsMeta): 

464 """ 

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

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

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

468 |~settings.report_multiple_bugs|, |~settings.suppress_health_check|, 

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

470 

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

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

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

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

475 

476 Attribute inheritance 

477 --------------------- 

478 

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

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

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

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

483 from the currently active settings profile instead. 

484 

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

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

487 currently active settings profile. 

488 

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

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

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

492 settings objects. 

493 

494 .. _builtin-profiles: 

495 

496 Built-in profiles 

497 ----------------- 

498 

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

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

501 

502 By default, the ``default`` profile is active. If the ``CI`` environment 

503 variable is set to any value, the ``ci`` profile is active by default. Hypothesis 

504 also automatically detects various vendor-specific CI environment variables. 

505 

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

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

508 for |settings.max_examples|). 

509 

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

511 

512 .. code-block:: python 

513 

514 default = settings.register_profile( 

515 "default", 

516 max_examples=100, 

517 derandomize=False, 

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

519 verbosity=Verbosity.normal, 

520 phases=tuple(Phase), 

521 stateful_step_count=50, 

522 report_multiple_bugs=True, 

523 suppress_health_check=(), 

524 deadline=duration(milliseconds=200), 

525 print_blob=False, 

526 backend="hypothesis", 

527 ) 

528 

529 ci = settings.register_profile( 

530 "ci", 

531 parent=default, 

532 derandomize=True, 

533 deadline=None, 

534 database=None, 

535 print_blob=True, 

536 suppress_health_check=[HealthCheck.too_slow], 

537 ) 

538 

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

540 

541 .. code-block:: python 

542 

543 # run more examples in CI 

544 settings.register_profile( 

545 "ci", 

546 settings.get_profile("ci"), 

547 max_examples=1000, 

548 ) 

549 """ 

550 

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

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

553 

554 def __init__( 

555 self, 

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

557 *, 

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

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

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

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

562 max_examples: int = not_set, # type: ignore 

563 derandomize: bool = not_set, # type: ignore 

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

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

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

567 stateful_step_count: int = not_set, # type: ignore 

568 report_multiple_bugs: bool = not_set, # type: ignore 

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

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

571 print_blob: bool = not_set, # type: ignore 

572 backend: str = not_set, # type: ignore 

573 ) -> None: 

574 self._in_definition = True 

575 

576 if parent is not None: 

577 check_type(settings, parent, "parent") 

578 if derandomize not in (not_set, False): 

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

580 raise InvalidArgument( 

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

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

583 ) 

584 database = None 

585 

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

587 # the parent (or default settings object) otherwise 

588 self._fallback = parent or settings.default 

589 self._max_examples = ( 

590 self._fallback.max_examples # type: ignore 

591 if max_examples is not_set # type: ignore 

592 else _validate_max_examples(max_examples) 

593 ) 

594 self._derandomize = ( 

595 self._fallback.derandomize # type: ignore 

596 if derandomize is not_set # type: ignore 

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

598 ) 

599 if database is not not_set: # type: ignore 

600 database = _validate_database(database) 

601 self._database = database 

602 self._cached_database = None 

603 self._verbosity = ( 

604 self._fallback.verbosity # type: ignore 

605 if verbosity is not_set # type: ignore 

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

607 ) 

608 self._phases = ( 

609 self._fallback.phases # type: ignore 

610 if phases is not_set # type: ignore 

611 else _validate_phases(phases) 

612 ) 

613 self._stateful_step_count = ( 

614 self._fallback.stateful_step_count # type: ignore 

615 if stateful_step_count is not_set # type: ignore 

616 else _validate_stateful_step_count(stateful_step_count) 

617 ) 

618 self._report_multiple_bugs = ( 

619 self._fallback.report_multiple_bugs # type: ignore 

620 if report_multiple_bugs is not_set # type: ignore 

621 else _validate_choices( 

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

623 ) 

624 ) 

625 self._suppress_health_check = ( 

626 self._fallback.suppress_health_check # type: ignore 

627 if suppress_health_check is not_set # type: ignore 

628 else _validate_suppress_health_check(suppress_health_check) 

629 ) 

630 self._deadline = ( 

631 self._fallback.deadline # type: ignore 

632 if deadline is not_set 

633 else _validate_deadline(deadline) 

634 ) 

635 self._print_blob = ( 

636 self._fallback.print_blob # type: ignore 

637 if print_blob is not_set # type: ignore 

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

639 ) 

640 self._backend = ( 

641 self._fallback.backend # type: ignore 

642 if backend is not_set # type: ignore 

643 else _validate_backend(backend) 

644 ) 

645 

646 self._in_definition = False 

647 

648 @property 

649 def max_examples(self): 

650 """ 

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

652 counter-example, Hypothesis will stop looking. 

653 

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

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

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

657 prevent the test case from completing successfully. 

658 

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

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

661 running time against the chance of missing a bug. 

662 

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

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

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

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

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

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

669 shines when given minutes or hours to run. 

670 

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

672 """ 

673 return self._max_examples 

674 

675 @property 

676 def derandomize(self): 

677 """ 

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

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

680 update Hypothesis, Python, or the test function. 

681 

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

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

684 settings profiles - for example running 

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

686 nightly testing run. 

687 

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

689 """ 

690 return self._derandomize 

691 

692 @property 

693 def database(self): 

694 """ 

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

696 and load previous examples from. 

697 

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

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

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

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

702 

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

704 

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

706 classes, and how to define custom database classes. 

707 """ 

708 from hypothesis.database import _db_for_path 

709 

710 # settings.database has two conflicting requirements: 

711 # * The default settings should respect changes to set_hypothesis_home_dir 

712 # in-between accesses 

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

714 # 

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

716 # which always recomputes dynamically. 

717 if self._fallback is None: 

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

719 # we should recompute the database dynamically 

720 assert self._database is not_set 

721 return _db_for_path(not_set) 

722 

723 # otherwise, we cache the database 

724 if self._cached_database is None: 

725 self._cached_database = ( 

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

727 ) 

728 return self._cached_database 

729 

730 @property 

731 def verbosity(self): 

732 """ 

733 Control the verbosity level of Hypothesis messages. 

734 

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

736 up the verbosity setting. 

737 

738 .. code-block:: pycon 

739 

740 >>> from hypothesis import settings, Verbosity 

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

742 >>> @given(lists(integers())) 

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

744 ... def f(x): 

745 ... assert not any(x) 

746 ... f() 

747 Trying example: [] 

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

749 Shrunk example to [-1198601713] 

750 Shrunk example to [-128] 

751 Shrunk example to [32] 

752 Shrunk example to [1] 

753 [1] 

754 

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

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

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

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

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

760 

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

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

763 to see verbose output as tests run. 

764 """ 

765 return self._verbosity 

766 

767 @property 

768 def phases(self): 

769 """ 

770 Control which phases should be run. 

771 

772 Hypothesis divides tests into logically distinct phases. 

773 

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

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

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

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

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

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

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

781 Requires |Phase.shrink|. 

782 

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

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

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

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

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

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

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

790 temptation to guess <20>`. 

791 

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

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

794 -- which can vary freely without changing the result 

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

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

797 

798 .. code-block:: python 

799 

800 test_x_divided_by_y( 

801 x=0, # or any other generated value 

802 y=0, 

803 ) 

804 

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

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

807 simpler failing example) exists. 

808 

809 

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

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

812 

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

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

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

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

817 examples. 

818 """ 

819 

820 return self._phases 

821 

822 @property 

823 def stateful_step_count(self): 

824 """ 

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

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

827 

828 Note that this setting is effectively multiplicative with max_examples, 

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

830 

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

832 """ 

833 return self._stateful_step_count 

834 

835 @property 

836 def report_multiple_bugs(self): 

837 """ 

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

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

840 but replacing the exceptions can occasionally clash with debuggers. 

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

842 

843 The default value is ``True``. 

844 """ 

845 return self._report_multiple_bugs 

846 

847 @property 

848 def suppress_health_check(self): 

849 """ 

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

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

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

853 

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

855 encourage suppressing health checks where you have evaluated they will 

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

857 issue is not worthwhile. 

858 

859 .. seealso:: 

860 

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

862 """ 

863 return self._suppress_health_check 

864 

865 @property 

866 def deadline(self): 

867 """ 

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

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

870 is disabled entirely. 

871 

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

873 avoid flakiness due to timing variability. 

874 

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

876 ``None`` instead. 

877 """ 

878 return self._deadline 

879 

880 @property 

881 def print_blob(self): 

882 """ 

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

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

885 

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

887 """ 

888 return self._print_blob 

889 

890 @property 

891 def backend(self): 

892 """ 

893 .. warning:: 

894 

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

896 

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

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

899 backends. 

900 """ 

901 return self._backend 

902 

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

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

905 

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

907 """ 

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

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

910 _test: Any = test 

911 

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

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

914 if not callable(_test): 

915 raise InvalidArgument( 

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

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

918 ) 

919 if inspect.isclass(test): 

920 from hypothesis.stateful import RuleBasedStateMachine 

921 

922 if issubclass(_test, RuleBasedStateMachine): 

923 attr_name = "_hypothesis_internal_settings_applied" 

924 if getattr(test, attr_name, False): 

925 raise InvalidArgument( 

926 "Applying the @settings decorator twice would " 

927 "overwrite the first version; merge their arguments " 

928 "instead." 

929 ) 

930 setattr(test, attr_name, True) 

931 _test.TestCase.settings = self 

932 return test 

933 else: 

934 raise InvalidArgument( 

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

936 "functions, or on subclasses of RuleBasedStateMachine." 

937 ) 

938 if hasattr(_test, "_hypothesis_internal_settings_applied"): 

939 # Can't use _hypothesis_internal_use_settings as an indicator that 

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

941 descr = get_pretty_function_description(test) 

942 raise InvalidArgument( 

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

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

945 f" This: {self!r}" 

946 ) 

947 

948 _test._hypothesis_internal_use_settings = self 

949 _test._hypothesis_internal_settings_applied = True 

950 return test 

951 

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

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

954 raise AttributeError("settings objects are immutable") 

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

956 

957 def __repr__(self) -> str: 

958 bits = sorted( 

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

960 for name in all_settings 

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

962 ) 

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

964 

965 def show_changed(self) -> str: 

966 bits = [] 

967 for name in all_settings: 

968 value = getattr(self, name) 

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

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

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

972 

973 @staticmethod 

974 def register_profile( 

975 name: str, 

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

977 **kwargs: Any, 

978 ) -> None: 

979 """ 

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

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

982 |settings|. 

983 

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

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

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

987 and do not require reloading the profile. 

988 

989 Registered settings profiles can be retrieved later by name with 

990 |settings.get_profile|. 

991 """ 

992 check_type(str, name, "name") 

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

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

995 # then optimize out the pointless intermediate settings object which 

996 # would just forward everything to the parent. 

997 settings._profiles[name] = ( 

998 parent 

999 if parent is not None and not kwargs 

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

1001 ) 

1002 if settings._current_profile == name: 

1003 settings.load_profile(name) 

1004 

1005 @staticmethod 

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

1007 """ 

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

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

1010 """ 

1011 check_type(str, name, "name") 

1012 try: 

1013 return settings._profiles[name] 

1014 except KeyError: 

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

1016 

1017 @staticmethod 

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

1019 """ 

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

1021 

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

1023 """ 

1024 check_type(str, name, "name") 

1025 settings._current_profile = name 

1026 default_variable.value = settings.get_profile(name) 

1027 

1028 

1029@contextlib.contextmanager 

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

1031 with default_variable.with_value(s): 

1032 yield s 

1033 

1034 

1035def note_deprecation( 

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

1037) -> None: 

1038 if since != "RELEASEDAY": 

1039 date = datetime.date.fromisoformat(since) 

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

1041 if has_codemod: 

1042 message += ( 

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

1044 "refactor your code to fix this warning." 

1045 ) 

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

1047 

1048 

1049default = settings( 

1050 max_examples=100, 

1051 derandomize=False, 

1052 database=not_set, # type: ignore 

1053 verbosity=Verbosity.normal, 

1054 phases=tuple(Phase),