# First-party extensions¶

Hypothesis has minimal dependencies, to maximise compatibility and make installing Hypothesis as easy as possible.

Our integrations with specific packages are therefore provided by extra modules that need their individual dependencies installed in order to work. You can install these dependencies using the setuptools extra feature as e.g. pip install hypothesis[django]. This will check installation of compatible versions.

You can also just install hypothesis into a project using them, ignore the version constraints, and hope for the best.

In general “Which version is Hypothesis compatible with?” is a hard question to answer and even harder to regularly test. Hypothesis is always tested against the latest compatible version and each package will note the expected compatibility range. If you run into a bug with any of these please specify the dependency version.

There are separate pages for Hypothesis for Django users and Hypothesis for the scientific stack.

$hypothesis --help Usage: hypothesis [OPTIONS] COMMAND [ARGS]... Options: --version Show the version and exit. -h, --help Show this message and exit. Commands: codemod hypothesis codemod refactors deprecated or inefficient code. fuzz [hypofuzz] runs tests with an adaptive coverage-guided fuzzer. write hypothesis write writes property-based tests for you!  This module requires the click package, and provides Hypothesis’ command-line interface, for e.g. ‘ghostwriting’ tests via the terminal. It’s also where HypoFuzz adds the hypothesis fuzz command (learn more about that here). ## hypothesis[codemods]¶ This module provides codemods based on the LibCST library, which can both detect and automatically fix issues with code that uses Hypothesis, including upgrading from deprecated features to our recommended style. You can run the codemods via our CLI: $ hypothesis codemod --help
Usage: hypothesis codemod [OPTIONS] PATH...

hypothesis codemod refactors deprecated or inefficient code.

It adapts python -m libcst.tool, removing many features and config
options which are rarely relevant for this purpose.  If you need more
control, we encourage you to use the libcst CLI directly; if not this one
is easier.

PATH is the file(s) or directories of files to format in place, or "-" to
read from stdin and write to stdout.

Options:
-h, --help  Show this message and exit.


Alternatively you can use python -m libcst.tool, which offers more control at the cost of additional configuration (adding 'hypothesis.extra' to the modules list in .libcst.codemod.yaml) and some issues on Windows.

hypothesis.extra.codemods.refactor(code)[source]

Update a source code string from deprecated to modern Hypothesis APIs.

This may not fix all the deprecation warnings in your code, but we’re confident that it will be easier than doing it all by hand.

We recommend using the CLI, but if you want a Python function here it is.

## hypothesis[dpcontracts]¶

This module provides tools for working with the dpcontracts library, because combining contracts and property-based testing works really well.

It requires dpcontracts >= 0.4.

Tip

For new projects, we recommend using either deal or icontract and icontract-hypothesis over dpcontracts. They’re generally more powerful tools for design-by-contract programming, and have substantially nicer Hypothesis integration too!

hypothesis.extra.dpcontracts.fulfill(contract_func)[source]

Decorate contract_func to reject calls which violate preconditions, and retry them with different arguments.

This is a convenience function for testing internal code that uses dpcontracts, to automatically filter out arguments that would be rejected by the public interface before triggering a contract error.

This can be used as builds(fulfill(func), ...) or in the body of the test e.g. assert fulfill(func)(*args).

## hypothesis[lark]¶

This extra can be used to generate strings matching any context-free grammar, using the Lark parser library.

It currently only supports Lark’s native EBNF syntax, but we plan to extend this to support other common syntaxes such as ANTLR and RFC 5234 ABNF. Lark already supports loading grammars from nearley.js, so you may not have to write your own at all.

Note that as Lark is at version 0.x, this module may break API compatibility in minor releases if supporting the latest version of Lark would otherwise be infeasible. We may also be quite aggressive in bumping the minimum version of Lark, unless someone volunteers to either fund or do the maintenance.

hypothesis.extra.lark.from_lark(grammar, *, start=None, explicit=None)[source]

A strategy for strings accepted by the given context-free grammar.

grammar must be a Lark object, which wraps an EBNF specification. The Lark EBNF grammar reference can be found here.

from_lark will automatically generate strings matching the nonterminal start symbol in the grammar, which was supplied as an argument to the Lark class. To generate strings matching a different symbol, including terminals, you can override this by passing the start argument to from_lark. Note that Lark may remove unreachable productions when the grammar is compiled, so you should probably pass the same value for start to both.

Currently from_lark does not support grammars that need custom lexing. Any lexers will be ignored, and any undefined terminals from the use of %declare will result in generation errors. To define strategies for such terminals, pass a dictionary mapping their name to a corresponding strategy as the explicit argument.

The hypothesmith project includes a strategy for Python source, based on a grammar and careful post-processing.

Example grammars, which may provide a useful starting point for your tests, can be found in the Lark repository and in this third-party collection.

## hypothesis[pytz]¶

This module provides pytz timezones.

You can use this strategy to make and produce timezone-aware values.

hypothesis.extra.pytz.timezones()[source]

Any timezone in the Olsen database, as a pytz tzinfo object.

This strategy minimises to UTC, or the smallest possible fixed offset, and is designed for use with .

## hypothesis[dateutil]¶

This module provides dateutil timezones.

You can use this strategy to make and produce timezone-aware values.

hypothesis.extra.dateutil.timezones()[source]

Any timezone from dateutil.

This strategy minimises to UTC, or the timezone with the smallest offset from UTC as of 2000-01-01, and is designed for use with .

Note that the timezones generated by the strategy may vary depending on the configuration of your machine. See the dateutil documentation for more information.