python hypothesis dictionary

hypothesis 6.108.8

pip install hypothesis Copy PIP instructions

Released: Aug 4, 2024

A library for property-based testing

Verified details

Maintainers.

Unverified details

Project links.

• Documentation

GitHub Statistics

• Open issues:

License: Mozilla Public License 2.0 (MPL 2.0) (MPL-2.0)

Author: David R. MacIver and Zac Hatfield-Dodds

Tags python, testing, fuzzing, property-based-testing

Requires: Python >=3.8

Provides-Extra: all , cli , codemods , crosshair , dateutil , django , dpcontracts , ghostwriter , lark , numpy , pandas , pytest , pytz , redis , zoneinfo

Classifiers

• 5 - Production/Stable
• OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
• Microsoft :: Windows
• Python :: 3
• Python :: 3 :: Only
• Python :: 3.8
• Python :: 3.9
• Python :: 3.10
• Python :: 3.11
• Python :: 3.12
• Python :: Implementation :: CPython
• Python :: Implementation :: PyPy
• Education :: Testing
• Software Development :: Testing

Project description

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.

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:

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 .

Project details

Release history release notifications | rss feed.

Aug 4, 2024

Jul 28, 2024

Jul 22, 2024

Jul 15, 2024

Jul 14, 2024

Jul 13, 2024

Jul 12, 2024

Jul 7, 2024

Jul 4, 2024

Jun 29, 2024

Jun 25, 2024

Jun 24, 2024

Jun 14, 2024

Jun 5, 2024

May 29, 2024

May 23, 2024

May 22, 2024

May 15, 2024

May 13, 2024

May 12, 2024

May 10, 2024

May 6, 2024

May 5, 2024

May 4, 2024

Apr 28, 2024

Apr 8, 2024

Mar 31, 2024

Mar 24, 2024

Mar 23, 2024

Mar 20, 2024

Mar 19, 2024

Mar 18, 2024

Mar 14, 2024

Mar 12, 2024

Mar 11, 2024

Mar 10, 2024

Mar 9, 2024

Mar 4, 2024

Feb 29, 2024

Feb 27, 2024

Feb 25, 2024

Feb 24, 2024

Feb 22, 2024

Feb 20, 2024

Feb 18, 2024

Feb 15, 2024

Feb 14, 2024

Feb 12, 2024

Feb 8, 2024

Feb 5, 2024

Feb 4, 2024

Feb 3, 2024

Jan 31, 2024

Jan 30, 2024

Jan 27, 2024

Jan 25, 2024

Jan 23, 2024

Jan 22, 2024

Jan 21, 2024

Jan 18, 2024

Jan 17, 2024

Jan 16, 2024

Jan 15, 2024

Jan 13, 2024

Jan 12, 2024

Jan 11, 2024

Jan 10, 2024

Jan 8, 2024

Dec 27, 2023

Dec 16, 2023

Dec 10, 2023

Dec 8, 2023

Nov 27, 2023

Nov 20, 2023

Nov 19, 2023

Nov 16, 2023

Nov 13, 2023

Nov 5, 2023

Oct 16, 2023

Oct 15, 2023

Oct 12, 2023

Oct 6, 2023

Oct 1, 2023

Sep 25, 2023

Sep 18, 2023

Sep 17, 2023

Sep 16, 2023

Sep 10, 2023

Sep 6, 2023

Sep 5, 2023

Sep 4, 2023

Sep 3, 2023

Sep 1, 2023

Aug 28, 2023

Aug 20, 2023

Aug 18, 2023

Aug 12, 2023

Aug 8, 2023

Aug 6, 2023

Aug 5, 2023

Jul 20, 2023

Jul 15, 2023

Jul 11, 2023

Jul 10, 2023

Jul 6, 2023

Jun 27, 2023

Jun 26, 2023

Jun 22, 2023

Jun 19, 2023

Jun 17, 2023

Jun 15, 2023

Jun 13, 2023

Jun 12, 2023

Jun 11, 2023

Jun 9, 2023

Jun 4, 2023

May 31, 2023

May 30, 2023

May 27, 2023

May 26, 2023

May 14, 2023

May 4, 2023

Apr 30, 2023

Apr 28, 2023

Apr 26, 2023

Apr 27, 2023

Apr 25, 2023

Apr 24, 2023

Apr 19, 2023

Apr 16, 2023

Apr 7, 2023

Apr 3, 2023

Mar 27, 2023

Mar 16, 2023

Mar 15, 2023

Feb 17, 2023

Feb 12, 2023

Feb 9, 2023

Feb 5, 2023

Feb 4, 2023

Feb 3, 2023

Feb 2, 2023

Jan 27, 2023

Jan 26, 2023

Jan 24, 2023

Jan 23, 2023

Jan 20, 2023

Jan 14, 2023

Jan 8, 2023

Jan 7, 2023

Jan 6, 2023

Dec 11, 2022

Dec 4, 2022

Dec 2, 2022

Nov 30, 2022

Nov 26, 2022

Nov 19, 2022

Nov 14, 2022

Oct 28, 2022

Oct 17, 2022

Oct 10, 2022

Oct 5, 2022

Oct 2, 2022

Sep 29, 2022

Sep 18, 2022

Sep 5, 2022

Aug 20, 2022

Aug 12, 2022

Aug 10, 2022

Aug 2, 2022

Jul 25, 2022

Jul 22, 2022

Jul 19, 2022

Jul 18, 2022

Jul 17, 2022

Jul 9, 2022

Jul 5, 2022

Jul 4, 2022

Jul 3, 2022

Jun 29, 2022

Jun 27, 2022

Jun 25, 2022

Jun 23, 2022

Jun 15, 2022

Jun 12, 2022

Jun 10, 2022

Jun 7, 2022

Jun 2, 2022

Jun 1, 2022

May 25, 2022

May 19, 2022

May 18, 2022

May 15, 2022

May 11, 2022

May 3, 2022

May 1, 2022

Apr 30, 2022

Apr 29, 2022

Apr 27, 2022

Apr 22, 2022

Apr 21, 2022

Apr 18, 2022

Apr 16, 2022

Apr 13, 2022

Apr 12, 2022

Apr 10, 2022

Apr 9, 2022

Apr 1, 2022

Mar 29, 2022

Mar 27, 2022

Mar 26, 2022

Mar 17, 2022

Mar 7, 2022

Mar 3, 2022

Mar 1, 2022

Feb 26, 2022

Feb 21, 2022

Feb 18, 2022

Feb 13, 2022

Jan 31, 2022

Jan 19, 2022

Jan 17, 2022

Jan 8, 2022

Jan 5, 2022

Dec 31, 2021

Dec 30, 2021

Dec 23, 2021

Dec 15, 2021

Dec 14, 2021

Dec 11, 2021

Dec 10, 2021

Dec 9, 2021

Dec 5, 2021

Dec 3, 2021

Dec 2, 2021

Nov 29, 2021

Nov 28, 2021

Nov 26, 2021

Nov 22, 2021

Nov 21, 2021

Nov 19, 2021

Nov 18, 2021

Nov 16, 2021

Nov 15, 2021

Nov 13, 2021

Nov 5, 2021

Nov 1, 2021

Oct 23, 2021

Oct 20, 2021

Oct 18, 2021

Oct 8, 2021

Sep 29, 2021

Sep 26, 2021

Sep 24, 2021

Sep 19, 2021

Sep 16, 2021

Sep 15, 2021

Sep 13, 2021

Sep 11, 2021

Sep 10, 2021

Sep 9, 2021

Sep 8, 2021

Sep 6, 2021

Aug 31, 2021

Aug 30, 2021

Aug 29, 2021

Aug 27, 2021

Aug 22, 2021

Aug 20, 2021

Aug 16, 2021

Aug 14, 2021

Aug 7, 2021

Jul 27, 2021

Jul 26, 2021

Jul 18, 2021

Jul 12, 2021

Jul 2, 2021

Jun 9, 2021

Jun 4, 2021

Jun 3, 2021

Jun 2, 2021

May 30, 2021

May 28, 2021

May 27, 2021

May 26, 2021

May 24, 2021

May 23, 2021

May 20, 2021

May 18, 2021

May 17, 2021

May 6, 2021

Apr 26, 2021

Apr 17, 2021

Apr 15, 2021

Apr 12, 2021

Apr 11, 2021

Apr 7, 2021

Apr 6, 2021

Apr 5, 2021

Apr 1, 2021

Mar 28, 2021

Mar 27, 2021

Mar 14, 2021

Mar 11, 2021

Mar 10, 2021

Mar 9, 2021

Mar 7, 2021

Mar 4, 2021

Mar 2, 2021

Feb 28, 2021

Feb 26, 2021

Feb 25, 2021

Feb 24, 2021

Feb 20, 2021

Feb 12, 2021

Jan 31, 2021

Jan 29, 2021

Jan 27, 2021

Jan 23, 2021

Jan 14, 2021

Jan 13, 2021

Jan 8, 2021

Jan 7, 2021

Jan 6, 2021

Jan 5, 2021

Jan 4, 2021

Jan 3, 2021

Jan 2, 2021

Jan 1, 2021

Dec 24, 2020

Dec 11, 2020

Dec 10, 2020

Dec 9, 2020

Dec 5, 2020

Nov 28, 2020

Nov 18, 2020

Nov 8, 2020

Nov 3, 2020

Oct 30, 2020

Oct 26, 2020

Oct 24, 2020

Oct 20, 2020

Oct 15, 2020

Oct 14, 2020

Oct 7, 2020

Oct 3, 2020

Oct 2, 2020

Sep 25, 2020

Sep 24, 2020

Sep 21, 2020

Sep 15, 2020

Sep 14, 2020

Sep 11, 2020

Sep 9, 2020

Sep 7, 2020

Sep 6, 2020

Sep 4, 2020

Aug 30, 2020

Aug 28, 2020

Aug 27, 2020

Aug 24, 2020

Aug 20, 2020

Aug 19, 2020

Aug 17, 2020

Aug 16, 2020

Aug 14, 2020

Aug 13, 2020

Aug 12, 2020

Aug 10, 2020

Aug 4, 2020

Aug 3, 2020

Jul 31, 2020

Jul 29, 2020

Jul 27, 2020

Jul 26, 2020

Jul 25, 2020

Jul 23, 2020

Jul 21, 2020

Jul 18, 2020

Jul 17, 2020

Jul 15, 2020

Jul 13, 2020

Jul 12, 2020

Jun 30, 2020

Jun 27, 2020

Jun 26, 2020

Jun 25, 2020

Jun 22, 2020

Jun 21, 2020

Jun 19, 2020

Jun 10, 2020

May 27, 2020

May 21, 2020

May 19, 2020

May 13, 2020

May 12, 2020

May 10, 2020

May 7, 2020

May 4, 2020

Apr 24, 2020

Apr 22, 2020

Apr 19, 2020

Apr 18, 2020

Apr 16, 2020

Apr 15, 2020

Apr 14, 2020

Apr 12, 2020

Mar 24, 2020

Mar 23, 2020

Mar 19, 2020

Mar 18, 2020

Feb 29, 2020

Feb 16, 2020

Feb 14, 2020

Feb 13, 2020

Feb 7, 2020

Feb 6, 2020

Feb 1, 2020

Jan 30, 2020

Jan 26, 2020

Jan 21, 2020

Jan 19, 2020

Jan 12, 2020

Jan 11, 2020

Jan 9, 2020

Jan 6, 2020

Jan 3, 2020

Jan 1, 2020

Dec 29, 2019

Dec 28, 2019

Dec 22, 2019

Dec 21, 2019

Dec 19, 2019

Dec 18, 2019

Dec 17, 2019

Dec 16, 2019

Dec 15, 2019

Dec 11, 2019

Dec 9, 2019

Dec 7, 2019

Dec 5, 2019

Dec 2, 2019

Dec 1, 2019

Nov 29, 2019

Nov 28, 2019

Nov 27, 2019

Nov 26, 2019

Nov 25, 2019

Nov 24, 2019

Nov 23, 2019

Nov 22, 2019

Nov 20, 2019

Nov 12, 2019

Nov 11, 2019

Nov 8, 2019

Nov 7, 2019

Nov 6, 2019

Nov 5, 2019

Nov 4, 2019

Nov 3, 2019

Nov 2, 2019

Nov 1, 2019

Oct 30, 2019

Oct 27, 2019

Oct 21, 2019

Oct 17, 2019

Oct 16, 2019

Oct 14, 2019

Oct 9, 2019

Oct 7, 2019

Oct 4, 2019

Oct 2, 2019

Oct 1, 2019

Sep 28, 2019

Sep 20, 2019

Sep 17, 2019

Sep 9, 2019

Sep 4, 2019

Aug 23, 2019

Aug 21, 2019

Aug 20, 2019

Aug 5, 2019

Jul 30, 2019

Jul 29, 2019

Jul 28, 2019

Jul 24, 2019

Jul 14, 2019

Jul 12, 2019

Jul 11, 2019

Jul 8, 2019

Jul 7, 2019

Jul 5, 2019

Jul 4, 2019

Jul 3, 2019

Jun 26, 2019

Jun 23, 2019

Jun 21, 2019

Jun 7, 2019

Jun 6, 2019

Jun 4, 2019

May 29, 2019

May 28, 2019

May 26, 2019

May 19, 2019

May 16, 2019

May 9, 2019

May 8, 2019

May 7, 2019

May 6, 2019

May 5, 2019

Apr 30, 2019

Apr 29, 2019

Apr 24, 2019

Apr 19, 2019

Apr 16, 2019

Apr 12, 2019

Apr 9, 2019

Apr 7, 2019

Apr 5, 2019

Apr 3, 2019

Mar 31, 2019

Mar 30, 2019

Mar 19, 2019

Mar 18, 2019

Mar 15, 2019

Mar 13, 2019

Mar 12, 2019

Mar 11, 2019

Mar 9, 2019

Mar 6, 2019

Mar 4, 2019

Mar 3, 2019

Mar 1, 2019

Feb 28, 2019

Feb 27, 2019

Feb 25, 2019

Feb 24, 2019

Feb 23, 2019

Feb 22, 2019

Feb 21, 2019

Feb 19, 2019

Feb 18, 2019

Feb 15, 2019

Feb 14, 2019

Feb 12, 2019

Feb 11, 2019

Feb 10, 2019

Feb 8, 2019

Feb 6, 2019

Feb 5, 2019

Feb 3, 2019

Feb 2, 2019

Jan 25, 2019

Jan 24, 2019

Jan 23, 2019

Jan 22, 2019

Jan 16, 2019

Jan 14, 2019

Jan 11, 2019

Jan 10, 2019

Jan 9, 2019

Jan 8, 2019

Jan 7, 2019

Jan 6, 2019

Jan 4, 2019

Jan 3, 2019

Jan 2, 2019

Dec 31, 2018

Dec 30, 2018

Dec 29, 2018

Dec 28, 2018

Dec 21, 2018

Dec 20, 2018

Dec 19, 2018

Dec 18, 2018

Dec 17, 2018

Dec 13, 2018

Dec 12, 2018

Dec 11, 2018

Dec 8, 2018

Oct 29, 2018

Oct 27, 2018

Oct 25, 2018

Oct 23, 2018

Oct 22, 2018

Oct 18, 2018

Oct 16, 2018

Oct 11, 2018

Oct 10, 2018

Oct 9, 2018

Oct 8, 2018

Oct 3, 2018

Oct 1, 2018

Sep 30, 2018

Sep 27, 2018

Sep 26, 2018

Sep 25, 2018

Sep 24, 2018

Sep 18, 2018

Sep 17, 2018

Sep 16, 2018

Sep 15, 2018

Sep 14, 2018

Sep 9, 2018

Sep 8, 2018

Sep 3, 2018

Sep 1, 2018

Aug 30, 2018

Aug 29, 2018

Aug 28, 2018

Aug 27, 2018

Aug 23, 2018

Aug 21, 2018

Aug 20, 2018

Aug 19, 2018

Aug 18, 2018

Aug 15, 2018

Aug 14, 2018

Aug 10, 2018

Aug 9, 2018

Aug 8, 2018

Aug 6, 2018

Aug 5, 2018

Aug 3, 2018

Aug 2, 2018

Aug 1, 2018

Jul 31, 2018

Jul 30, 2018

Jul 28, 2018

Jul 26, 2018

Jul 24, 2018

Jul 23, 2018

Jul 22, 2018

Jul 20, 2018

Jul 19, 2018

Jul 8, 2018

Jul 5, 2018

Jul 4, 2018

Jul 3, 2018

Jun 30, 2018

Jun 27, 2018

Jun 26, 2018

Jun 24, 2018

Jun 20, 2018

Jun 19, 2018

Jun 18, 2018

Jun 16, 2018

Jun 14, 2018

Jun 13, 2018

May 20, 2018

May 16, 2018

May 11, 2018

May 10, 2018

May 9, 2018

Apr 22, 2018

Apr 21, 2018

Apr 20, 2018

Apr 17, 2018

Apr 14, 2018

Apr 13, 2018

Apr 12, 2018

Apr 11, 2018

Apr 6, 2018

Apr 5, 2018

Apr 4, 2018

Apr 1, 2018

Mar 30, 2018

Mar 29, 2018

Mar 24, 2018

Mar 20, 2018

Mar 19, 2018

Mar 15, 2018

Mar 12, 2018

Mar 5, 2018

Mar 2, 2018

Mar 1, 2018

Feb 26, 2018

Feb 25, 2018

Feb 23, 2018

Feb 18, 2018

Feb 17, 2018

Feb 13, 2018

Feb 5, 2018

Jan 27, 2018

Jan 24, 2018

Jan 23, 2018

Jan 22, 2018

Jan 21, 2018

Jan 20, 2018

Jan 13, 2018

Jan 8, 2018

Jan 7, 2018

Jan 6, 2018

Jan 4, 2018

Jan 2, 2018

Dec 23, 2017

Dec 21, 2017

Dec 20, 2017

Dec 17, 2017

Dec 12, 2017

Dec 10, 2017

Dec 9, 2017

Dec 6, 2017

Dec 4, 2017

Dec 2, 2017

Dec 1, 2017

Nov 29, 2017

Nov 28, 2017

Nov 23, 2017

Nov 22, 2017

Nov 21, 2017

Nov 18, 2017

Nov 12, 2017

Nov 10, 2017

Nov 6, 2017

Nov 2, 2017

Nov 1, 2017

Oct 16, 2017

Oct 15, 2017

Oct 13, 2017

Oct 9, 2017

Oct 8, 2017

Oct 6, 2017

Sep 30, 2017

Sep 29, 2017

Sep 27, 2017

Sep 25, 2017

Sep 24, 2017

Sep 22, 2017

Sep 19, 2017

Sep 18, 2017

Sep 16, 2017

Sep 15, 2017

Sep 14, 2017

Sep 13, 2017

Sep 12, 2017

Sep 11, 2017

Sep 6, 2017

Sep 5, 2017

Sep 1, 2017

Aug 31, 2017

Aug 29, 2017

Aug 28, 2017

Aug 26, 2017

Aug 25, 2017

Aug 24, 2017

Aug 23, 2017

Aug 22, 2017

Aug 21, 2017

Aug 20, 2017

Aug 18, 2017

Aug 17, 2017

Aug 16, 2017

Aug 15, 2017

Aug 13, 2017

Aug 7, 2017

Aug 4, 2017

Aug 3, 2017

Aug 2, 2017

Jul 23, 2017

Jul 20, 2017

Jul 16, 2017

Jul 7, 2017

Jun 19, 2017

Jun 17, 2017

Jun 11, 2017

Jun 10, 2017

May 28, 2017

May 23, 2017

May 22, 2017

May 19, 2017

May 17, 2017

May 9, 2017

Apr 26, 2017

Apr 23, 2017

Apr 22, 2017

Apr 21, 2017

Mar 20, 2017

Dec 20, 2016

Oct 31, 2016

Oct 5, 2016

Sep 26, 2016

Sep 23, 2016

Sep 22, 2016

Jul 13, 2016

Jul 7, 2016

May 27, 2016

May 24, 2016

May 1, 2016

Apr 30, 2016

Apr 29, 2016

Mar 6, 2016

Feb 25, 2016

Feb 24, 2016

Feb 23, 2016

Feb 18, 2016

Feb 17, 2016

Jan 10, 2016

Jan 9, 2016

Dec 22, 2015

Dec 21, 2015

Dec 16, 2015

Dec 15, 2015

Dec 8, 2015

Nov 24, 2015

Nov 1, 2015

Oct 29, 2015

Oct 18, 2015

Sep 27, 2015

Sep 23, 2015

Sep 16, 2015

Aug 31, 2015

Aug 26, 2015

Aug 22, 2015

Aug 19, 2015

Aug 4, 2015

Aug 3, 2015

Jul 27, 2015

Jul 24, 2015

Jul 21, 2015

Jul 20, 2015

Jul 18, 2015

Jul 17, 2015

Jul 16, 2015

Jul 10, 2015

Jun 29, 2015

Jun 8, 2015

May 21, 2015

May 14, 2015

May 5, 2015

May 4, 2015

Apr 22, 2015

Apr 15, 2015

Apr 14, 2015

Apr 7, 2015

Apr 6, 2015

Mar 27, 2015

Mar 26, 2015

Mar 25, 2015

Mar 23, 2015

Mar 22, 2015

Mar 21, 2015

Mar 20, 2015

Mar 14, 2015

Feb 10, 2015

Feb 5, 2015

Feb 4, 2015

Feb 3, 2015

Jan 21, 2015

Jan 16, 2015

Jan 13, 2015

Jan 12, 2015

Jan 8, 2015

Jan 7, 2015

Dec 14, 2013

May 3, 2013

Mar 26, 2013

Mar 24, 2013

Mar 23, 2013

Mar 13, 2013

Mar 12, 2013

Mar 10, 2013

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages .

Source Distribution

Uploaded Aug 4, 2024 Source

Built Distribution

Uploaded Aug 4, 2024 Python 3

Hashes for hypothesis-6.108.8.tar.gz

Hashes for hypothesis-6.108.8-py3-none-any.whl

• português (Brasil)

Supported by

Table of Contents

Testing your python code with hypothesis, installing & using hypothesis, a quick example, understanding hypothesis, using hypothesis strategies, filtering and mapping strategies, composing strategies, constraints & satisfiability, writing reusable strategies with functions.

• @composite: Declarative Strategies
• @example: Explicitly Testing Certain Values

Hypothesis Example: Roman Numeral Converter

I can think of a several Python packages that greatly improved the quality of the software I write. Two of them are pytest and hypothesis . The former adds an ergonomic framework for writing tests and fixtures and a feature-rich test runner. The latter adds property-based testing that can ferret out all but the most stubborn bugs using clever algorithms, and that’s the package we’ll explore in this course.

In an ordinary test you interface with the code you want to test by generating one or more inputs to test against, and then you validate that it returns the right answer. But that, then, raises a tantalizing question: what about all the inputs you didn’t test? Your code coverage tool may well report 100% test coverage, but that does not, ipso facto , mean the code is bug-free.

One of the defining features of Hypothesis is its ability to generate test cases automatically in a manner that is:

Repeated invocations of your tests result in reproducible outcomes, even though Hypothesis does use randomness to generate the data.

You are given a detailed answer that explains how your test failed and why it failed. Hypothesis makes it clear how you, the human, can reproduce the invariant that caused your test to fail.

You can refine its strategies and tell it where or what it should or should not search for. At no point are you compelled to modify your code to suit the whims of Hypothesis if it generates nonsensical data.

So let’s look at how Hypothesis can help you discover errors in your code.

You can install hypothesis by typing pip install hypothesis . It has few dependencies of its own, and should install and run everywhere.

Hypothesis plugs into pytest and unittest by default, so you don’t have to do anything to make it work with it. In addition, Hypothesis comes with a CLI tool you can invoke with hypothesis . But more on that in a bit.

I will use pytest throughout to demonstrate Hypothesis, but it works equally well with the builtin unittest module.

Before I delve into the details of Hypothesis, let’s start with a simple example: a naive CSV writer and reader. A topic that seems simple enough: how hard is it to separate fields of data with a comma and then read it back in later?

But of course CSV is frighteningly hard to get right. The US and UK use '.' as a decimal separator, but in large parts of the world they use ',' which of course results in immediate failure. So then you start quoting things, and now you need a state machine that can distinguish quoted from unquoted; and what about nested quotes, etc.

The naive CSV reader and writer is an excellent stand-in for any number of complex projects where the requirements outwardly seem simple but there lurks a large number of edge cases that you must take into account.

Here the writer simply string quotes each field before joining them together with ',' . The reader does the opposite: it assumes each field is quoted after it is split by the comma.

A naive roundtrip pytest proves the code “works”:

And evidently so:

And for a lot of code that’s where the testing would begin and end. A couple of lines of code to test a couple of functions that outwardly behave in a manner that anybody can read and understand. Now let’s look at what a Hypothesis test would look like, and what happens when we run it:

At first blush there’s nothing here that you couldn’t divine the intent of, even if you don’t know Hypothesis. I’m asking for the argument fields to have a list ranging from one element of generated text up to ten. Aside from that, the test operates in exactly the same manner as before.

Now watch what happens when I run the test:

Hypothesis quickly found an example that broke our code. As it turns out, a list of [','] breaks our code. We get two fields back after round-tripping the code through our CSV writer and reader — uncovering our first bug.

In a nutshell, this is what Hypothesis does. But let’s look at it in detail.

Simply put, Hypothesis generates data using a number of configurable strategies . Strategies range from simple to complex. A simple strategy may generate bools; another integers. You can combine strategies to make larger ones, such as lists or dicts that match certain patterns or structures you want to test. You can clamp their outputs based on certain constraints, like only positive integers or strings of a certain length. You can also write your own strategies if you have particularly complex requirements.

Strategies are the gateway to property-based testing and are a fundamental part of how Hypothesis works. You can find a detailed list of all the strategies in the Strategies reference of their documentation or in the hypothesis.strategies module.

The best way to get a feel for what each strategy does in practice is to import them from the hypothesis.strategies module and call the example() method on an instance:

You may have noticed that the floats example included inf in the list. By default, all strategies will – where feasible – attempt to test all legal (but possibly obscure) forms of values you can generate of that type. That is particularly important as corner cases like inf or NaN are legal floating-point values but, I imagine, not something you’d ordinarily test against yourself.

And that’s one pillar of how Hypothesis tries to find bugs in your code: by testing edge cases that you would likely miss yourself. If you ask it for a text() strategy you’re as likely to be given Western characters as you are a mishmash of unicode and escape-encoded garbage. Understanding why Hypothesis generates the examples it does is a useful way to think about how your code may interact data it has no control over.

Now if it were simply generating text or numbers from an inexhaustible source of numbers or strings, it wouldn’t catch as many errors as it actually does . The reason for that is that each test you write is subjected to a battery of examples drawn from the strategies you’ve designed. If a test case fails, it’s put aside and tested again but with a reduced subset of inputs, if possible. In Hypothesis it’s known as shrinking the search space to try and find the smallest possible result that will cause your code to fail. So instead of a 10,000-length string, if it can find one that’s only 3 or 4, it will try to show that to you instead.

You can tell Hypothesis to filter or map the examples it draws to further reduce them if the strategy does not meet your requirements:

Here I ask for integers where the number is greater than 0 and is evenly divisible by 8. Hypothesis will then attempt to generate examples that meets the constraints you have imposed on it.

You can also map , which works in much the same way as filter. Here I’m asking for lowercase ASCII and then uppercasing them:

Having said that, using either when you don’t have to (I could have asked for uppercase ASCII characters to begin with) is likely to result in slower strategies.

A third option, flatmap , lets you build strategies from strategies; but that deserves closer scrutiny, so I’ll talk about it later.

You can tell Hypothesis to pick one of a number of strategies by composing strategies with | or st.one_of() :

An essential feature when you have to draw from multiple sources of examples for a single data point.

When you ask Hypothesis to draw an example it takes into account the constraints you may have imposed on it: only positive integers; only lists of numbers that add up to exactly 100; any filter() calls you may have applied; and so on. Those are constraints. You’re taking something that was once unbounded (with respect to the strategy you’re drawing an example from, that is) and introducing additional limitations that constrain the possible range of values it can give you.

But consider what happens if I pass filters that will yield nothing at all:

At some point Hypothesis will give up and declare it cannot find anything that satisfies that strategy and its constraints.

Hypothesis gives up after a while if it’s not able to draw an example. Usually that indicates an invariant in the constraints you’ve placed that makes it hard or impossible to draw examples from. In the example above, I asked for numbers that are simultaneously below zero and greater than zero, which is an impossible request.

As you can see, the strategies are simple functions, and they behave as such. You can therefore refactor each strategy into reusable patterns:

The benefit of this approach is that if you discover edge cases that Hypothesis does not account for, you can update the pattern in one place and observe its effects on your code. It’s functional and composable.

One caveat of this approach is that you cannot draw examples and expect Hypothesis to behave correctly. So I don’t recommend you call example() on a strategy only to pass it into another strategy.

For that, you want the @composite decorator.

@composite : Declarative Strategies

If the previous approach is unabashedly functional in nature, this approach is imperative.

The @composite decorator lets you write imperative Python code instead. If you cannot easily structure your strategy with the built-in ones, or if you require more granular control over the values it emits, you should consider the @composite strategy.

Instead of returning a compound strategy object like you would above, you instead draw examples using a special function you’re given access to in the decorated function.

This example draws two randomized names and returns them as a tuple:

Note that the @composite decorator passes in a special draw callable that you must use to draw samples from. You cannot – well, you can , but you shouldn’t – use the example() method on the strategy object you get back. Doing so will break Hypothesis’s ability to synthesize test cases properly.

Because the code is imperative you’re free to modify the drawn examples to your liking. But what if you’re given an example you don’t like or one that breaks a known invariant you don’t wish to test for? For that you can use the assume() function to state the assumptions that Hypothesis must meet if you try to draw an example from generate_full_name .

Let’s say that first_name and last_name must not be equal:

Like the assert statement in Python, the assume() function teaches Hypothesis what is, and is not, a valid example. You use this to great effect to generate complex compound strategies.

I recommend you observe the following rules of thumb if you write imperative strategies with @composite :

If you want to draw a succession of examples to initialize, say, a list or a custom object with values that meet certain criteria you should use filter , where possible, and assume to teach Hypothesis why the value(s) you drew and subsequently discarded weren’t any good.

The example above uses assume() to teach Hypothesis that first_name and last_name must not be equal.

If you can put your functional strategies in separate functions, you should. It encourages code re-use and if your strategies are failing (or not generating the sort of examples you’d expect) you can inspect each strategy in turn. Large nested strategies are harder to untangle and harder still to reason about.

If you can express your requirements with filter and map or the builtin constraints (like min_size or max_size ), you should. Imperative strategies that use assume may take more time to converge on a valid example.

@example : Explicitly Testing Certain Values

Occasionally you’ll come across a handful of cases that either fails or used to fail, and you want to ensure that Hypothesis does not forget to test them, or to indicate to yourself or your fellow developers that certain values are known to cause issues and should be tested explicitly.

The @example decorator does just that:

You can add as many as you like.

Let’s say I wanted to write a simple converter to and from Roman numerals.

Here I’m collecting Roman numerals into numerals , one at a time, by looping over SYMBOLS of valid numerals, subtracting the value of the symbol from number , until the while loop’s condition ( number >= 1 ) is False .

The test is also simple and serves as a smoke test. I generate a random integer and convert it to Roman numerals with to_roman . When it’s all said and done I turn the string of numerals into a set and check that all members of the set are legal Roman numerals.

Now if I run pytest on it seems to hang . But thanks to Hypothesis’s debug mode I can inspect why:

Ah. Instead of testing with tiny numbers like a human would ordinarily do, it used a fantastically large one… which is altogether slow.

OK, so there’s at least one gotcha; it’s not really a bug , but it’s something to think about: limiting the maximum value. I’m only going to limit the test, but it would be reasonable to limit it in the code also.

Changing the max_value to something sensible, like st.integers(max_value=5000) and the test now fails with another error:

It seems our code’s not able to handle the number 0! Which… is correct. The Romans didn’t really use the number zero as we would today; that invention came later, so they had a bunch of workarounds to deal with the absence of something. But that’s neither here nor there in our example. Let’s instead set min_value=1 also, as there is no support for negative numbers either:

OK… not bad. We’ve proven that given a random assortment of numbers between our defined range of values that, indeed, we get something resembling Roman numerals.

One of the hardest things about Hypothesis is framing questions to your testable code in a way that tests its properties but without you, the developer, knowing the answer (necessarily) beforehand. So one simple way to test that there’s at least something semi-coherent coming out of our to_roman function is to check that it can generate the very numerals we defined in SYMBOLS from before:

Here I’m sampling from a tuple of the SYMBOLS from earlier. The sampling algorithm’ll decide what values it wants to give us, all we care about is that we are given examples like ("I", 1) or ("V", 5) to compare against.

So let’s run pytest again:

Oops. The Roman numeral V is equal to 5 and yet we get five IIIII ? A closer examination reveals that, indeed, the code only yields sequences of I equal to the number we pass it. There’s a logic error in our code.

In the example above I loop over the elements in the SYMBOLS dictionary but as it’s ordered the first element is always I . And as the smallest representable value is 1, we end up with just that answer. It’s technically correct as you can count with just I but it’s not very useful.

Fixing it is easy though:

Rerunning the test yields a pass. Now we know that, at the very least, our to_roman function is capable of mapping numbers that are equal to any symbol in SYMBOLS .

Now the litmus test is taking the numeral we’re given and making sense of it. So let’s write a function that converts a Roman numeral back into decimal:

Like to_roman we walk through each character, get the numeral’s numeric value, and add it to the running total. The test is a simple roundtrip test as to_roman has an inverse function from_roman (and vice versa) such that :

Invertible functions are easier to test because you can compare the output of one against the input of another and check if it yields the original value. But not every function has an inverse, though.

Running the test yields a pass:

So now we’re in a pretty good place. But there’s a slight oversight in our Roman numeral converters, though: they don’t respect the subtraction rule for some of the numerals. For instance VI is 6; but IV is 4. The value XI is 11; and IX is 9. Only some (sigh) numerals exhibit this property.

So let’s write another test. This time it’ll fail as we’ve yet to write the modified code. Luckily we know the subtractive numerals we must accommodate:

Pretty simple test. Check that certain numerals yield the value, and that the values yield the right numeral.

With an extensive test suite we should feel fairly confident making changes to the code. If we break something, one of our preexisting tests will fail.

The rules around which numerals are subtractive is rather subjective. The SUBTRACTIVE_SYMBOLS dictionary holds the most common ones. So all we need to do is read ahead of the numerals list to see if there exists a two-digit numeral that has a prescribed value and then we use that instead of the usual value.

The to_roman change is simple. A union of the two numeral symbol dictionaries is all it takes . The code already understands how to turn numbers into numerals — we just added a few more.

This method requires Python 3.9 or later. Read how to merge dictionaries

If done right, running the tests should yield a pass:

And that’s it. We now have useful tests and a functional Roman numeral converter that converts to and from with ease. But one thing we didn’t do is create a strategy that generates Roman numerals using st.text() . A custom composite strategy to generate both valid and invalid Roman numerals to test the ruggedness of our converter is left as an exercise to you.

In the next part of this course we’ll look at more advanced testing strategies.

Unlike a tool like faker that generates realistic-looking test data for fixtures or demos, Hypothesis is a property-based tester . It uses heuristics and clever algorithms to find inputs that break your code.

Testing a function that does not have an inverse to compare the result against – like our Roman numeral converter that works both ways – you often have to approach your code as though it were a black box where you relinquish control of the inputs and outputs. That is harder, but makes for less brittle code.

It’s perfectly fine to mix and match tests. Hypothesis is useful for flushing out invariants you would never think of. Combine it with known inputs and outputs to jump start your testing for the first 80%, and augment it with Hypothesis to catch the remaining 20%.

Be Inspired Sign up and we’ll tell you about new articles and courses

Absolutely no spam. We promise!

Liked the Article?

Why not follow us …, be inspired get python tips sent to your inbox.

We'll tell you about the latest courses and articles.

• Subscription

Tutorial: Text Analysis in Python to Test a Hypothesis

People often complain about important subjects being covered too little in the news. One such subject is climate change. The scientific consensus is that this is an important problem, and it stands to reason that the more people are aware of it, the better our chances may be of solving it. But how can we assess how widely covered climate change is by various media outlets? We can use Python to do some text analysis!

Specifically, in this post, we'll try to answer some questions about which news outlets are giving climate change the most coverage. At the same time, we'll learn some of the programming skills required to analyze text data in Python and test a hypothesis related to that data.

This tutorial assumes that you’re fairly familiar with Python and the popular data science package pandas. If you'd like to brush up on pandas, check out this post, and if you need to build a more thorough foundation, Dataquest's data science courses cover all of the Python and pandas fundamentals in more depth.

Finding & Exploring our Data Set

For this post we’ll use a news data set from Kaggle provided by Andrew Thompson (no relation). This data set contains over 142,000 articles from 15 sources mostly from 2016 and 2017, and is split into three different csv files. Here is the article count as displayed on the Kaggle overview page by Andrew:

We’ll work on reproducing our own version of this later. But one of the things that might be interesting to look at is the correlation, if any, between the characteristics of these news outlets and the proportion of climate-change-related articles they publish.

Some interesting characteristics we could look at include ownership (independent, non-profit, or corporate) and political leanings, if any. Below, I've done some preliminary research, collecting information from Wikipedia and the providers' own web pages.

I also found two websites that rate publications for their liberal vs conservative bias, allsides.com and mediabiasfactcheck.com, so I've collected some information about political leanings from there.

• Owner: Atlantic Media; majority stake recently sold to Emerson collective, a non-profit founded by Powell Jobs, widow of Steve Jobs
• Owner: Breitbart News Network, LLC
• Founded by a conservative commentator
• Owner: Alex Springer SE (publishing house in Europe)
• Center / left-center
• Private, Jonah Peretti CEO & Kenneth Lerer, executive chair (latter also co-founder of Huffington Post)
• Turner Broadcasting System, mass media
• TBS itself is owned by Time Warner
• Fox entertainment group, mass media
• Lean right / right
• Guardian Media Group (UK), mass media
• Owned by Scott Trust Limited
• National Review Institute, a non-profit
• Founded by William F Buckley Jr
• News corp, mass media
• Right / right center
• NY Times Company
• Thomson Reuters Corporation (Canadian multinational mass media)
• Josh Marshall, independent
• Nash Holdings LLC, controlled by J. Bezos
• Vox Media, multinational
• Lean left / left

Looking this over, we might hypothesize that right-leaning Breitbart, for example, would have a lower proportion of climate related articles than, say, NPR.

We can turn this into a formal hypothesis statement and will do that later in the post. But first, let’s dive deeper into the data. A terminology note: in the computational linguistics and NLP communities, a text collection such as this is called a corpus , so we'll use that terminology here when talking about our text data set.

Exploratory Data Analysis, or EDA, is an important part of any Data Science project. It usually involves analyzing and visualizing the data in various ways to look for patterns before proceeding with more in-depth analysis. In this case, though, we're working with text data rather than numerical data, which makes things a bit different.

For example, in numerical exploratory data analysis, we'd often want to look at the mean values for our data features. But there’s no such thing as an “average” word in a textual database, which makes our task a bit more complex. However, there are still both quantitative and qualitative explorations we can perform to sanity check our corpus’s integrity.

First, let’s reproduce the chart above to ensure that we're not missing any data, and then sort by article count. We'll start by covering all of our imports, reading the data set, and checking the length of each of its three parts.

Working with three separate data sets isn't going to be convenient, though. We'll combine all three DataFrames into a single one so we can work with our entire corpus more easily:

Next, we'll make sure we have the same publication names as in the original data set, and check the earliest and latest years of the articles.

It’s unusual to store dates as floats like we see above, but that is how they are stored in our CSV file. We're not planning to use dates for anything too important anyway, so for the purposes of this tutorial we'll just leave them as floats. If we were doing a different analysis, though, we might want to convert them to a different format.

Let's take a quick look at when our articles are from using pandas' value_counts()  function.

We can see that there are mostly recent years, but a few older articles are included, too. That serves our purposes fine, as we're mostly concerned with coverage over the past few years.

Now, let's sort the publications by name to reproduce the original plot from Kaggle.

This plot order is helpful if you want to find a specific outlet quickly, but it may be more helpful for us to sort it by article count so that we get a better idea of where our data is coming from.

We want to check the average article length in words, but equally important is the diversity of those words. Let’s look at both.

We'll start by defining a function that removes punctuation and converts all the text to lower case. (We’re not doing any complicated syntactic analysis, so we don’t need to preserve the sentence structure or capitalization).

Now we'll create a new column in our dataframe with the cleaned up text.

Above, we can see that we've successfully removed capitalization and punctuation from our corpus, which should make it easier for us to identify and count unique words.

Let's take a look at the average (mean) number of words in each article, and the longest and shortest articles in our data set.

An article with zero words isn't any use to us, so let's see how many of those there are. We'll want to remove articles with no words from our data set.

Let's get rid of those empty articles and then see what that does to the mean number of words per article in our data set, and what our new minimum word count is.

At this point, it might be helpful for us visualize a distribution of the article word counts to see how skewed our average might be by outliers. Let's generate another plot to take a look:

Next step in our Python text analysis: explore article diversity. We’ll use the number of unique words in each article as a start. To calculate that value, we need to create a set out of the words in the article, rather than a list. We can think of a set as being a bit like a list, but a set will omit duplicate entries.

There's more information on sets and how they work in the official documentation , but let's first take a look at a basic example of how creating a set works. Notice that although we start with two b entries, there is only one in the set we create:

Next, we're going to do a few things at once:

Operating on the series from the tokenized column that we created earlier, we will invoke the split function from the string library. Then we'll get the set from our series to eliminate duplicate words, then measure the size of the set with len() .

Finally, we’ll add the result as a new column that contains the number of unique words in each article.

We also want to take a look at the average (mean) number of unique words per article, and the minimum and maximum unique word counts.

When we plot this into a chart, we can see that while the distribution of unique words is still skewed, it looks a bit more like a normal (Gaussian) distribution than the distribution based on total word counts we generated earlier.

Let’s also look at how these two measures of article length differ by publication.

To do that, we’ll use pandas’s groupby function. The full documentation on this powerful function can be found  here , but for our purposes, we just need to know that it allows us to aggregate , or total in different ways, different metrics by the values of another column.

In this case that column is publication . This first plot uses just the number of objects in each group by aggregating over len . We could have used any other column besides title in the code below.

Now we'll aggregate over the mean number of words and number of unique words, respectively.

Finally, let’s look at the most common words over the entire corpus.

We'll use a Python Counter , which is a special kind of dictionary that assumes integer types for each key’s value. Here, we iterate through all the articles using the tokenized version of our articles.

When we're counting the most common words, though, we don’t want to include all words in our count. There are a number of words so common in written English that they're likely to appear as the most common words in any analysis. Counting them won't tell us anything about the article's content. In NLP and text processing, these words are called "stopwords." The list of common English stopwords includes words such as “and,” “or,” and “such.”

Remember we imported the module stopwords from nltk.corpus at the beginning of this project, so now let’s take a look at what words are contained in this pre-made stopwords list:

As we can see, this is quite a long list, but none of these words can really tell us anything about the meaning of an article. Let's use this list to delete the stopwords from our Counter .

To further filter our word counts down into useful information,  Counter has a handy most_common method which we can use here to take a look at just the most commonly-used words it found. Using this fucntion, we can specify the number of results we'd like to see. Here, we'll ask it for a list of just the top 20 most common words.

Above, we can see some pretty predictable words, but also a bit of a surprise: the word  u is apparently among the most common. This may seem strange, but it comes from the fact that acronyms like "U.S." and "U.N." are used frequently in these articles.

That's a bit odd, but remember that at the moment we're just exploring the data. The actual hypothesis we want to test is that climate change coverage might be correlated with certain aspects of a media outlet, like its ownership or political leanings. The existence of u as a word in our corpus isn't likely to affect this analysis at all, so we can leave it as-is.

We could do a lot more cleaning and refining for this data set in other areas as well, but it's probably not necessary. Instead, let's move on to the next step: testing whether our initial hypothesis is correct.

Text Analysis: Testing Our Hypothesis

How can we test our hypothesis? First, we have to determine which articles are talking about climate change, and then we have to compare coverage across types of articles.

How can we tell whether an article is talking about climate change? There are several ways we could do this. We could identify concepts using advanced text analytics techniques such as clustering or topic modeling. But for the purposes of this article, let's keep it simple: let's just identify keywords that might correlate with the topic, and search for them in the articles. Just brainstorming some words and phrases of interest should do the trick.

When we list out these phrases, we have to be a little careful to avoid ambiguous words such as “environment” or “sustainability.” These are potentially related to environmentalism, but they could also be about the political environment or business sustainability. Even "climate" may not be a meaningful keyword unless we can be sure it's closely associated with "change."

What we need to do is create a function to determine whether an article contains words of interest to us. To do this, we're going to use regex, or regular expressions. Regex in Python is covered in more detail in this blog post if you need a refresher. In addition to this Regex, we'll also search for exact matches of several other phrases, defined in the cc_wds parameter.

In looking for mentions of climate change, we have to be a bit careful. We can't use the word "change," because that would eliminate related words like "changing".

So here's how we're going to filter it: we want the string chang followed by the string climate within 1 to 5 words (in regular expressions,  \w+ matches one or more word characters, and \W+ matches one or more nonword characters).

We can use | is to represent a logical or , so we can also match the string climate followed by the string chang within 1 to 5 words. The 1 to 5 word part is the part of the regex that will look like this: (?:\w+\W+){1,5}? .

All together, searching for these two strings should help us identify any articles that mention climate change, the changing climate, etc.

Here's a closer look at how the parts of this function work:

As we can see, this is working as intended — it's matching the real references to climate change, and not being thrown off by the use of the term "change" in other contexts.

Now let's use our function to create a new Boolean field indicating whether we've found relevant words, and then see if there are any mentions of climate change in the first five articles of our data set:

The first five articles in our data set don't contain any mentions of climate change, but we know our function is working as intended from our earlier test, so now we can start to do some analysis of the news coverage.

Returning to our original goal of comparing coverage of climate change topics across sources, we might think of counting the number of climate related articles published by each source and comparing across sources. When we do that, we need to account for the disparity in total article counts, though. A larger total number of climate related articles from one outlet may only be due to a larger number of articles published overall.

What we need to do is count the relative proportion of climate related articles. We can use the sum function on a Boolean field such as cc_wds to count the number of True values, and we divide by the number of articles total articles published to get our proportion.

Let's start by taking a look at the total proportion across all sources to give ourselves a baseline to compare each outlet against:

We see that the proportion of climate coverage over all articles is 3.1%, which is fairly low, but not problematic from a statistical point of view.

Next we want to count the relative proportions for each group. Let’s illustrate how this works by looking at the proportion per publication source. We will again use our groupby object and sum , but this time we want the count of articles per group, which we get from the count function:

Now, let's break that down into proportions and sort the list so that we can quickly see at a glance which outlets are doing the most coverage of climate change:

The proportion ranges from 0.7% for the New York Post to 8% for Vox. Let's plot this, sorted by publication name, and then again sorted by value.

We could do all sorts of other exploratory data analysis here, but let’s put that aside for now and move on to our goal of testing a hypothesis about our corpus.

Testing the Hypothesis

We won’t present a complete overview of hypothesis testing and its subtleties in this post; for an overview of probability in Python visit this article , and for details on statistical hypothesis testing, Wikipedia isn’t a bad place to continue.

We’ll illustrate one form of hypothesis testing here.

Recall that we started off by informally assuming that publication characteristics might correlate with the preponderance of climate related articles they produce. Those characteristics include political leanings and ownership. For example, our null hypothesis related to political leanings informally says that there is no difference in climate change mention when comparing articles with different political leanings. Let’s make that more formal.

If we look at the left vs. right political leanings of the publications, and call the group of publications that lean left “Left” and the right-leaning group “Right,” our null hypothesis is that the population climate change article proportion for Left equals the population climate change article proportion for Right. Our alternative hypothesis is that the two population proportions are unequal. We can substitute other population groupings and state similar hypotheses for other political leaning comparisons or for other publication characteristics.

Let’s start with political leanings. You can revisit the top of this post to remind yourself of how we collected the information about outlets' political leanings. The below code uses a dictionary to assign left , right , and center values to each publication name based on the information we collected.

We again use groupby() to find the proportion of climate change articles within each political group.

Let's look at how many articles there are in each group, and chart it:

From the above chart, it seems obvious that the proportion of climate change related articles differs for the different political leaning groups, but let's formally test our hypothesis. To do this, for a given pair of article groupings, we state the null hypothesis, which is to assume that there is no difference in the population proportion of climate-related articles. Let’s also establish a 95% confidence level for our test.

Once we gather our statistics, we can use either P-values or confidence intervals to determine whether our results are statistically significant. We’ll use confidence intervals here because we're interested in what range of values of the difference are likely to reflect the population proportion differences. The statistic of interest in our hypothesis test is the difference in the proportion of climate change articles in two samples. Recall that there is a close relationship between confidence intervals and significance tests. Specifically, if a statistic is significantly different than zero at the 0.05 level, then the 95% confidence interval will not contain 0.

In other words, if zero is in the confidence interval that we compute, then we would not reject the null hypothesis. But if it is not, we can say the difference in the proportion of relevant articles is statistically significant. I want to take this opportunity to point out a common misunderstanding in confidence intervals: the 95% interval gives us a region where, had we redone the sampling, then 95% of the time, the interval will contain the true (population) difference in proportion. It is not saying that 95% of the samples will be in the interval.

To compute the confidence interval, we need a point estimate and a margin of error; the latter consists of the critical value multiplied by the standard error. For difference in proportions, our point estimate for the difference is p 1 − p 2 , where p 1 and p 2 are our two sample proportions. With a 95% CI, 1.96 is our critical value. Next, our standard error is:

Finally, the confidence interval is (point_estimate ± critical_value X standard-error) , or:

Let’s plug our numbers into these formulas, using some helper functions to do so.

Finally, the calc_ci_range function puts everything together.

Let's calculate the confidence intervals for our leaning groups, looking first at left vs. right.

Looking at the difference in proportions for left vs right publications, our confidence interval ranges from 1.8% to 2.1%. This is both a fairly narrow range and far from zero relative to the overall range of the difference in proportion. So rejecting the null hypothesis is obvious. Similarly, the range for center vs left is 1.3% to 2.1%:

Because the assignment of publications to bias slant is somewhat subjective, here is another variant, putting Business Insider, NY Post, and NPR in center .

Next, we can look at publication ownership, using the same approach. We divide our population into four groups, LLC, corporation, non-profit, and private.

Now let's plot that data to see whether different types of companies cover climate change in different proportions.

Perhaps unsurprisingly, it looks like private companies and nonprofits cover climate change a bit more than corporations and LLCs. But let's look more closely at the difference in proportion between the first two, LLCs and corporations:

Here, the confidence interval is 0.3% to 0.7%, much closer to zero than our earlier differences, but still not including zero. We would expect the non-profit to LLC interval to also not include zero:

The non-profit to LLC confidence interval is 0.6% to 1.2%.Finally, looking at private vs. non-profit, we find a confidence interval of -0.3% to 0.5%:

Thus in this case, we can conclude that there is not a significant difference in proportion of climate change related articles between these two populations, unlike the others populations we’ve compared.

Summary: Text Analysis to Test a Hypothesis

In this article, we've performed some text analysis on a large corpus of news articles and tested some hypotheses about the differences in their content. Specifically, using a 95% confidence interval, we estimated differences in climate change discussions between different groups of news sources.

We found some interesting differences which were also statistically significant, including that right-leaning news sources tend to cover climate change less, and corporations and LLCs tend to cover it less than non-profit and private outlets.

In terms of working with this corpus, though, we've barely touched the tip of the iceberg. There are many interesting analyses you could attempt with this data, so download the data from Kaggle for yourself and start writing your own text analysis project!

Further Reading:

Olteanu, A, et al. “Comparing events coverage in online news and social media: The case of climate change.” Proceedings of the Ninth International AAAI Conference on Web and Social Media. 2015.

More learning resources

Tutorial: basic statistics in python — descriptive statistics, using box plots to explore women’s height data.

Learn data skills 10x faster

Join 1M+ learners

Enroll for free

• Data Analyst (Python)
• Gen AI (Python)
• Business Analyst (Power BI)
• Business Analyst (Tableau)
• Machine Learning
• Data Analyst (R)

Python Dictionary: How To Create And Use, With Examples

The Python dictionary is one of the language’s most powerful data types. In other programming languages and computer science in general, dictionaries are also known as associative arrays. They allow you to associate one or more keys to values. If you are familiar with JSON , you might feel right at home. The syntax of a dictionary strongly resembles the syntax of a JSON document.

Table of Contents

• 1 Creating a Python Dictionary
• 2 Access and delete a key-value pair
• 3 Overwrite dictionary entries
• 4 Using try… except
• 5 Valid dictionary values
• 6 Valid dictionary keys
• 7 More ways to create a Python dictionary
• 8 Check if a key exists in a Python dictionary
• 9 Getting the length of a Python dictionary
• 10 Dictionary view objects
• 11 Merging dictionaries
• 12 Comparing Python dictionaries
• 13 Built-in Python dictionary methods
• 14 Conclusion

Creating a Python Dictionary

Let’s look at how we can create and use a Python dictionary in the  Python REPL :

A dictionary is created by using curly braces. Inside these braces, we can add one or more key-value pairs. The pairs are separated by commas when adding more than one key-value pair. The first dictionary in our example associates keys (names like Jack and Pete) with values (their phone numbers). The second dictionary is an empty one.

Access and delete a key-value pair

Now that you’ve seen how to initialize a dictionary, let’s see how we can add and remove entries to an already existing one:

Default values and dict.get()

Another way to retrieve a single value from a dictionary is using the get-method. The advantage? It returns a default value, None , if the key was not found. You can specify your own default value too.

With the get-method, you don’t have to surround the operation with a try… except. It’s ideal when working with configuration data that is parsed from YAML or JSON files, where your software offers defaults for unset configuration items.

An example:

That last get call returns None , but the more recent versions of the REPL don’t print None.

Overwrite dictionary entries

To overwrite an entry, simply assign a new value to it. You don’t need to  del()  it first. E.g.:

Using try… except

If a requested key does not exist, an exception of type  KeyError  is thrown:

If you know data can be missing, e.g., when parsing input from the outside world, make sure to surround your code with a  try ... except KeyError. I’ve explained this in detail in the best practices section of my article on try… except . In that article, I also explain the concept of asking for forgiveness, not permission . E.g., don’t check if a key exists before trying to access it. Instead, just try it, and catch the exception if it doesn’t exist.

Valid dictionary values

You can put anything in a dictionary. You’re not limited to numbers or strings . In fact, you can put dictionaries and Python lists inside your dictionary and access the nested values in a very natural way:

Python’s JSON decoding and encoding library  uses this feature of Python when parsing more complex JSON documents. It creates nested trees of lists, dictionaries, and other valid data types.

Valid dictionary keys

You can go pretty wild on your dictionary keys, too. The only requirement is that the key is hashable. Mutable types like lists , dictionaries, and sets won’t work and result in an error like: TypeError: unhashable type: ‘dict’ .

Besides this limitation, you can use all data types as a dictionary key, including native types like a tuple ,  float  and  int or even a class name or object based on a class. Although completely useless for most, I’ll demonstrate anyway:

A more likely use case is the use of numbers as keys. For example, consider this registration of runners in a marathon:

More ways to create a Python dictionary

Depending on your data source, there are more advanced ways to initialize a dictionary that might come in handy.

Using the dict() constructor

The  dict()  function builds a dictionary from a sequence or list of key-value pairs ( tuples ):

Dictionary Comprehensions

Analogous to list comprehensions , you can also use dictionary comprehensions to create a new dictionary. While a list only contains values, a dictionary contains key/value pairs. Hence, dictionary comprehensions need to define both. Other than that, the syntax is similar:

Please read my article on list comprehensions for a more detailed explanation of comprehensions in general.

Using dict.fromkeys

The  dict.fromkeys(keys, value)  method creates a new dictionary, based on the list of  keys  supplied to it. The value of all elements will be set to the supplied  value , or  None  by default, if you don’t supply a value.

See the following code:

The list of keys can be anything that is iterable. E.g., this works just as well with a set or a tuple .

Parse a JSON object to a dictionary

As explained in the section on working with JSON, you can also  decode JSON data into a dictionary  like this:

Check if a key exists in a Python dictionary

You can check if a key exists inside a dictionary with the  in  and  not in  keywords:

Getting the length of a Python dictionary

The built-in Python  len()  function returns the number of key/value pairs in a dictionary:

Dictionary view objects

Some built-in dictionary methods return a view object, offering a window on your dictionary’s keys and values. Before we start using such view objects, there’s an important concept you need to understand: values in a view object change as the content of the dictionary changes.

dict.keys() and dict.values()

This is best illustrated with an example, in which we use two of these views: keys() and values(). Keys returns a view on all the keys of a dictionary, while values() returns a view on all its values:

If that didn’t work, here’s the non-interactive version:

The output of this code is  dict_keys(['Jack', 'Pete', 'Eric', 'Linda']) . As you can see, Linda is part of the list too, even though she got added after creating the  names  view object.

dict.items(): loop through a Python dictionary

The  items()  method of a dictionary returns an iterable view object, offering both the keys and values, as can be seen below. You can loop through this object with a simple Python for-loop :

Alternatively, you can use the keys() and values() methods to loop through just the keys or values. Both functions return an iterable view object.

More ways to get all the keys

We’ve seen the  dict.keys()  method, which returns a view object containing a list of all the dictionary keys. The advantage of this object is that it stays in sync with the dictionary. It’s perfect for looping over all the keys, but you still might opt for the  list  or  sorted  methods though, because those return a native list that you can manipulate as well.

There are two other easy ways to get all the keys from a dictionary:

list()  returns all the keys in insertion order, while  sorted()  returns all the keys sorted alphabetically.

Merging dictionaries

If you’re running Python 3.9 or later, you can use the newly introduced merging operator for dictionaries:

If you’re still on a Python version between 3.5 and 3.9, you can merge two dictionaries using the following method:

Comparing Python dictionaries

If you need to compare two dictionaries, you can use a comparison operator like this:

This looks and sounds trivial, but it’s not! A dictionary can contain objects of any type, after all! Consequently, Python has to walk through all the keys and values and individually compare them.

You might wonder if a dictionary with the same keys and values inserted in another order is the same. Let’s check this:

They are the same to Python, despite having a different order.

Good to know: the order of dictionaries is guaranteed to be insertion order since Python 3.7. In other words, it means that the order of the dictionary is determined by the order in which you insert items.

Built-in Python dictionary methods

Each dictionary inherits some handy built-in functions, as listed in the following table:

You’ve learned what a Python dictionary is, how to create dictionaries, and how to use them. We’ve examined many practical use cases involving Python dictionaries with example code. If there’s still something missing, or you simply want to learn even more about dictionaries, you can head over to the official manual page at Python.org .

Get certified with our courses

Learn Python properly through small, easy-to-digest lessons, progress tracking, quizzes to test your knowledge, and practice sessions. Each course will earn you a downloadable course certificate.

Related articles

• Python List Comprehension: Tutorial With Examples
• Python Read And Write File: With Examples
• JSON in Python: How To Read, Write, and Parse
• Python YAML: How to Load, Read, and Write YAML

Python Dictionaries 101: A Detailed Visual Introduction

In this article, you will learn how to work with Python dictionaries, an incredibly helpful built-in data type that you will definitely use in your projects.

In particular, you will learn:

• What dictionaries are used for and their main characteristics.
• Why they are important for your programming projects.
• The "anatomy" of a dictionary: keys, values, and key-value pairs.
• The specific rules that determine if a value can be a key.
• How to access, add, modify, and delete key-value pairs.
• How to check if a key is in a dictionary.
• What the length of a dictionary represents.
• How to iterate over dictionaries using for loops.
• What built-in dictionary methods you can use to leverage the power of this data type.

At the end of this article, we will dive into a simple project to apply your knowledge: we will write a function that creates and returns a dictionary with a particular purpose.

Let's begin! ⭐️

🔹 Dictionaries in Context

Let's start by discussing the importance of dictionaries. To illustrate this, let me do a quick comparison with another data type that you are probably familiar with: lists.

When you work with lists in Python, you can access an element using a index, an integer that describes the position of the element in the list. Indices start from zero for the first element and increase by one for every subsequent element in the list. You can see an example right here:

But what if we need to store two related values and keep this "connection" in our code? Right now, we only have single, independent values stored in a list.

Let's say that we want to store names of students and "connect" each name with the grades of each particular student. We want to keep the "connection" between them. How would you do that in Python?

If you use nested lists, things would get very complex and inefficient after adding only a few items because you would need to use two or more indices to access each value, depending on the final list. This is where Python dictionaries come to the rescue.

Meet Dictionaries

A Python dictionary looks like this (see below). With a dictionary, you can "connect" a value to another value to represent the relationship between them in your code. In this example,"Gino" is "connected" to the integer 15 and the string "Nora" is "connected" to the integer 30.

Let's see the different elements that make a dictionary.

🔸 The "Anatomy" of a Python Dictionary

Since a dictionary "connects" two values, it has two types of elements:

• Keys: a key is a value used to access another value. Keys are the equivalent of "indices" in strings, lists, and tuples. In dictionaries, to access a value, you use the key, which is a value itself.
• Values: these are the values that you can access with their corresponding key.

These two elements form what is called a key-value pair (a key with its corresponding value).

This is an example of a Python Dictionary mapping the string "Gino" to the number 15  and the string "Nora" to the number 30:

• To create a dictionary, we use curly brackets { } .
• Between these curly brackets, we write key-value pairs separated by a comma.
• For the key-value pairs, we write the key followed by a colon, a space, and the value that corresponds to the key.
• For readability and style purposes, it is recommended to add a space after each comma to separate the key-value pairs.
• You can create an empty dictionary with an empty pair of curly brackets {} .

Important Rules for Keys

Not every value can be a key in a Python dictionary. Keys have to follow a set of rules:

According to the Python Documentation :

• Keys have to be unique within one dictionary.

It is best to think of a dictionary as a set of key: value pairs, with the requirement that the keys are unique (within one dictionary).

• Keys have to be immutable.

Unlike sequences, which are indexed by a range of numbers, dictionaries are indexed by keys , which can be any immutable type; strings and numbers can always be keys.

• If the key is a tuple, it can only contain strings, numbers or tuples.

Tuples can be used as keys if they contain only strings, numbers, or tuples; if a tuple contains any mutable object either directly or indirectly, it cannot be used as a key.

• Lists cannot be keys because they are mutable. This is a consequence of the previous rule.

You can’t use lists as keys, since lists can be modified in place using index assignments, slice assignments, or methods like append() and extend() .

💡 Note: Values have no specific rules, they can be either mutable or immutable values.  

🔹 Dictionaries in Action

Now let's see how we can work with dictionaries in Python. We are going to access, add, modify, and delete key-value pairs.

We will start working with this dictionary, assigned to the ages variable:

Access Values using Keys

If we need to access the value associated with a specific key, we write the name of the variable that references the dictionary followed by square brackets [] and, within the square brackets, the key that corresponds to the value:

This is an example of how we can access the value that corresponds to the string "Gino" :

Notice that the syntax is very similar to indexing a string, tuple, or list, but now we are using the key as the index instead of an integer.

If we want to access the value that corresponds to "Nora", we would do this:

💡 Tip: If you try to access a key that does not exist in the dictionary, you will get a KeyError :

Add Key-Value Pairs

If a key-value pair doesn't exist in the dictionary, we can add it. To do this, we write the variable that references the dictionary followed by the key within square brackets, an equal sign, and the new value:

This is an example in IDLE:

Modify a Key-Value Pair

To modify the value associated to a specific key, we use the same syntax that we use to add a new key-value pair, but now we will be assigning the new value to an existing key:

Deleting a Key-Value Pair

To delete a key-value pair, you would use the del keyword followed by the name of the variable that references the dictionary and, within square brackets [] , the key of the key-value pair:

🔸 Check if a Key is in a Dictionary

Sometimes, it can be very helpful to check if a key already exists in a dictionary (remember that keys have to be unique).

To check whether a single key is in the dictionary, use the in keyword.

The in operator checks the keys, not the values. If we write this:

We are checking if the key 15 is in the dictionary, not the value. This is why the expression evaluates to False .

💡 Tip: You can use the in operator to check if a value is in a dictionary with <dict> .values() .

🔹 Length of a Python Dictionary

The length of a dictionary is the number of key-value pairs it contains. You can check the length of a dictionary with the len() function that we commonly use, just like we check the length of lists, tuples, and strings:

🔸 Iterating over Dictionaries in Python

You can iterate over dictionaries using a for loop. There are various approaches to do this and they are all equally relevant. You should choose the approach that works best for you, depending on what you are trying to accomplish.

First Option - Iterate over the Keys

We can iterate over the keys of a dictionary like this:

For example:

Second Option - Iterate over the Key-Value Pairs

To do this, we need to use the built-in method .items() , which allows us to iterate over the key-value pairs as tuples of this format (key, value) .

Third Option - Assign Keys and Values to Individual Variables

With .items() and for loops, you can use the power of a tuple assignment to directly assign the keys and values to individual variables that you can use within the loop:

Fourth Option - Iterate over the Values

You can iterate over the values of a dictionary using the .values() method.

🔹 Dictionary Methods

Dictionaries include very helpful built-in methods that can save you time and work to perform common functionality:

This method removes all the key-value pairs from the dictionary.

.get(<key>, <default>)

This method returns the value associated with the key. Otherwise, it returns the default value that was provided as the second argument (this second argument is optional).

If you don't add a second argument, this is equivalent to the previous syntax with square brackets [] that you learned:

.pop(<key>, <default>)

This method removes the key-value pair from the dictionary and returns the value.

.update(<other>)

This method replaces the values of a dictionary with the values of another dictionary only for those keys that exist in both dictionaries.

An example of this would be a dictionary with the original grades of three students (see code below). We only want to replace the grades of the students who took the make-up exam (in this case, only one student took the make-up exam, so the other grades should remain unchanged).

By using the .update() method, we could update the value associated with the string "Gino" in the original dictionary since this is the only common key in both dictionaries.

The original value would be replaced by the value associated with this key in the dictionary that was passed as argument to .update().

💡 Tips: To learn more about dictionary methods, I recommend reading this article in the Python Documentation .

🔸 Mini Project - A Frequencies Dictionary

Now you will apply your knowledge by writing a function freq_dict that creates and returns a dictionary with the frequency of each element of a list, string, or tuple (the number of times the element appears). The elements will be the keys and the frequencies will be the values.

We will be writing the function step-by-step to see the logic behind each line of code.

• Step 1: The first thing that we need to do is to write the function header. Notice that this function only takes one argument, the list, string or tuple, which we call data .
• Step 2: Then, we need to create an empty dictionary that will map each element of the list, string, or tuple to its corresponding frequency.
• Step 3: Then, we need to iterate over the list, string, or tuple to determine what to do with each element.
• Step 4: If the element has already been included in the dictionary, then the element appears more than once and we need to add 1 to its current frequency. Else, if the element is not in the dictionary already, it's the first time it appears and its initial value should be 1.
• Step 5: Finally, we need to return the dictionary.

❗️ Important: Since we are assigning the elements as the keys of the dictionary, they have to be of an immutable data type.

Here we have an example of the use of this function. Notice how the dictionary maps each character of the string to how many times it occurs.

This is another example applied to a list of integers:

Great Work! Now we have the final function.

🔹 In Summary

• Dictionaries are built-in data types in Python that associate (map) keys to values, forming key-value pairs.
• You can access a value with its corresponding key.  
• Keys have to be of an immutable data type.
• You can access, add, modify, and delete key-value pairs.
• Dictionaries offer a wide variety of methods that can help you perform common functionality.

I really hope you liked my article and found it helpful. Now you can work with dictionaries in your Python projects. Check out my online courses . Follow me on Twitter . ⭐️

Developer, technical writer, and content creator @freeCodeCamp. I run the freeCodeCamp.org Español YouTube channel.

If you read this far, thank the author to show them you care. Say Thanks

Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started

• Hypothesis for the scientific stack
• Edit on GitHub

Hypothesis for the scientific stack ¶

Hypothesis offers a number of strategies for NumPy testing, available in the hypothesis[numpy] extra . It lives in the hypothesis.extra.numpy package.

The centerpiece is the arrays() strategy, which generates arrays with any dtype, shape, and contents you can specify or give a strategy for. To make this as useful as possible, strategies are provided to generate array shapes and generate all kinds of fixed-size or compound dtypes.

Creates a strategy which can generate any value of the given dtype.

Compatible parameters are passed to the inferred strategy function while inapplicable ones are ignored. This allows you, for example, to customise the min and max values, control the length or contents of strings, or exclude non-finite numbers. This is particularly useful when kwargs are passed through from arrays() which allow a variety of numeric dtypes, as it seamlessly handles the width or representable bounds for you.

Returns a strategy for generating numpy.ndarray s.

dtype may be any valid input to dtype (this includes dtype objects), or a strategy that generates such values.

shape may be an integer >= 0, a tuple of such integers, or a strategy that generates such values.

elements is a strategy for generating values to put in the array. If it is None a suitable value will be inferred based on the dtype, which may give any legal value (including eg NaN for floats). If a mapping, it will be passed as **kwargs to from_dtype()

fill is a strategy that may be used to generate a single background value for the array. If None, a suitable default will be inferred based on the other arguments. If set to nothing() then filling behaviour will be disabled entirely and every element will be generated independently.

unique specifies if the elements of the array should all be distinct from one another. Note that in this case multiple NaN values may still be allowed. If fill is also set, the only valid values for it to return are NaN values (anything for which numpy.isnan returns True. So e.g. for complex numbers nan+1j is also a valid fill). Note that if unique is set to True the generated values must be hashable.

Arrays of specified dtype and shape are generated for example like this:

Array values are generated in two parts:

Some subset of the coordinates of the array are populated with a value drawn from the elements strategy (or its inferred form).

If any coordinates were not assigned in the previous step, a single value is drawn from the fill strategy and is assigned to all remaining places.

You can set fill=nothing() to disable this behaviour and draw a value for every element.

If fill=None , then it will attempt to infer the correct behaviour automatically. If unique is True , no filling will occur by default. Otherwise, if it looks safe to reuse the values of elements across multiple coordinates (this will be the case for any inferred strategy, and for most of the builtins, but is not the case for mutable values or strategies built with flatmap, map, composite, etc) then it will use the elements strategy as the fill, else it will default to having no fill.

Having a fill helps Hypothesis craft high quality examples, but its main importance is when the array generated is large: Hypothesis is primarily designed around testing small examples. If you have arrays with hundreds or more elements, having a fill value is essential if you want your tests to run in reasonable time.

Return a strategy for array shapes (tuples of int >= 1).

min_dims is the smallest length that the generated shape can possess.

max_dims is the largest length that the generated shape can possess, defaulting to min_dims + 2 .

min_side is the smallest size that a dimension can possess.

max_side is the largest size that a dimension can possess, defaulting to min_side + 5 .

Return a strategy that can return any non-flexible scalar dtype.

Return a strategy for unsigned integer dtypes.

endianness may be < for little-endian, > for big-endian, = for native byte order, or ? to allow either byte order. This argument only applies to dtypes of more than one byte.

sizes must be a collection of integer sizes in bits. The default (8, 16, 32, 64) covers the full range of sizes.

Return a strategy for signed integer dtypes.

endianness and sizes are treated as for unsigned_integer_dtypes() .

Return a strategy for floating-point dtypes.

sizes is the size in bits of floating-point number. Some machines support 96- or 128-bit floats, but these are not generated by default.

Larger floats (96 and 128 bit real parts) are not supported on all platforms and therefore disabled by default. To generate these dtypes, include these values in the sizes argument.

Return a strategy for complex-number dtypes.

sizes is the total size in bits of a complex number, which consists of two floats. Complex halves (a 16-bit real part) are not supported by numpy and will not be generated by this strategy.

Return a strategy for datetime64 dtypes, with various precisions from year to attosecond.

Return a strategy for timedelta64 dtypes, with various precisions from year to attosecond.

Return a strategy for generating bytestring dtypes, of various lengths and byteorder.

While Hypothesis’ string strategies can generate empty strings, string dtypes with length 0 indicate that size is still to be determined, so the minimum length for string dtypes is 1.

Return a strategy for generating unicode string dtypes, of various lengths and byteorder.

Return a strategy for generating array (compound) dtypes, with members drawn from the given subtype strategy.

Return the most-general dtype strategy.

Elements drawn from this strategy may be simple (from the subtype_strategy), or several such values drawn from array_dtypes() with allow_subarrays=True . Subdtypes in an array dtype may be nested to any depth, subject to the max_leaves argument.

Return a strategy for generating permissible tuple-values for the axis argument for a numpy sequential function (e.g. numpy.sum() ), given an array of the specified dimensionality.

All tuples will have a length >= min_size and <= max_size . The default value for max_size is ndim .

Examples from this strategy shrink towards an empty tuple, which render most sequential functions as no-ops.

The following are some examples drawn from this strategy.

valid_tuple_axes can be joined with other strategies to generate any type of valid axis object, i.e. integers, tuples, and None :

Return a strategy for shapes that are broadcast-compatible with the provided shape.

Examples from this strategy shrink towards a shape with length min_dims . The size of an aligned dimension shrinks towards size 1 . The size of an unaligned dimension shrink towards min_side .

shape is a tuple of integers.

max_dims is the largest length that the generated shape can possess, defaulting to max(len(shape), min_dims) + 2 .

min_side is the smallest size that an unaligned dimension can possess.

max_side is the largest size that an unaligned dimension can possess, defaulting to 2 plus the size of the largest aligned dimension.

Return a strategy for a specified number of shapes N that are mutually-broadcastable with one another and with the provided base shape.

num_shapes is the number of mutually broadcast-compatible shapes to generate.

base_shape is the shape against which all generated shapes can broadcast. The default shape is empty, which corresponds to a scalar and thus does not constrain broadcasting at all.

The strategy will generate a typing.NamedTuple containing:

input_shapes as a tuple of the N generated shapes.

result_shape as the resulting shape produced by broadcasting the N shapes with the base shape.

Use with Generalised Universal Function signatures

A universal function (or ufunc for short) is a function that operates on ndarrays in an element-by-element fashion, supporting array broadcasting, type casting, and several other standard features. A generalised ufunc operates on sub-arrays rather than elements, based on the “signature” of the function. Compare e.g. numpy.add() (ufunc) to numpy.matmul() (gufunc).

To generate shapes for a gufunc, you can pass the signature argument instead of num_shapes . This must be a gufunc signature string; which you can write by hand or access as e.g. np.matmul.signature on generalised ufuncs.

In this case, the side arguments are applied to the ‘core dimensions’ as well, ignoring any frozen dimensions. base_shape and the dims arguments are applied to the ‘loop dimensions’, and if necessary, the dimensionality of each shape is silently capped to respect the 32-dimension limit.

The generated result_shape is the real result shape of applying the gufunc to arrays of the generated input_shapes , even where this is different to broadcasting the loop dimensions.

gufunc-compatible shapes shrink their loop dimensions as above, towards omitting optional core dimensions, and smaller-size core dimensions.

Return a strategy for basic indexes of arrays with the specified shape, which may include dimensions of size zero.

It generates tuples containing some mix of integers, slice objects, ... (an Ellipsis ), and None . When a length-one tuple would be generated, this strategy may instead return the element which will index the first axis, e.g. 5 instead of (5,) .

shape is the shape of the array that will be indexed, as a tuple of positive integers. This must be at least two-dimensional for a tuple to be a valid index; for one-dimensional arrays use slices() instead.

min_dims is the minimum dimensionality of the resulting array from use of the generated index. When min_dims == 0 , scalars and zero-dimensional arrays are both allowed.

max_dims is the the maximum dimensionality of the resulting array, defaulting to len(shape) if not allow_newaxis else max(len(shape), min_dims) + 2 .

allow_newaxis specifies whether None is allowed in the index.

allow_ellipsis specifies whether ... is allowed in the index.

Return a search strategy for tuples of integer-arrays that, when used to index into an array of shape shape , given an array whose shape was drawn from result_shape .

Examples from this strategy shrink towards the tuple of index-arrays:

shape a tuple of integers that indicates the shape of the array, whose indices are being generated.

result_shape a strategy for generating tuples of integers, which describe the shape of the resulting index arrays. The default is array_shapes() . The shape drawn from this strategy determines the shape of the array that will be produced when the corresponding example from integer_array_indices is used as an index.

dtype the integer data type of the generated index-arrays. Negative integer indices can be generated if a signed integer type is specified.

Recall that an array can be indexed using a tuple of integer-arrays to access its members in an arbitrary order, producing an array with an arbitrary shape. For example:

Note that this strategy does not accommodate all variations of so-called ‘advanced indexing’, as prescribed by NumPy’s nomenclature. Combinations of basic and advanced indexes are too complex to usefully define in a standard strategy; we leave application-specific strategies to the user. Advanced-boolean indexing can be defined as arrays(shape=..., dtype=bool) , and is similarly left to the user.

Hypothesis provides strategies for several of the core pandas data types: pandas.Index , pandas.Series and pandas.DataFrame .

The general approach taken by the pandas module is that there are multiple strategies for generating indexes, and all of the other strategies take the number of entries they contain from their index strategy (with sensible defaults). So e.g. a Series is specified by specifying its numpy.dtype (and/or a strategy for generating elements for it).

Provides a strategy for producing a pandas.Index .

elements is a strategy which will be used to generate the individual values of the index. If None, it will be inferred from the dtype. Note: even if the elements strategy produces tuples, the generated value will not be a MultiIndex, but instead be a normal index whose elements are tuples.

dtype is the dtype of the resulting index. If None, it will be inferred from the elements strategy. At least one of dtype or elements must be provided.

min_size is the minimum number of elements in the index.

max_size is the maximum number of elements in the index. If None then it will default to a suitable small size. If you want larger indexes you should pass a max_size explicitly.

unique specifies whether all of the elements in the resulting index should be distinct.

name is a strategy for strings or None , which will be passed to the pandas.Index constructor.

Provides a strategy which generates an Index whose values are 0, 1, …, n for some n.

min_size is the smallest number of elements the index can have.

max_size is the largest number of elements the index can have. If None it will default to some suitable value based on min_size.

name is the name of the index. If st.none(), the index will have no name.

Provides a strategy for producing a pandas.Series .

elements: a strategy that will be used to generate the individual values in the series. If None, we will attempt to infer a suitable default from the dtype.

dtype: the dtype of the resulting series and may be any value that can be passed to numpy.dtype . If None, will use pandas’s standard behaviour to infer it from the type of the elements values. Note that if the type of values that comes out of your elements strategy varies, then so will the resulting dtype of the series.

index: If not None, a strategy for generating indexes for the resulting Series. This can generate either pandas.Index objects or any sequence of values (which will be passed to the Index constructor).

You will probably find it most convenient to use the indexes() or range_indexes() function to produce values for this argument.

name: is a strategy for strings or None , which will be passed to the pandas.Series constructor.

Data object for describing a column in a DataFrame.

name: the column name, or None to default to the column position. Must be hashable, but can otherwise be any value supported as a pandas column name.

elements: the strategy for generating values in this column, or None to infer it from the dtype.

dtype: the dtype of the column, or None to infer it from the element strategy. At least one of dtype or elements must be provided.

fill: A default value for elements of the column. See arrays() for a full explanation.

unique: If all values in this column should be distinct.

A convenience function for producing a list of column objects of the same general shape.

The names_or_number argument is either a sequence of values, the elements of which will be used as the name for individual column objects, or a number, in which case that many unnamed columns will be created. All other arguments are passed through verbatim to create the columns.

Provides a strategy for producing a pandas.DataFrame .

columns: An iterable of column objects describing the shape of the generated DataFrame.

rows: A strategy for generating a row object. Should generate either dicts mapping column names to values or a sequence mapping column position to the value in that position (note that unlike the pandas.DataFrame constructor, single values are not allowed here. Passing e.g. an integer is an error, even if there is only one column).

At least one of rows and columns must be provided. If both are provided then the generated rows will be validated against the columns and an error will be raised if they don’t match.

Caveats on using rows:

In general you should prefer using columns to rows, and only use rows if the columns interface is insufficiently flexible to describe what you need - you will get better performance and example quality that way.

If you provide rows and not columns, then the shape and dtype of the resulting DataFrame may vary. e.g. if you have a mix of int and float in the values for one column in your row entries, the column will sometimes have an integral dtype and sometimes a float.

index: If not None, a strategy for generating indexes for the resulting DataFrame. This can generate either pandas.Index objects or any sequence of values (which will be passed to the Index constructor).

The expected usage pattern is that you use column and columns() to specify a fixed shape of the DataFrame you want as follows. For example the following gives a two column data frame:

If you want the values in different columns to interact in some way you can use the rows argument. For example the following gives a two column DataFrame where the value in the first column is always at most the value in the second:

You can also combine the two:

(Note that the column dtype must still be specified and will not be inferred from the rows. This restriction may be lifted in future).

Combining rows and columns has the following behaviour:

The column names and dtypes will be used.

If the column is required to be unique, this will be enforced.

Any values missing from the generated rows will be provided using the column’s fill.

Any values in the row not present in the column specification (if dicts are passed, if there are keys with no corresponding column name, if sequences are passed if there are too many items) will result in InvalidArgument being raised.

Supported versions ¶

There is quite a lot of variation between pandas versions. We only commit to supporting the latest version of pandas, but older minor versions are supported on a “best effort” basis. Hypothesis is currently tested against and confirmed working with every Pandas minor version from 1.1 through to 2.2.

Releases that are not the latest patch release of their minor version are not tested or officially supported, but will probably also work unless you hit a pandas bug.

Array API ¶

Hypothesis offers strategies for Array API adopting libraries in the hypothesis.extra.array_api package. See issue #3037 for more details. If you want to test with CuPy , Dask , JAX , MXNet , PyTorch , TensorFlow , or Xarray - or just NumPy - this is the extension for you!

Creates a strategies namespace for the given array module.

xp is the Array API library to automatically pass to the namespaced methods.

api_version is the version of the Array API which the returned strategies namespace should conform to. If None , the latest API version which xp supports will be inferred from xp.__array_api_version__ . If a version string in the YYYY.MM format, the strategies namespace will conform to that version if supported.

A types.SimpleNamespace is returned which contains all the strategy methods in this module but without requiring the xp argument. Creating and using a strategies namespace for NumPy’s Array API implementation would go like this:

The resulting namespace contains all our familiar strategies like arrays() and from_dtype() , but based on the Array API standard semantics and returning objects from the xp module:

Return a strategy for any value of the given dtype.

Values generated are of the Python scalar which is promotable to dtype , where the values do not exceed its bounds.

dtype may be a dtype object or the string name of a valid dtype .

Compatible **kwargs are passed to the inferred strategy function for integers and floats. This allows you to customise the min and max values, and exclude non-finite numbers. This is particularly useful when kwargs are passed through from arrays() , as it seamlessly handles the width or other representable bounds for you.

Returns a strategy for arrays .

dtype may be a valid dtype object or name, or a strategy that generates such values.

elements is a strategy for values to put in the array. If None then a suitable value will be inferred based on the dtype, which may give any legal value (including e.g. NaN for floats). If a mapping, it will be passed as **kwargs to from_dtype() when inferring based on the dtype.

fill is a strategy that may be used to generate a single background value for the array. If None , a suitable default will be inferred based on the other arguments. If set to nothing() then filling behaviour will be disabled entirely and every element will be generated independently.

unique specifies if the elements of the array should all be distinct from one another; if fill is also set, the only valid values for fill to return are NaN values.

Specifying element boundaries by a dict of the kwargs to pass to from_dtype() will ensure dtype bounds will be respected.

Refer to What you can generate and how for passing your own elements strategy.

A single value is drawn from the fill strategy and is used to create a filled array.

You can set fill to nothing() if you want to disable this behaviour and draw a value for every element.

By default arrays will attempt to infer the correct fill behaviour: if unique is also True , no filling will occur. Otherwise, if it looks safe to reuse the values of elements across multiple coordinates (this will be the case for any inferred strategy, and for most of the builtins, but is not the case for mutable values or strategies built with flatmap, map, composite, etc.) then it will use the elements strategy as the fill, else it will default to having no fill.

Return a strategy for all valid dtype objects.

Return a strategy for just the boolean dtype object.

Return a strategy for all numeric dtype objects.

Return a strategy for all real-valued dtype objects.

Return a strategy for signed integer dtype objects.

sizes contains the signed integer sizes in bits, defaulting to (8, 16, 32, 64) which covers all valid sizes.

Return a strategy for unsigned integer dtype objects.

sizes contains the unsigned integer sizes in bits, defaulting to (8, 16, 32, 64) which covers all valid sizes.

Return a strategy for real-valued floating-point dtype objects.

sizes contains the floating-point sizes in bits, defaulting to (32, 64) which covers all valid sizes.

Return a strategy for complex dtype objects.

sizes contains the complex sizes in bits, defaulting to (64, 128) which covers all valid sizes.

Return a strategy for permissible tuple-values for the axis argument in Array API sequential methods e.g. sum , given the specified dimensionality.

Return a strategy for valid indices of arrays with the specified shape, which may include dimensions of size zero.

shape is the shape of the array that will be indexed, as a tuple of integers >= 0. This must be at least two-dimensional for a tuple to be a valid index; for one-dimensional arrays use slices() instead.

min_dims is the minimum dimensionality of the resulting array from use of the generated index.

allow_ellipsis specifies whether None is allowed in the index.

Python Tutorial

File handling, python modules, python numpy, python pandas, python matplotlib, python scipy, machine learning, python mysql, python mongodb, python reference, module reference, python how to, python examples, python dictionaries.

Dictionaries are used to store data values in key:value pairs.

A dictionary is a collection which is ordered*, changeable and do not allow duplicates.

As of Python version 3.7, dictionaries are ordered . In Python 3.6 and earlier, dictionaries are unordered .

Dictionaries are written with curly brackets, and have keys and values:

Create and print a dictionary:

Dictionary Items

Dictionary items are ordered, changeable, and do not allow duplicates.

Dictionary items are presented in key:value pairs, and can be referred to by using the key name.

Print the "brand" value of the dictionary:

Ordered or Unordered?

When we say that dictionaries are ordered, it means that the items have a defined order, and that order will not change.

Unordered means that the items do not have a defined order, you cannot refer to an item by using an index.

Dictionaries are changeable, meaning that we can change, add or remove items after the dictionary has been created.

Duplicates Not Allowed

Dictionaries cannot have two items with the same key:

Duplicate values will overwrite existing values:

Advertisement

Dictionary Length

To determine how many items a dictionary has, use the len() function:

Print the number of items in the dictionary:

Dictionary Items - Data Types

The values in dictionary items can be of any data type:

String, int, boolean, and list data types:

From Python's perspective, dictionaries are defined as objects with the data type 'dict':

Print the data type of a dictionary:

The dict() Constructor

It is also possible to use the dict() constructor to make a dictionary.

Using the dict() method to make a dictionary:

Python Collections (Arrays)

There are four collection data types in the Python programming language:

• List is a collection which is ordered and changeable. Allows duplicate members.
• Tuple is a collection which is ordered and unchangeable. Allows duplicate members.
• Set is a collection which is unordered, unchangeable*, and unindexed. No duplicate members.
• Dictionary is a collection which is ordered** and changeable. No duplicate members.

*Set items are unchangeable, but you can remove and/or add items whenever you like.

**As of Python version 3.7, dictionaries are ordered . In Python 3.6 and earlier, dictionaries are unordered .

When choosing a collection type, it is useful to understand the properties of that type. Choosing the right type for a particular data set could mean retention of meaning, and, it could mean an increase in efficiency or security.

COLOR PICKER

Contact Sales

If you want to use W3Schools services as an educational institution, team or enterprise, send us an e-mail: [email protected]

Report Error

If you want to report an error, or if you want to make a suggestion, send us an e-mail: [email protected]

Top Tutorials

Top references, top examples, get certified.

• Stack Overflow for Teams Where developers & technologists share private knowledge with coworkers
• Advertising & Talent Reach devs & technologists worldwide about your product, service or employer brand
• OverflowAI GenAI features for Teams
• OverflowAPI Train & fine-tune LLMs
• Labs The future of collective knowledge sharing
• About the company Visit the blog

Collectives™ on Stack Overflow

Find centralized, trusted content and collaborate around the technologies you use most.

Q&A for work

Connect and share knowledge within a single location that is structured and easy to search.

Get early access and see previews of new features.

Hypothesis (Python): Omit argument

I have a function like so (it's actually a class, but that's not relevant given Python's duck typing):

Now I want to write a Hypothesis test which always supplies a , but only sometimes b .

But it seems that when it gets strat.nothing() just skips that test run (I get hypothesis.errors.FailedHealthCheck: It looks like your strategy is filtering out a lot of data. when using that as the sole strategy for b ).

How can I only sometimes supply an argument with a Hypothesis test? Do I need to write two tests, one with b and one without?

• python-hypothesis

4 Answers 4

Your approach is guaranteed to fail, because, as the hypothesis docs imply

your attempt not to provide a value for b will always fail.

How about this:

which, over a bunch of trials, gave me outputs such as (True,) , (False, 9) , (False, 4) , (True, 5) and (False,) .

You would, of course, use this with *args rather than **kwargs .

• Unfortunately, because I have more than 1 "optional" argument (I simplified it for the question), keyword arguments are necessary. Also, if the function accepts *args or **kwargs , then you can't supply positional arguments to @given (see is_invalid_test in these docs) - you'd need function parameters of (self, args) - note no * . Thanks for the suggestions though - they did put me on the right track. –  Scott Stevens Commented Nov 14, 2017 at 11:57

jacq's answer put me on the right track - the selection of keywords needs to be its own strategy.

With the standard dictionary

and the optional dictionary

I can then use chained list comprehension for all the possible "optional argument combinations":

That generates the key-value tuples for b , c , and (b, c) .

In order to draw a set of values, we need to get one of those options, which can be done with sampled_from(optional) . With the obtained tuples, we must draw from the strategies within, in addition to those in the std dictionary.

This can all be wrapped in a function, let's call it valid_values() . You can't use @given(valid_values()) if you specify *args or **kwargs in the signature of the wrapped function.

As a result, test_model_properties(self, **kwargs) becomes test_model_properties(self, kwargs) (and you can use @given(kwargs=valid_values()) ) - by calling the dictionary kwargs , the rest of the function remains unchanged.

Note: This will not include an empty tuple if you want the possibility of no optional parameters, but that can be appended to the optional list easily. Alternatively, have range(n+1) instead of combinations(..., n+1) , hence including a length of 0.

It looks like you want none() instead of nothing() :

This is simpler than generating dictionaries to use as **kwargs and a little more efficient too. Ordering of the strategies for b is also important - putting none() first ensures that the minimal example will be a=False, b=None instead of a=False, b=1 .

Also note that applying @given multiple times is very inefficient compared to a single use, and actually deprecated since version 3.34.0.

So you let b being the default value (in this case, None ) trigger an 'if' condition inside myfunc() that sets it to something else.

• I want to test the default values of myfunc , so I actually have that code in place already - I need the test to sometimes call with b set, and sometimes not. –  Scott Stevens Commented Nov 1, 2017 at 9:57

Your Answer

Reminder: Answers generated by artificial intelligence tools are not allowed on Stack Overflow. Learn more

Sign up or log in

Post as a guest.

Required, but never shown

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy .

Not the answer you're looking for? Browse other questions tagged python python-3.x python-hypothesis or ask your own question .

• Featured on Meta
• We've made changes to our Terms of Service & Privacy Policy - July 2024
• Announcing a change to the data-dump process

Hot Network Questions

• How can DC charge a capacitor?
• ORCA 6 slower than ORCA 5?
• Is it realistic that I can fit and maintain 22 trillion people without the need to eat in East Asia?
• Why is transfer of heat very slow as compared to transfer of sound in solids?
• What is the “history“ of mindfulness
• Absolute invisibility in cosmos
• Smallest positive integer problem.
• Newtonian vs General Relativistic light deflection angle
• How can Blowfish be resistant against differential cryptanalysis if it doesn't have S-boxes tuned for that?
• What's another word for utopian
• Why would radio-capable transhumans still vocalise to each-other?
• How to contain a transcontinental empire?
• Blocking access to `*.php` in `.well-known`
• Can you be resurrected while your soul is under the effect of Magic Jar?
• Political Relations on an Interstellar Scale
• Was homology influenced by Euler's polyhedron formula?
• Was the idea of foxes with many tails invented in anime, or is it a Japanese folk religion thing?
• Will the dense subset of an uncountable set remain dense if we remove a single element?
• Does apt-add-reposity add gpg keys to the infamous and ill-reputed keyring /etc/apt/trusted.gpg?
• When Beatrix stops placing dominoes on a 5x5 board, what is the largest possible number of squares that may still be uncovered?
• F-test for nested GLM
• Generating Random Polytopes for Nonconvex Optimization
• Why do doctors always seem to overcharge for services?
• Is it bad to have similar themes between my novels?