diff --git a/README.md b/README.md new file mode 100644 index 0000000000..3071102ccc --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +
+ +
+ +# Hypothesis + +* [Website](https://hypothesis.works/) +* [Documentation](https://hypothesis.readthedocs.io/en/latest/) +* [Source code](https://github.com/hypothesisWorks/hypothesis/) +* [Contributing](https://github.com/HypothesisWorks/hypothesis/blob/master/CONTRIBUTING.rst) +* [Community](https://hypothesis.readthedocs.io/en/latest/community.html) + +Hypothesis is the property-based testing library for Python. A property-based test asserts something for *all* inputs, and lets Hypothesis generate them — including inputs you may not have thought of. + +```python +from hypothesis import given, strategies as st + + +@given(st.lists(st.integers() | st.floats())) +def test_matches_builtin(ls): + assert sorted(ls) == my_sort(ls) +``` + +Additionally, when a property fails, Hypothesis doesn't just report any failing example — it reports the simplest possible one. This makes property-based tests a powerful tool for debugging, as well as testing. + +For instance, + +```python +def my_sort(ls): + return list(reversed(sorted(ls, reverse=True))) +``` + +fails with: + +``` +Falsifying example: test_matches_builtin(ls=[0, math.nan]) +``` + +### Installation + +To install Hypothesis: + +``` +pip install hypothesis +``` + +There are also [optional extras available](https://hypothesis.readthedocs.io/en/latest/packaging.html#other-python-libraries). diff --git a/README.rst b/README.rst deleted file mode 100644 index 83f621aaec..0000000000 --- a/README.rst +++ /dev/null @@ -1,48 +0,0 @@ -========== -Hypothesis -========== - -Hypothesis is a family of testing libraries which let you write tests parametrized -by a source of examples. A Hypothesis implementation then generates simple and -comprehensible examples that make your tests fail. -This simplifies writing your tests and makes them more powerful at the same time, -by letting software automate the boring bits and do them to a higher standard than a human would, -freeing you to focus on the higher level test logic. - -This sort of testing is often called "property-based testing", -and the most widely known implementation of the concept is the Haskell -library `QuickCheck `_, -but Hypothesis differs significantly from QuickCheck and is designed to fit -idiomatically and easily into existing styles of testing that you are used to, -with absolutely no familiarity with Haskell or functional programming needed. - -`Hypothesis for Python `_ is the original implementation, -and the only one that is currently fully production ready and actively maintained. - ------------------------------- -Hypothesis for Other Languages ------------------------------- - -The core ideas of Hypothesis are language agnostic and in principle it is -suitable for any language. We are interested in developing and supporting -implementations for a wide variety of languages, but currently lack the -resources to do so, so our porting efforts are mostly prototypes. - -The two prototype implementations of Hypothesis for other languages are: - -* `Hypothesis for Ruby `_ - is a reasonable start on a port of Hypothesis to Ruby. -* `Hypothesis for Java `_ - is a prototype written some time ago. It's far from feature complete and is - not under active development, but was intended to prove the viability of the - concept. - -Additionally there is a port of the core engine of Hypothesis, Conjecture, to -Rust. It is not feature complete but in the long run we are hoping to move -much of the existing functionality to Rust and rebuild Hypothesis for Python -on top of it, greatly lowering the porting effort to other languages. - -Any or all of these could be turned into full fledged implementations with relatively -little effort (no more than a few months of full time work), but as well as the -initial work this would require someone prepared to provide or fund ongoing -maintenance efforts for them in order to be viable. diff --git a/hypothesis-python/README.md b/hypothesis-python/README.md new file mode 100644 index 0000000000..fa3229ac71 --- /dev/null +++ b/hypothesis-python/README.md @@ -0,0 +1 @@ +The Hypothesis python readme has moved to [the main readme](../README.md)! diff --git a/hypothesis-python/README.rst b/hypothesis-python/README.rst deleted file mode 100644 index 65419d8b70..0000000000 --- a/hypothesis-python/README.rst +++ /dev/null @@ -1,59 +0,0 @@ -========== -Hypothesis -========== - -Hypothesis is an advanced testing library for Python. It lets you write tests which -are parametrized by a source of examples, and then generates simple and comprehensible -examples that make your tests fail. This lets you find more bugs in your code with less -work. - -e.g. - -.. code-block:: python - - @given(st.lists(st.floats(allow_nan=False, allow_infinity=False), min_size=1)) - def test_mean(xs): - assert min(xs) <= mean(xs) <= max(xs) - -.. code-block:: - - Falsifying example: test_mean( - xs=[1.7976321109618856e+308, 6.102390043022755e+303] - ) - -Hypothesis is extremely practical and advances the state of the art of -unit testing by some way. It's easy to use, stable, and powerful. If -you're not using Hypothesis to test your project then you're missing out. - ------------------------- -Quick Start/Installation ------------------------- - -If you just want to get started: - -.. code-block:: - - pip install hypothesis - - ------------------ -Links of interest ------------------ - -The main Hypothesis site is at `hypothesis.works `_, and contains a lot -of good introductory and explanatory material. - -Extensive documentation and examples of usage are `available at readthedocs `_. - -If you want to talk to people about using Hypothesis, `we have both an IRC channel -and a mailing list `_. - -If you want to receive occasional updates about Hypothesis, including useful tips and tricks, there's a -`TinyLetter mailing list to sign up for them `_. - -If you want to contribute to Hypothesis, `instructions are here `_. - -If you want to hear from people who are already using Hypothesis, some of them `have written -about it `_. - -If you want to create a downstream package of Hypothesis, please read `these guidelines for packagers `_. diff --git a/hypothesis-python/setup.py b/hypothesis-python/setup.py index d423503187..5dd5331406 100644 --- a/hypothesis-python/setup.py +++ b/hypothesis-python/setup.py @@ -132,7 +132,7 @@ def local_file(name): "pytest11": ["hypothesispytest = _hypothesis_pytestplugin"], "console_scripts": ["hypothesis = hypothesis.extra.cli:main"], }, - long_description=local_file("README.rst").read_text(encoding="utf-8"), - long_description_content_type="text/x-rst", + long_description=local_file("README.md").read_text(encoding="utf-8"), + long_description_content_type="text/markdown", keywords="python testing fuzzing property-based-testing", ) diff --git a/tooling/setup.py b/tooling/setup.py index 3f84ed61f2..151133a608 100644 --- a/tooling/setup.py +++ b/tooling/setup.py @@ -18,7 +18,7 @@ def local_file(name): SOURCE = local_file("src") -README = local_file("README.rst") +README = local_file("README.md") setuptools.setup( name="hypothesis-tooling",