This file is indexed.

/usr/share/doc/python-hypothesis/html/data.html is in python-hypothesis-doc 3.44.1-2ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>What you can generate and how &mdash; Hypothesis 3.44.1 documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
        <link rel="index" title="Index"
              href="genindex.html"/>
        <link rel="search" title="Search" href="search.html"/>
    <link rel="top" title="Hypothesis 3.44.1 documentation" href="index.html"/>
        <link rel="next" title="Additional packages" href="extras.html"/>
        <link rel="prev" title="Settings" href="settings.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="index.html" class="icon icon-home"> Hypothesis
          

          
          </a>

          
            
            
              <div class="version">
                3.44.1
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick start guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="details.html">Details and advanced features</a></li>
<li class="toctree-l1"><a class="reference internal" href="settings.html">Settings</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">What you can generate and how</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#shrinking">Shrinking</a></li>
<li class="toctree-l2"><a class="reference internal" href="#adapting-strategies">Adapting strategies</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#mapping">Mapping</a></li>
<li class="toctree-l3"><a class="reference internal" href="#filtering">Filtering</a></li>
<li class="toctree-l3"><a class="reference internal" href="#chaining-strategies-together">Chaining strategies together</a></li>
<li class="toctree-l3"><a class="reference internal" href="#recursive-data">Recursive data</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#composite-strategies">Composite strategies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#drawing-interactively-in-tests">Drawing interactively in tests</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="extras.html">Additional packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="django.html">Hypothesis for Django users</a></li>
<li class="toctree-l1"><a class="reference internal" href="numpy.html">Hypothesis for the Scientific Stack</a></li>
<li class="toctree-l1"><a class="reference internal" href="healthchecks.html">Health checks</a></li>
<li class="toctree-l1"><a class="reference internal" href="database.html">The Hypothesis Example Database</a></li>
<li class="toctree-l1"><a class="reference internal" href="stateful.html">Stateful testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="supported.html">Compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Some more examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="community.html">Community</a></li>
<li class="toctree-l1"><a class="reference internal" href="manifesto.html">The Purpose of Hypothesis</a></li>
<li class="toctree-l1"><a class="reference internal" href="endorsements.html">Testimonials</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Open Source Projects using Hypothesis</a></li>
<li class="toctree-l1"><a class="reference internal" href="strategies.html">Projects extending Hypothesis</a></li>
<li class="toctree-l1"><a class="reference internal" href="changes.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Ongoing Hypothesis Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Help and Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="packaging.html">Packaging Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="reproducing.html">Reproducing Failures</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">Hypothesis</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="index.html">Docs</a> &raquo;</li>
        
      <li>What you can generate and how</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/data.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="what-you-can-generate-and-how">
<h1>What you can generate and how<a class="headerlink" href="#what-you-can-generate-and-how" title="Permalink to this headline"></a></h1>
<p><em>Most things should be easy to generate and everything should be possible.</em></p>
<p>To support this principle Hypothesis provides strategies for most built-in
types with arguments to constrain or adjust the output, as well as higher-order
strategies that can be composed to generate more complex types.</p>
<p>This document is a guide to what strategies are available for generating data
and how to build them. Strategies have a variety of other important internal
features, such as how they simplify, but the data they can generate is the only
public part of their API.</p>
<p>Functions for building strategies are all available in the hypothesis.strategies
module. The salient functions from it are as follows:</p>
<span class="target" id="module-hypothesis.strategies"></span><dl class="function">
<dt id="hypothesis.strategies.nothing">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">nothing</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#nothing"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.nothing" title="Permalink to this definition"></a></dt>
<dd><p>This strategy never successfully draws a value and will always reject on
an attempt to draw.</p>
<p>Examples from this strategy do not shrink (because there are none).</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.just">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">just</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#just"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.just" title="Permalink to this definition"></a></dt>
<dd><p>Return a strategy which only generates <code class="docutils literal"><span class="pre">value</span></code>.</p>
<p>Note: <code class="docutils literal"><span class="pre">value</span></code> is not copied. Be wary of using mutable values.</p>
<p>If <code class="docutils literal"><span class="pre">value</span></code> is the result of a callable, you can use
<a class="reference internal" href="#hypothesis.strategies.builds" title="hypothesis.strategies.builds"><code class="xref py py-func docutils literal"><span class="pre">builds(callable)</span></code></a> instead
of <code class="docutils literal"><span class="pre">just(callable())</span></code> to get a fresh value each time.</p>
<p>Examples from this strategy do not shrink (because there is only one).</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.none">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">none</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#none"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.none" title="Permalink to this definition"></a></dt>
<dd><p>Return a strategy which only generates None.</p>
<p>Examples from this strategy do not shrink (because there is only
one).</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.one_of">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">one_of</code><span class="sig-paren">(</span><em>*args</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#one_of"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.one_of" title="Permalink to this definition"></a></dt>
<dd><p>Return a strategy which generates values from any of the argument
strategies.</p>
<p>This may be called with one iterable argument instead of multiple
strategy arguments. In which case one_of(x) and one_of(*x) are
equivalent.</p>
<p>Examples from this strategy will generally shrink to ones that come from
strategies earlier in the list, then shrink according to behaviour of the
strategy that produced them. In order to get good shrinking behaviour,
try to put simpler strategies first. e.g. <code class="docutils literal"><span class="pre">one_of(none(),</span> <span class="pre">text())</span></code> is
better than <code class="docutils literal"><span class="pre">one_of(text(),</span> <span class="pre">none())</span></code>.</p>
<p>This is especially important when using recursive strategies. e.g.
<code class="docutils literal"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">st.deferred(lambda:</span> <span class="pre">st.none()</span> <span class="pre">|</span> <span class="pre">st.tuples(x,</span> <span class="pre">x))</span></code> will shrink well,
but <code class="docutils literal"><span class="pre">x</span> <span class="pre">=</span> <span class="pre">st.deferred(lambda:</span> <span class="pre">st.tuples(x,</span> <span class="pre">x)</span> <span class="pre">|</span> <span class="pre">st.none())</span></code> will shrink
very badly indeed.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.integers">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">integers</code><span class="sig-paren">(</span><em>min_value=None</em>, <em>max_value=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#integers"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.integers" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy which generates integers (in Python 2 these may be
ints or longs).</p>
<p>If min_value is not None then all values will be &gt;= min_value. If
max_value is not None then all values will be &lt;= max_value</p>
<p>Examples from this strategy will shrink towards being positive (e.g. 1000
is considered simpler than -1) and then towards zero.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.booleans">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">booleans</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#booleans"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.booleans" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy which generates instances of bool.</p>
<p>Examples from this strategy will shrink towards False (i.e.
shrinking will try to replace True with False where possible).</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.floats">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">floats</code><span class="sig-paren">(</span><em>min_value=None</em>, <em>max_value=None</em>, <em>allow_nan=None</em>, <em>allow_infinity=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#floats"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.floats" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy which generates floats.</p>
<ul class="simple">
<li>If min_value is not None, all values will be &gt;= min_value.</li>
<li>If max_value is not None, all values will be &lt;= max_value.</li>
<li>If min_value or max_value is not None, it is an error to enable
allow_nan.</li>
<li>If both min_value and max_value are not None, it is an error to enable
allow_infinity.</li>
</ul>
<p>Where not explicitly ruled out by the bounds, all of infinity, -infinity
and NaN are possible values generated by this strategy.</p>
<p>Examples from this strategy have a complicated and hard to explain
shrinking behaviour, but it tries to improve “human readability”. Finite
numbers will be preferred to infinity and infinity will be preferred to
NaN.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.complex_numbers">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">complex_numbers</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#complex_numbers"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.complex_numbers" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy that generates complex numbers.</p>
<p>Examples from this strategy shrink by shrinking their component real
and imaginary parts.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.tuples">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">tuples</code><span class="sig-paren">(</span><em>*args</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#tuples"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.tuples" title="Permalink to this definition"></a></dt>
<dd><p>Return a strategy which generates a tuple of the same length as args by
generating the value at index i from args[i].</p>
<p>e.g. tuples(integers(), integers()) would generate a tuple of length
two with both values an integer.</p>
<p>Examples from this strategy shrink by shrinking their component parts.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.sampled_from">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">sampled_from</code><span class="sig-paren">(</span><em>elements</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#sampled_from"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.sampled_from" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy which generates any value present in <code class="docutils literal"><span class="pre">elements</span></code>.</p>
<p>Note that as with <code class="xref py py-func docutils literal"><span class="pre">just()</span></code>, values will not be
copied and thus you should be careful of using mutable data.</p>
<p><code class="docutils literal"><span class="pre">sampled_from</span></code> supports ordered collections, as well as
<code class="xref py py-class docutils literal"><span class="pre">Enum</span></code> objects.  <code class="xref py py-class docutils literal"><span class="pre">Flag</span></code> objects
may also generate any combination of their members.</p>
<p>Examples from this strategy shrink by replacing them with values earlier in
the list. So e.g. sampled_from((10, 1)) will shrink by trying to replace
1 values with 10, and sampled_from((1, 10)) will shrink by trying to
replace 10 values with 1.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.lists">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">lists</code><span class="sig-paren">(</span><em>elements=None</em>, <em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em>, <em>unique_by=None</em>, <em>unique=False</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#lists"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.lists" title="Permalink to this definition"></a></dt>
<dd><p>Returns a list containing values drawn from elements with length in the
interval [min_size, max_size] (no bounds in that direction if these are
None). If max_size is 0 then elements may be None and only the empty list
will be drawn.</p>
<p>average_size may be used as a size hint to roughly control the size
of the list but it may not be the actual average of sizes you get, due
to a variety of factors.</p>
<p>If unique is True (or something that evaluates to True), we compare direct
object equality, as if unique_by was <cite>lambda x: x</cite>. This comparison only
works for hashable types.</p>
<p>if unique_by is not None it must be a function returning a hashable type
when given a value drawn from elements. The resulting list will satisfy the
condition that for i != j, unique_by(result[i]) != unique_by(result[j]).</p>
<p>Examples from this strategy shrink by trying to remove elements from the
list, and by shrinking each individual element of the list.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.sets">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">sets</code><span class="sig-paren">(</span><em>elements=None</em>, <em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#sets"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.sets" title="Permalink to this definition"></a></dt>
<dd><p>This has the same behaviour as lists, but returns sets instead.</p>
<p>Note that Hypothesis cannot tell if values are drawn from elements
are hashable until running the test, so you can define a strategy
for sets of an unhashable type but it will fail at test time.</p>
<p>Examples from this strategy shrink by trying to remove elements from the
set, and by shrinking each individual element of the set.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.frozensets">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">frozensets</code><span class="sig-paren">(</span><em>elements=None</em>, <em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#frozensets"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.frozensets" title="Permalink to this definition"></a></dt>
<dd><p>This is identical to the sets function but instead returns
frozensets.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.iterables">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">iterables</code><span class="sig-paren">(</span><em>elements=None</em>, <em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em>, <em>unique_by=None</em>, <em>unique=False</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#iterables"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.iterables" title="Permalink to this definition"></a></dt>
<dd><p>This has the same behaviour as lists, but returns iterables instead.</p>
<p>Some iterables cannot be indexed (e.g. sets) and some do not have a
fixed length (e.g. generators). This strategy produces iterators,
which cannot be indexed and do not have a fixed length. This ensures
that you do not accidentally depend on sequence behaviour.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.fixed_dictionaries">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">fixed_dictionaries</code><span class="sig-paren">(</span><em>mapping</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#fixed_dictionaries"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.fixed_dictionaries" title="Permalink to this definition"></a></dt>
<dd><p>Generates a dictionary of the same type as mapping with a fixed set of
keys mapping to strategies. mapping must be a dict subclass.</p>
<p>Generated values have all keys present in mapping, with the
corresponding values drawn from mapping[key]. If mapping is an
instance of OrderedDict the keys will also be in the same order,
otherwise the order is arbitrary.</p>
<p>Examples from this strategy shrink by shrinking each individual value in
the generated dictionary.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.dictionaries">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">dictionaries</code><span class="sig-paren">(</span><em>keys</em>, <em>values</em>, <em>dict_class=&lt;class 'dict'&gt;</em>, <em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#dictionaries"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.dictionaries" title="Permalink to this definition"></a></dt>
<dd><p>Generates dictionaries of type dict_class with keys drawn from the keys
argument and values drawn from the values argument.</p>
<p>The size parameters have the same interpretation as for lists.</p>
<p>Examples from this strategy shrink by trying to remove keys from the
generated dictionary, and by shrinking each generated key and value.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.streaming">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">streaming</code><span class="sig-paren">(</span><em>elements</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#streaming"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.streaming" title="Permalink to this definition"></a></dt>
<dd><p>Generates an infinite stream of values where each value is drawn from
elements.</p>
<p>The result is iterable (the iterator will never terminate) and
indexable.</p>
<p>Examples from this strategy shrink by trying to shrink each value drawn.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.15.0: </span>Use <a class="reference internal" href="#hypothesis.strategies.data" title="hypothesis.strategies.data"><code class="xref py py-func docutils literal"><span class="pre">data()</span></code></a> instead.</p>
</div>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.characters">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">characters</code><span class="sig-paren">(</span><em>whitelist_categories=None</em>, <em>blacklist_categories=None</em>, <em>blacklist_characters=None</em>, <em>min_codepoint=None</em>, <em>max_codepoint=None</em>, <em>whitelist_characters=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#characters"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.characters" title="Permalink to this definition"></a></dt>
<dd><p>Generates unicode text type (unicode on python 2, str on python 3)
characters following specified filtering rules.</p>
<p>When no filtering rules are specifed, any character can be produced.</p>
<p>If <code class="docutils literal"><span class="pre">min_codepoint</span></code> or <code class="docutils literal"><span class="pre">max_codepoint</span></code> is specifed, then only
characters having a codepoint in that range will be produced.</p>
<p>If <code class="docutils literal"><span class="pre">whitelist_categories</span></code> is specified, then only characters from those
Unicode categories will be produced. This is a further restriction,
characters must also satisfy <code class="docutils literal"><span class="pre">min_codepoint</span></code> and <code class="docutils literal"><span class="pre">max_codepoint</span></code>.</p>
<p>If <code class="docutils literal"><span class="pre">blacklist_categories</span></code> is specified, then any character from those
categories will not be produced. This is a further restriction,
characters that match both <code class="docutils literal"><span class="pre">whitelist_categories</span></code> and
<code class="docutils literal"><span class="pre">blacklist_categories</span></code> will not be produced.</p>
<p>If <code class="docutils literal"><span class="pre">whitelist_characters</span></code> is specified, then any additional characters
in that list will also be produced.</p>
<p>If <code class="docutils literal"><span class="pre">blacklist_characters</span></code> is specified, then any characters in that list
will be not be produced. Any overlap between <code class="docutils literal"><span class="pre">whitelist_characters</span></code> and
<code class="docutils literal"><span class="pre">blacklist_characters</span></code> will raise an exception.</p>
<p>Examples from this strategy shrink towards smaller codepoints.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.text">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">text</code><span class="sig-paren">(</span><em>alphabet=None</em>, <em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#text"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.text" title="Permalink to this definition"></a></dt>
<dd><p>Generates values of a unicode text type (unicode on python 2, str on
python 3) with values drawn from alphabet, which should be an iterable of
length one strings or a strategy generating such. If it is None it will
default to generating the full unicode range. If it is an empty collection
this will only generate empty strings.</p>
<p>min_size, max_size and average_size have the usual interpretations.</p>
<p>Examples from this strategy shrink towards shorter strings, and with the
characters in the text shrinking as per the alphabet strategy.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.from_regex">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">from_regex</code><span class="sig-paren">(</span><em>regex</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#from_regex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.from_regex" title="Permalink to this definition"></a></dt>
<dd><p>Generates strings that contain a match for the given regex (i.e. ones
for which <code class="xref py py-func docutils literal"><span class="pre">re.search()</span></code> will return a non-None result).</p>
<p><code class="docutils literal"><span class="pre">regex</span></code> may be a pattern or <code class="xref py py-func docutils literal"><span class="pre">compiled</span> <span class="pre">regex</span></code>.
Both byte-strings and unicode strings are supported, and will generate
examples of the same type.</p>
<p>You can use regex flags such as <code class="xref py py-const docutils literal"><span class="pre">re.IGNORECASE</span></code>, <code class="xref py py-const docutils literal"><span class="pre">re.DOTALL</span></code>
or <code class="xref py py-const docutils literal"><span class="pre">re.UNICODE</span></code> to control generation. Flags can be passed either
in compiled regex or inside the pattern with a <code class="docutils literal"><span class="pre">(?iLmsux)</span></code> group.</p>
<p>Some regular expressions are only partly supported - the underlying
strategy checks local matching and relies on filtering to resolve
context-dependent expressions.  Using too many of these constructs may
cause health-check errors as too many examples are filtered out. This
mainly includes (positive or negative) lookahead and lookbehind groups.</p>
<p>If you want the generated string to match the whole regex you should use
boundary markers. So e.g. <code class="docutils literal"><span class="pre">r&quot;\A.\Z&quot;</span></code> will return a single character
string, while <code class="docutils literal"><span class="pre">&quot;.&quot;</span></code> will return any string, and <code class="docutils literal"><span class="pre">r&quot;\A.$&quot;</span></code> will return
a single character optionally followed by a <code class="docutils literal"><span class="pre">&quot;\n&quot;</span></code>.</p>
<p>Examples from this strategy shrink towards shorter strings and lower
character values.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.binary">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">binary</code><span class="sig-paren">(</span><em>min_size=None</em>, <em>average_size=None</em>, <em>max_size=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#binary"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.binary" title="Permalink to this definition"></a></dt>
<dd><p>Generates the appropriate binary type (str in python 2, bytes in python
3).</p>
<p>min_size, average_size and max_size have the usual interpretations.</p>
<p>Examples from this strategy shrink towards smaller strings and lower byte
values.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.randoms">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">randoms</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#randoms"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.randoms" title="Permalink to this definition"></a></dt>
<dd><p>Generates instances of Random (actually a Hypothesis specific
RandomWithSeed class which displays what it was initially seeded with)</p>
<p>Examples from this strategy shrink to seeds closer to zero.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.random_module">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">random_module</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#random_module"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.random_module" title="Permalink to this definition"></a></dt>
<dd><p>If your code depends on the global random module then you need to use
this.</p>
<p>It will explicitly seed the random module at the start of your test
so that tests are reproducible. The value it passes you is an opaque
object whose only useful feature is that its repr displays the
random seed. It is not itself a random number generator. If you want
a random number generator you should use the randoms() strategy
which will give you one.</p>
<p>Examples from these strategy shrink to seeds closer to zero.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.builds">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">builds</code><span class="sig-paren">(</span><em>target</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#builds"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.builds" title="Permalink to this definition"></a></dt>
<dd><p>Generates values by drawing from <code class="docutils literal"><span class="pre">args</span></code> and <code class="docutils literal"><span class="pre">kwargs</span></code> and passing
them to <code class="docutils literal"><span class="pre">target</span></code> in the appropriate argument position.</p>
<p>e.g. <code class="docutils literal"><span class="pre">builds(target,</span> <span class="pre">integers(),</span> <span class="pre">flag=booleans())</span></code> would draw an
integer <code class="docutils literal"><span class="pre">i</span></code> and a boolean <code class="docutils literal"><span class="pre">b</span></code> and call <code class="docutils literal"><span class="pre">target(i,</span> <span class="pre">flag=b)</span></code>.</p>
<p>If <code class="docutils literal"><span class="pre">target</span></code> has type annotations, they will be used to infer a strategy
for required arguments that were not passed to builds.  You can also tell
builds to infer a strategy for an optional argument by passing the special
value <code class="xref py py-const docutils literal"><span class="pre">hypothesis.infer</span></code> as a keyword argument to
builds, instead of a strategy for that argument to <code class="docutils literal"><span class="pre">target</span></code>.</p>
<p>Examples from this strategy shrink by shrinking the argument values to
the target.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.from_type">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">from_type</code><span class="sig-paren">(</span><em>thing</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#from_type"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.from_type" title="Permalink to this definition"></a></dt>
<dd><p>Looks up the appropriate search strategy for the given type.</p>
<p><code class="docutils literal"><span class="pre">from_type</span></code> is used internally to fill in missing arguments to
<a class="reference internal" href="#hypothesis.strategies.builds" title="hypothesis.strategies.builds"><code class="xref py py-func docutils literal"><span class="pre">builds()</span></code></a> and can be used interactively
to explore what strategies are available or to debug type resolution.</p>
<p>You can use <a class="reference internal" href="#hypothesis.strategies.register_type_strategy" title="hypothesis.strategies.register_type_strategy"><code class="xref py py-func docutils literal"><span class="pre">register_type_strategy()</span></code></a> to
handle your custom types, or to globally redefine certain strategies -
for example excluding NaN from floats, or use timezone-aware instead of
naive time and datetime strategies.</p>
<p>The resolution logic may be changed in a future version, but currently
tries these four options:</p>
<ol class="arabic simple">
<li>If <code class="docutils literal"><span class="pre">thing</span></code> is in the default lookup mapping or user-registered lookup,
return the corresponding strategy.  The default lookup covers all types
with Hypothesis strategies, including extras where possible.</li>
<li>If <code class="docutils literal"><span class="pre">thing</span></code> is from the <code class="xref py py-mod docutils literal"><span class="pre">python:typing</span></code> module, return the
corresponding strategy (special logic).</li>
<li>If <code class="docutils literal"><span class="pre">thing</span></code> has one or more subtypes in the merged lookup, return
the union of the strategies for those types that are not subtypes of
other elements in the lookup.</li>
<li>Finally, if <code class="docutils literal"><span class="pre">thing</span></code> has type annotations for all required arguments,
it is resolved via <a class="reference internal" href="#hypothesis.strategies.builds" title="hypothesis.strategies.builds"><code class="xref py py-func docutils literal"><span class="pre">builds()</span></code></a>.</li>
</ol>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.fractions">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">fractions</code><span class="sig-paren">(</span><em>min_value=None</em>, <em>max_value=None</em>, <em>max_denominator=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#fractions"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.fractions" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy which generates Fractions.</p>
<p>If min_value is not None then all generated values are no less than
min_value.  If max_value is not None then all generated values are no
greater than max_value.  min_value and max_value may be anything accepted
by the <code class="xref py py-class docutils literal"><span class="pre">Fraction</span></code> constructor.</p>
<p>If max_denominator is not None then the denominator of any generated
values is no greater than max_denominator. Note that max_denominator must
be None or a positive integer.</p>
<p>Examples from this strategy shrink towards smaller denominators, then
closer to zero.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.decimals">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">decimals</code><span class="sig-paren">(</span><em>min_value=None</em>, <em>max_value=None</em>, <em>allow_nan=None</em>, <em>allow_infinity=None</em>, <em>places=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#decimals"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.decimals" title="Permalink to this definition"></a></dt>
<dd><p>Generates instances of <code class="xref py py-class docutils literal"><span class="pre">decimals.Decimal</span></code>, which may be:</p>
<ul class="simple">
<li>A finite rational number, between <code class="docutils literal"><span class="pre">min_value</span></code> and <code class="docutils literal"><span class="pre">max_value</span></code>.</li>
<li>Not a Number, if <code class="docutils literal"><span class="pre">allow_nan</span></code> is True.  None means “allow NaN, unless
<code class="docutils literal"><span class="pre">min_value</span></code> and <code class="docutils literal"><span class="pre">max_value</span></code> are not None”.</li>
<li>Positive or negative infinity, if <code class="docutils literal"><span class="pre">max_value</span></code> and <code class="docutils literal"><span class="pre">min_value</span></code>
respectively are None, and <code class="docutils literal"><span class="pre">allow_infinity</span></code> is not False.  None means
“allow infinity, unless excluded by the min and max values”.</li>
</ul>
<p>Note that where floats have one <code class="docutils literal"><span class="pre">NaN</span></code> value, Decimals have four: signed,
and either <em>quiet</em> or <em>signalling</em>.  See <a class="reference external" href="https://docs.python.org/3/library/decimal.html#special-values">the decimal module docs</a> for
more information on special values.</p>
<p>If <code class="docutils literal"><span class="pre">places</span></code> is not None, all finite values drawn from the strategy will
have that number of digits after the decimal place.</p>
<p>Examples from this strategy do not have a well defined shrink order but
try to maximize human readability when shrinking.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.recursive">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">recursive</code><span class="sig-paren">(</span><em>base</em>, <em>extend</em>, <em>max_leaves=100</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#recursive"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.recursive" title="Permalink to this definition"></a></dt>
<dd><p>base: A strategy to start from.</p>
<p>extend: A function which takes a strategy and returns a new strategy.</p>
<p>max_leaves: The maximum number of elements to be drawn from base on a given
run.</p>
<p>This returns a strategy <code class="docutils literal"><span class="pre">S</span></code> such that <code class="docutils literal"><span class="pre">S</span> <span class="pre">=</span> <span class="pre">extend(base</span> <span class="pre">|</span> <span class="pre">S)</span></code>. That is,
values may be drawn from base, or from any strategy reachable by mixing
applications of | and extend.</p>
<p>An example may clarify: <code class="docutils literal"><span class="pre">recursive(booleans(),</span> <span class="pre">lists)</span></code> would return a
strategy that may return arbitrarily nested and mixed lists of booleans.
So e.g. <code class="docutils literal"><span class="pre">False</span></code>, <code class="docutils literal"><span class="pre">[True]</span></code>, <code class="docutils literal"><span class="pre">[False,</span> <span class="pre">[]]</span></code>, and <code class="docutils literal"><span class="pre">[[[[True]]]]</span></code> are
all valid values to be drawn from that strategy.</p>
<p>Examples from this strategy shrink by trying to reduce the amount of
recursion and by shrinking according to the shrinking behaviour of base
and the result of extend.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.permutations">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">permutations</code><span class="sig-paren">(</span><em>values</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#permutations"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.permutations" title="Permalink to this definition"></a></dt>
<dd><p>Return a strategy which returns permutations of the collection
<code class="docutils literal"><span class="pre">values</span></code>.</p>
<p>Examples from this strategy shrink by trying to become closer to the
original order of values.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.datetimes">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">datetimes</code><span class="sig-paren">(</span><em>min_value=datetime.datetime(1</em>, <em>1</em>, <em>1</em>, <em>0</em>, <em>0)</em>, <em>max_value=datetime.datetime(9999</em>, <em>12</em>, <em>31</em>, <em>23</em>, <em>59</em>, <em>59</em>, <em>999999)</em>, <em>timezones=none()</em>, <em>min_datetime=None</em>, <em>max_datetime=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#datetimes"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.datetimes" title="Permalink to this definition"></a></dt>
<dd><p>A strategy for generating datetimes, which may be timezone-aware.</p>
<blockquote>
<div><p>This strategy works by drawing a naive datetime between <code class="docutils literal"><span class="pre">min_datetime</span></code>
and <code class="docutils literal"><span class="pre">max_datetime</span></code>, which must both be naive (have no timezone).</p>
<p><code class="docutils literal"><span class="pre">timezones</span></code> must be a strategy that generates tzinfo objects (or None,
which is valid for naive datetimes).  A value drawn from this strategy
will be added to a naive datetime, and the resulting tz-aware datetime
returned.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">tz-aware datetimes from this strategy may be ambiguous or non-existent
due to daylight savings, leap seconds, timezone and calendar
adjustments, etc.  This is intentional, as malformed timestamps are a
common source of bugs.</p>
</div>
<p><code class="xref py py-func docutils literal"><span class="pre">hypothesis.extra.timezones()</span></code> requires the <code class="docutils literal"><span class="pre">pytz</span></code> package, but
provides all timezones in the Olsen database.  If you also want to allow
naive datetimes, combine strategies like <code class="docutils literal"><span class="pre">none()</span> <span class="pre">|</span> <span class="pre">timezones()</span></code>.</p>
<p>Alternatively, you can create a list of the timezones you wish to allow
(e.g. from the standard library, <code class="docutils literal"><span class="pre">datetutil</span></code>, or <code class="docutils literal"><span class="pre">pytz</span></code>) and use
<a class="reference internal" href="#hypothesis.strategies.sampled_from" title="hypothesis.strategies.sampled_from"><code class="xref py py-func docutils literal"><span class="pre">sampled_from()</span></code></a>.  Ensure that simple values such as None or UTC
are at the beginning of the list for proper minimisation.</p>
<p>Examples from this strategy shrink towards midnight on January 1st 2000.</p>
</div></blockquote>
<p>The following arguments have been renamed:</p>
<blockquote>
<div><ul class="simple">
<li>min_datetime has been renamed to min_value</li>
<li>max_datetime has been renamed to max_value</li>
</ul>
</div></blockquote>
<p>Use of the old names has been deprecated and will be removed
in a future version of Hypothesis.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.dates">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">dates</code><span class="sig-paren">(</span><em>min_value=datetime.date(1</em>, <em>1</em>, <em>1)</em>, <em>max_value=datetime.date(9999</em>, <em>12</em>, <em>31)</em>, <em>min_date=None</em>, <em>max_date=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#dates"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.dates" title="Permalink to this definition"></a></dt>
<dd><p>A strategy for dates between <code class="docutils literal"><span class="pre">min_date</span></code> and <code class="docutils literal"><span class="pre">max_date</span></code>.</p>
<blockquote>
<div>Examples from this strategy shrink towards January 1st 2000.</div></blockquote>
<p>The following arguments have been renamed:</p>
<blockquote>
<div><ul class="simple">
<li>min_date has been renamed to min_value</li>
<li>max_date has been renamed to max_value</li>
</ul>
</div></blockquote>
<p>Use of the old names has been deprecated and will be removed
in a future version of Hypothesis.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.times">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">times</code><span class="sig-paren">(</span><em>min_value=datetime.time(0</em>, <em>0)</em>, <em>max_value=datetime.time(23</em>, <em>59</em>, <em>59</em>, <em>999999)</em>, <em>timezones=none()</em>, <em>min_time=None</em>, <em>max_time=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#times"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.times" title="Permalink to this definition"></a></dt>
<dd><p>A strategy for times between <code class="docutils literal"><span class="pre">min_time</span></code> and <code class="docutils literal"><span class="pre">max_time</span></code>.</p>
<blockquote>
<div><p>The <code class="docutils literal"><span class="pre">timezones</span></code> argument is handled as for <a class="reference internal" href="#hypothesis.strategies.datetimes" title="hypothesis.strategies.datetimes"><code class="xref py py-func docutils literal"><span class="pre">datetimes()</span></code></a>.</p>
<p>Examples from this strategy shrink towards midnight, with the timezone
component shrinking as for the strategy that provided it.</p>
</div></blockquote>
<p>The following arguments have been renamed:</p>
<blockquote>
<div><ul class="simple">
<li>min_time has been renamed to min_value</li>
<li>max_time has been renamed to max_value</li>
</ul>
</div></blockquote>
<p>Use of the old names has been deprecated and will be removed
in a future version of Hypothesis.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.timedeltas">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">timedeltas</code><span class="sig-paren">(</span><em>min_value=datetime.timedelta(-999999999)</em>, <em>max_value=datetime.timedelta(999999999</em>, <em>86399</em>, <em>999999)</em>, <em>min_delta=None</em>, <em>max_delta=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#timedeltas"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.timedeltas" title="Permalink to this definition"></a></dt>
<dd><p>A strategy for timedeltas between <code class="docutils literal"><span class="pre">min_value</span></code> and <code class="docutils literal"><span class="pre">max_value</span></code>.</p>
<blockquote>
<div>Examples from this strategy shrink towards zero.</div></blockquote>
<p>The following arguments have been renamed:</p>
<blockquote>
<div><ul class="simple">
<li>min_delta has been renamed to min_value</li>
<li>max_delta has been renamed to max_value</li>
</ul>
</div></blockquote>
<p>Use of the old names has been deprecated and will be removed
in a future version of Hypothesis.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.composite">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">composite</code><span class="sig-paren">(</span><em>f</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#composite"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.composite" title="Permalink to this definition"></a></dt>
<dd><p>Defines a strategy that is built out of potentially arbitrarily many
other strategies.</p>
<p>This is intended to be used as a decorator. See
<a class="reference internal" href="#composite-strategies"><span class="std std-ref">the full documentation for more details</span></a>
about how to use this function.</p>
<p>Examples from this strategy shrink by shrinking the output of each draw
call.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.shared">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">shared</code><span class="sig-paren">(</span><em>base</em>, <em>key=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#shared"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.shared" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy that draws a single shared value per run, drawn from
base. Any two shared instances with the same key will share the same value,
otherwise the identity of this strategy will be used. That is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">integers</span><span class="p">()</span>  <span class="c1"># or any other strategy</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">shared</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">shared</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
</pre></div>
</div>
<p>In the above x and y may draw different (or potentially the same) values.
In the following they will always draw the same:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">shared</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s2">&quot;hi&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">shared</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s2">&quot;hi&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Examples from this strategy shrink as per their base strategy.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.choices">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">choices</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#choices"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.choices" title="Permalink to this definition"></a></dt>
<dd><p>Strategy that generates a function that behaves like random.choice.</p>
<p>Will note choices made for reproducibility.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.15.0: </span>Use <a class="reference internal" href="#hypothesis.strategies.data" title="hypothesis.strategies.data"><code class="xref py py-func docutils literal"><span class="pre">data()</span></code></a> with
<a class="reference internal" href="#hypothesis.strategies.sampled_from" title="hypothesis.strategies.sampled_from"><code class="xref py py-func docutils literal"><span class="pre">sampled_from()</span></code></a> instead.</p>
</div>
<p>Examples from this strategy shrink by making each choice function return
an earlier value in the sequence passed to it.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.uuids">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">uuids</code><span class="sig-paren">(</span><em>version=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#uuids"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.uuids" title="Permalink to this definition"></a></dt>
<dd><p>Returns a strategy that generates <code class="xref py py-class docutils literal"><span class="pre">UUIDs</span></code>.</p>
<p>If the optional version argument is given, value is passed through
to <code class="xref py py-class docutils literal"><span class="pre">UUID</span></code> and only UUIDs of that version will
be generated.</p>
<p>All returned values from this will be unique, so e.g. if you do
<code class="docutils literal"><span class="pre">lists(uuids())</span></code> the resulting list will never contain duplicates.</p>
<p>Examples from this strategy don’t have any meaningful shrink order.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.runner">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">runner</code><span class="sig-paren">(</span><em>default=not_set</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#runner"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.runner" title="Permalink to this definition"></a></dt>
<dd><p>A strategy for getting “the current test runner”, whatever that may be.
The exact meaning depends on the entry point, but it will usually be the
associated ‘self’ value for it.</p>
<p>If there is no current test runner and a default is provided, return
that default. If no default is provided, raises InvalidArgument.</p>
<p>Examples from this strategy do not shrink (because there is only one).</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.data">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">data</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#data"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.data" title="Permalink to this definition"></a></dt>
<dd><p>This isn’t really a normal strategy, but instead gives you an object
which can be used to draw data interactively from other strategies.</p>
<p>It can only be used within <a class="reference internal" href="details.html#hypothesis.given" title="hypothesis.given"><code class="xref py py-func docutils literal"><span class="pre">&#64;given</span></code></a>, not
<a class="reference internal" href="details.html#hypothesis.find" title="hypothesis.find"><code class="xref py py-func docutils literal"><span class="pre">find()</span></code></a>. This is because the lifetime
of the object cannot outlast the test body.</p>
<p>See <a class="reference internal" href="#interactive-draw"><span class="std std-ref">the rest of the documentation</span></a> for more
complete information.</p>
<p>Examples from this strategy do not shrink (because there is only one),
but the result of calls to each draw() call shrink as they normally would.</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.register_type_strategy">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">register_type_strategy</code><span class="sig-paren">(</span><em>custom_type</em>, <em>strategy</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#register_type_strategy"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.register_type_strategy" title="Permalink to this definition"></a></dt>
<dd><p>Add an entry to the global type-to-strategy lookup.</p>
<p>This lookup is used in <a class="reference internal" href="#hypothesis.strategies.builds" title="hypothesis.strategies.builds"><code class="xref py py-func docutils literal"><span class="pre">builds()</span></code></a> and
<a class="reference internal" href="details.html#hypothesis.given" title="hypothesis.given"><code class="xref py py-func docutils literal"><span class="pre">&#64;given</span></code></a>.</p>
<p><a class="reference internal" href="#hypothesis.strategies.builds" title="hypothesis.strategies.builds"><code class="xref py py-func docutils literal"><span class="pre">builds()</span></code></a> will be used automatically for
classes with type annotations on <code class="docutils literal"><span class="pre">__init__</span></code> , so you only need to
register a strategy if one or more arguments need to be more tightly
defined than their type-based default, or if you want to supply a strategy
for an argument with a default value.</p>
<p><code class="docutils literal"><span class="pre">strategy</span></code> may be a search strategy, or a function that takes a type and
returns a strategy (useful for generic types).</p>
</dd></dl>

<dl class="function">
<dt id="hypothesis.strategies.deferred">
<code class="descclassname">hypothesis.strategies.</code><code class="descname">deferred</code><span class="sig-paren">(</span><em>definition</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/hypothesis/strategies.html#deferred"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#hypothesis.strategies.deferred" title="Permalink to this definition"></a></dt>
<dd><p>A deferred strategy allows you to write a strategy that references other
strategies that have not yet been defined. This allows for the easy
definition of recursive and mutually recursive strategies.</p>
<p>The definition argument should be a zero-argument function that returns a
strategy. It will be evaluated the first time the strategy is used to
produce an example.</p>
<p>Example usage:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">hypothesis.strategies</span> <span class="k">as</span> <span class="nn">st</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">st</span><span class="o">.</span><span class="n">deferred</span><span class="p">(</span><span class="k">lambda</span><span class="p">:</span> <span class="n">st</span><span class="o">.</span><span class="n">booleans</span><span class="p">()</span> <span class="o">|</span> <span class="n">st</span><span class="o">.</span><span class="n">tuples</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">x</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">(((False, (True, True)), (False, True)), (True, True))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">(True, True)</span>
</pre></div>
</div>
<p>Mutual recursion also works fine:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">st</span><span class="o">.</span><span class="n">deferred</span><span class="p">(</span><span class="k">lambda</span><span class="p">:</span> <span class="n">st</span><span class="o">.</span><span class="n">booleans</span><span class="p">()</span> <span class="o">|</span> <span class="n">b</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">st</span><span class="o">.</span><span class="n">deferred</span><span class="p">(</span><span class="k">lambda</span><span class="p">:</span> <span class="n">st</span><span class="o">.</span><span class="n">tuples</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">a</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">(True, (True, False))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">(False, True)</span>
</pre></div>
</div>
<p>Examples from this strategy shrink as they normally would from the strategy
returned by the definition.</p>
</dd></dl>

<div class="section" id="shrinking">
<span id="id1"></span><h2>Shrinking<a class="headerlink" href="#shrinking" title="Permalink to this headline"></a></h2>
<p>When using strategies it is worth thinking about how the data <em>shrinks</em>.
Shrinking is the process by which Hypothesis tries to produce human readable
examples when it finds a failure - it takes a complex example and turns it
into a simpler one.</p>
<p>Each strategy defines an order in which it shrinks - you won’t usually need to
care about this much, but it can be worth being aware of as it can affect what
the best way to write your own strategies is.</p>
<p>The exact shrinking behaviour is not a guaranteed part of the API, but it
doesn’t change that often and when it does it’s usually because we think the
new way produces nicer examples.</p>
<p>Possibly the most important one to be aware of is
<a class="reference internal" href="#hypothesis.strategies.one_of" title="hypothesis.strategies.one_of"><code class="xref py py-func docutils literal"><span class="pre">one_of()</span></code></a>, which has a preference for values
produced by strategies earlier in its argument list. Most of the others should
largely “do the right thing” without you having to think about it.</p>
</div>
<div class="section" id="adapting-strategies">
<h2>Adapting strategies<a class="headerlink" href="#adapting-strategies" title="Permalink to this headline"></a></h2>
<p>Often it is the case that a strategy doesn’t produce exactly what you want it
to and you need to adapt it. Sometimes you can do this in the test, but this
hurts reuse because you then have to repeat the adaption in every test.</p>
<p>Hypothesis gives you ways to build strategies from other strategies given
functions for transforming the data.</p>
<div class="section" id="mapping">
<h3>Mapping<a class="headerlink" href="#mapping" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal"><span class="pre">map</span></code> is probably the easiest and most useful of these to use. If you have a
strategy <code class="docutils literal"><span class="pre">s</span></code> and a function <code class="docutils literal"><span class="pre">f</span></code>, then an example <code class="docutils literal"><span class="pre">s.map(f).example()</span></code> is
<code class="docutils literal"><span class="pre">f(s.example())</span></code>, i.e. we draw an example from <code class="docutils literal"><span class="pre">s</span></code> and then apply <code class="docutils literal"><span class="pre">f</span></code> to it.</p>
<p>e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">lists</span><span class="p">(</span><span class="n">integers</span><span class="p">())</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="nb">sorted</span><span class="p">)</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">[-158104205405429173199472404790070005365, -131418136966037518992825706738877085689, -49279168042092131242764306881569217089, 2564476464308589627769617001898573635]</span>
</pre></div>
</div>
<p>Note that many things that you might use mapping for can also be done with
<a class="reference internal" href="#hypothesis.strategies.builds" title="hypothesis.strategies.builds"><code class="xref py py-func docutils literal"><span class="pre">builds()</span></code></a>.</p>
</div>
<div class="section" id="filtering">
<span id="id2"></span><h3>Filtering<a class="headerlink" href="#filtering" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal"><span class="pre">filter</span></code> lets you reject some examples. <code class="docutils literal"><span class="pre">s.filter(f).example()</span></code> is some
example of <code class="docutils literal"><span class="pre">s</span></code> such that <code class="docutils literal"><span class="pre">f(example)</span></code> is truthy.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">integers</span><span class="p">()</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span> <span class="o">&gt;</span> <span class="mi">11</span><span class="p">)</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">87034457550488036879331335314643907276</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">integers</span><span class="p">()</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span> <span class="o">&gt;</span> <span class="mi">11</span><span class="p">)</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">145321388071838806577381808280858991039</span>
</pre></div>
</div>
<p>It’s important to note that <code class="docutils literal"><span class="pre">filter</span></code> isn’t magic and if your condition is too
hard to satisfy then this can fail:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">integers</span><span class="p">()</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="kc">False</span><span class="p">)</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
    <span class="o">...</span>
<span class="gr">hypothesis.errors.NoExamples</span>: <span class="n">Could not find any valid examples in 20 tries</span>
</pre></div>
</div>
<p>In general you should try to use <code class="docutils literal"><span class="pre">filter</span></code> only to avoid corner cases that you
don’t want rather than attempting to cut out a large chunk of the search space.</p>
<p>A technique that often works well here is to use map to first transform the data
and then use <code class="docutils literal"><span class="pre">filter</span></code> to remove things that didn’t work out. So for example if
you wanted pairs of integers (x,y) such that x &lt; y you could do the following:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">tuples</span><span class="p">(</span><span class="n">integers</span><span class="p">(),</span> <span class="n">integers</span><span class="p">())</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="nb">sorted</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">&lt;</span> <span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">[-145066798798423346485767563193971626126, -19139012562996970506504843426153630262]</span>
</pre></div>
</div>
</div>
<div class="section" id="chaining-strategies-together">
<span id="flatmap"></span><h3>Chaining strategies together<a class="headerlink" href="#chaining-strategies-together" title="Permalink to this headline"></a></h3>
<p>Finally there is <code class="docutils literal"><span class="pre">flatmap</span></code>. <code class="docutils literal"><span class="pre">flatmap</span></code> draws an example, then turns that
example into a strategy, then draws an example from <em>that</em> strategy.</p>
<p>It may not be obvious why you want this at first, but it turns out to be
quite useful because it lets you generate different types of data with
relationships to each other.</p>
<p>For example suppose we wanted to generate a list of lists of the same
length:</p>
<div class="highlight-pycon"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">rectangle_lists</span> <span class="o">=</span> <span class="n">integers</span><span class="p">(</span><span class="n">min_value</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">max_value</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span><span class="o">.</span><span class="n">flatmap</span><span class="p">(</span>
<span class="gp">... </span><span class="k">lambda</span> <span class="n">n</span><span class="p">:</span> <span class="n">lists</span><span class="p">(</span><span class="n">lists</span><span class="p">(</span><span class="n">integers</span><span class="p">(),</span> <span class="n">min_size</span><span class="o">=</span><span class="n">n</span><span class="p">,</span> <span class="n">max_size</span><span class="o">=</span><span class="n">n</span><span class="p">)))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">find</span><span class="p">(</span><span class="n">rectangle_lists</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="bp">True</span><span class="p">)</span>
<span class="go">[]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">find</span><span class="p">(</span><span class="n">rectangle_lists</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">10</span><span class="p">)</span>
<span class="go">[[], [], [], [], [], [], [], [], [], []]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">find</span><span class="p">(</span><span class="n">rectangle_lists</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">t</span><span class="p">:</span> <span class="nb">len</span><span class="p">(</span><span class="n">t</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">3</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">t</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span> <span class="o">&gt;=</span> <span class="mi">3</span><span class="p">)</span>
<span class="go">[[0, 0, 0], [0, 0, 0], [0, 0, 0]]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">find</span><span class="p">(</span><span class="n">rectangle_lists</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">t</span><span class="p">:</span> <span class="nb">sum</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">t</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="mi">10</span><span class="p">)</span>
<span class="go">[[0], [0], [0], [0], [0], [0], [0], [0], [0], [0]]</span>
</pre></div>
</div>
<p>In this example we first choose a length for our tuples, then we build a
strategy which generates lists containing lists precisely of that length. The
finds show what simple examples for this look like.</p>
<p>Most of the time you probably don’t want <code class="docutils literal"><span class="pre">flatmap</span></code>, but unlike <code class="docutils literal"><span class="pre">filter</span></code> and
<code class="docutils literal"><span class="pre">map</span></code> which are just conveniences for things you could just do in your tests,
<code class="docutils literal"><span class="pre">flatmap</span></code> allows genuinely new data generation that you wouldn’t otherwise be
able to easily do.</p>
<p>(If you know Haskell: Yes, this is more or less a monadic bind. If you don’t
know Haskell, ignore everything in these parentheses. You do not need to
understand anything about monads to use this, or anything else in Hypothesis).</p>
</div>
<div class="section" id="recursive-data">
<h3>Recursive data<a class="headerlink" href="#recursive-data" title="Permalink to this headline"></a></h3>
<p>Sometimes the data you want to generate has a recursive definition. e.g. if you
wanted to generate JSON data, valid JSON is:</p>
<ol class="arabic simple">
<li>Any float, any boolean, any unicode string.</li>
<li>Any list of valid JSON data</li>
<li>Any dictionary mapping unicode strings to valid JSON data.</li>
</ol>
<p>The problem is that you cannot call a strategy recursively and expect it to not just
blow up and eat all your memory.  The other problem here is that not all unicode strings
display consistently on different machines, so we’ll restrict them in our doctest.</p>
<p>The way Hypothesis handles this is with the <a class="reference internal" href="#hypothesis.strategies.recursive" title="hypothesis.strategies.recursive"><code class="xref py py-func docutils literal"><span class="pre">recursive()</span></code></a> function
which you pass in a base case and a function that, given a strategy for your data type,
returns a new strategy for it. So for example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">string</span> <span class="k">import</span> <span class="n">printable</span><span class="p">;</span> <span class="kn">from</span> <span class="nn">pprint</span> <span class="k">import</span> <span class="n">pprint</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">json</span> <span class="o">=</span> <span class="n">recursive</span><span class="p">(</span><span class="n">none</span><span class="p">()</span> <span class="o">|</span> <span class="n">booleans</span><span class="p">()</span> <span class="o">|</span> <span class="n">floats</span><span class="p">()</span> <span class="o">|</span> <span class="n">text</span><span class="p">(</span><span class="n">printable</span><span class="p">),</span>
<span class="gp">... </span><span class="k">lambda</span> <span class="n">children</span><span class="p">:</span> <span class="n">lists</span><span class="p">(</span><span class="n">children</span><span class="p">)</span> <span class="o">|</span> <span class="n">dictionaries</span><span class="p">(</span><span class="n">text</span><span class="p">(</span><span class="n">printable</span><span class="p">),</span> <span class="n">children</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pprint</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">example</span><span class="p">())</span>
<span class="go">{&#39;&#39;: &#39;wkP!4&#39;,</span>
<span class="go"> &#39;\nLdy&#39;: None,</span>
<span class="go"> &#39;&quot;uHuds:8a{h\\:694K~{mY&gt;a1yA:#CmDYb&#39;: {},</span>
<span class="go"> &#39;#1J1&#39;: [&#39;)gnP&#39;,</span>
<span class="go">          inf,</span>
<span class="go">          [&#39;6&#39;, 11881275561.716116, &quot;v&#39;A?qyp_sB\n$62g&quot;, &#39;&#39;],</span>
<span class="go">          -1e-05,</span>
<span class="go">          &#39;aF\rl&#39;,</span>
<span class="go">          [-2.599459969184803e+250, True, True, None],</span>
<span class="go">          [True,</span>
<span class="go">           &#39;9qP\x0bnUJH5&#39;,</span>
<span class="go">           3.0741121405774857e-131,</span>
<span class="go">           None,</span>
<span class="go">           &#39;&#39;,</span>
<span class="go">           -inf,</span>
<span class="go">           &#39;L&amp;&#39;,</span>
<span class="go">           1.5,</span>
<span class="go">           False,</span>
<span class="go">           None]],</span>
<span class="go"> &#39;cx.&#39;: None}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pprint</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">example</span><span class="p">())</span>
<span class="go">[5.321430774293539e+16, [], 1.1045114769709281e-125]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pprint</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">example</span><span class="p">())</span>
<span class="go">{&#39;a&#39;: []}</span>
</pre></div>
</div>
<p>That is, we start with our leaf data and then we augment it by allowing lists and dictionaries of anything we can generate as JSON data.</p>
<p>The size control of this works by limiting the maximum number of values that can be drawn from the base strategy. So for example if
we wanted to only generate really small JSON we could do this as:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">small_lists</span> <span class="o">=</span> <span class="n">recursive</span><span class="p">(</span><span class="n">booleans</span><span class="p">(),</span> <span class="n">lists</span><span class="p">,</span> <span class="n">max_leaves</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">small_lists</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">small_lists</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">[False, False, True, True, True]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">small_lists</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">True</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="composite-strategies">
<span id="id3"></span><h2>Composite strategies<a class="headerlink" href="#composite-strategies" title="Permalink to this headline"></a></h2>
<p>The <a class="reference internal" href="#hypothesis.strategies.composite" title="hypothesis.strategies.composite"><code class="xref py py-func docutils literal"><span class="pre">&#64;composite</span></code></a> decorator lets you combine other strategies in more or less
arbitrary ways. It’s probably the main thing you’ll want to use for
complicated custom strategies.</p>
<p>The composite decorator works by giving you a function as the first argument
that you can use to draw examples from other strategies. For example, the
following gives you a list and an index into it:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@composite</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">list_and_index</span><span class="p">(</span><span class="n">draw</span><span class="p">,</span> <span class="n">elements</span><span class="o">=</span><span class="n">integers</span><span class="p">()):</span>
<span class="gp">... </span>    <span class="n">xs</span> <span class="o">=</span> <span class="n">draw</span><span class="p">(</span><span class="n">lists</span><span class="p">(</span><span class="n">elements</span><span class="p">,</span> <span class="n">min_size</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>
<span class="gp">... </span>    <span class="n">i</span> <span class="o">=</span> <span class="n">draw</span><span class="p">(</span><span class="n">integers</span><span class="p">(</span><span class="n">min_value</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">max_value</span><span class="o">=</span><span class="nb">len</span><span class="p">(</span><span class="n">xs</span><span class="p">)</span> <span class="o">-</span> <span class="mi">1</span><span class="p">))</span>
<span class="gp">... </span>    <span class="k">return</span> <span class="p">(</span><span class="n">xs</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">draw(s)</span></code> is a function that should be thought of as returning <code class="docutils literal"><span class="pre">s.example()</span></code>,
except that the result is reproducible and will minimize correctly. The
decorated function has the initial argument removed from the list, but will
accept all the others in the expected order. Defaults are preserved.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">list_and_index</span><span class="p">()</span>
<span class="go">list_and_index()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">list_and_index</span><span class="p">()</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">([-57328788235238539257894870261848707608], 0)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">list_and_index</span><span class="p">(</span><span class="n">booleans</span><span class="p">())</span>
<span class="go">list_and_index(elements=booleans())</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">list_and_index</span><span class="p">(</span><span class="n">booleans</span><span class="p">())</span><span class="o">.</span><span class="n">example</span><span class="p">()</span>
<span class="go">([True], 0)</span>
</pre></div>
</div>
<p>Note that the repr will work exactly like it does for all the built-in
strategies: it will be a function that you can call to get the strategy in
question, with values provided only if they do not match the defaults.</p>
<p>You can use <a class="reference internal" href="details.html#hypothesis.assume" title="hypothesis.assume"><code class="xref py py-func docutils literal"><span class="pre">assume</span></code></a> inside composite functions:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="nd">@composite</span>
<span class="k">def</span> <span class="nf">distinct_strings_with_common_characters</span><span class="p">(</span><span class="n">draw</span><span class="p">):</span>
    <span class="n">x</span> <span class="o">=</span> <span class="n">draw</span><span class="p">(</span><span class="n">text</span><span class="p">(),</span> <span class="n">min_size</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
    <span class="n">y</span> <span class="o">=</span> <span class="n">draw</span><span class="p">(</span><span class="n">text</span><span class="p">(</span><span class="n">alphabet</span><span class="o">=</span><span class="n">x</span><span class="p">))</span>
    <span class="n">assume</span><span class="p">(</span><span class="n">x</span> <span class="o">!=</span> <span class="n">y</span><span class="p">)</span>
    <span class="k">return</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
</pre></div>
</div>
<p>This works as <a class="reference internal" href="details.html#hypothesis.assume" title="hypothesis.assume"><code class="xref py py-func docutils literal"><span class="pre">assume</span></code></a> normally would, filtering out any examples for which the
passed in argument is falsey.</p>
</div>
<div class="section" id="drawing-interactively-in-tests">
<span id="interactive-draw"></span><h2>Drawing interactively in tests<a class="headerlink" href="#drawing-interactively-in-tests" title="Permalink to this headline"></a></h2>
<p>There is also the <a class="reference internal" href="#hypothesis.strategies.data" title="hypothesis.strategies.data"><code class="xref py py-func docutils literal"><span class="pre">data()</span></code></a> strategy, which gives you a means of using
strategies interactively. Rather than having to specify everything up front in
<a class="reference internal" href="details.html#hypothesis.given" title="hypothesis.given"><code class="xref py py-func docutils literal"><span class="pre">&#64;given</span></code></a> you can draw from strategies in the body of your test:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="nd">@given</span><span class="p">(</span><span class="n">data</span><span class="p">())</span>
<span class="k">def</span> <span class="nf">test_draw_sequentially</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
    <span class="n">x</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">draw</span><span class="p">(</span><span class="n">integers</span><span class="p">())</span>
    <span class="n">y</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">draw</span><span class="p">(</span><span class="n">integers</span><span class="p">(</span><span class="n">min_value</span><span class="o">=</span><span class="n">x</span><span class="p">))</span>
    <span class="k">assert</span> <span class="n">x</span> <span class="o">&lt;</span> <span class="n">y</span>
</pre></div>
</div>
<p>If the test fails, each draw will be printed with the falsifying example. e.g.
the above is wrong (it has a boundary condition error), so will print:</p>
<div class="highlight-pycon"><div class="highlight"><pre><span></span><span class="go">Falsifying example: test_draw_sequentially(data=data(...))</span>
<span class="go">Draw 1: 0</span>
<span class="go">Draw 2: 0</span>
</pre></div>
</div>
<p>As you can see, data drawn this way is simplified as usual.</p>
<p>Test functions using the <a class="reference internal" href="#hypothesis.strategies.data" title="hypothesis.strategies.data"><code class="xref py py-func docutils literal"><span class="pre">data()</span></code></a> strategy do not support explicit
<a class="reference internal" href="reproducing.html#hypothesis.example" title="hypothesis.example"><code class="xref py py-func docutils literal"><span class="pre">&#64;example(...)</span></code></a>s.  In this case, the best option is usually to construct
your data with <a class="reference internal" href="#hypothesis.strategies.composite" title="hypothesis.strategies.composite"><code class="xref py py-func docutils literal"><span class="pre">&#64;composite</span></code></a> or the explicit example, and unpack this within
the body of the test.</p>
<p>Optionally, you can provide a label to identify values generated by each call
to <code class="docutils literal"><span class="pre">data.draw()</span></code>.  These labels can be used to identify values in the output
of a falsifying example.</p>
<p>For instance:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="nd">@given</span><span class="p">(</span><span class="n">data</span><span class="p">())</span>
<span class="k">def</span> <span class="nf">test_draw_sequentially</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
    <span class="n">x</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">draw</span><span class="p">(</span><span class="n">integers</span><span class="p">(),</span> <span class="n">label</span><span class="o">=</span><span class="s1">&#39;First number&#39;</span><span class="p">)</span>
    <span class="n">y</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">draw</span><span class="p">(</span><span class="n">integers</span><span class="p">(</span><span class="n">min_value</span><span class="o">=</span><span class="n">x</span><span class="p">),</span> <span class="n">label</span><span class="o">=</span><span class="s1">&#39;Second number&#39;</span><span class="p">)</span>
    <span class="k">assert</span> <span class="n">x</span> <span class="o">&lt;</span> <span class="n">y</span>
</pre></div>
</div>
<p>will produce the output:</p>
<div class="highlight-pycon"><div class="highlight"><pre><span></span><span class="go">Falsifying example: test_draw_sequentially(data=data(...))</span>
<span class="go">Draw 1 (First number): 0</span>
<span class="go">Draw 2 (Second number): 0</span>
</pre></div>
</div>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="extras.html" class="btn btn-neutral float-right" title="Additional packages" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="settings.html" class="btn btn-neutral" title="Settings" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2013-2018, David R. MacIver.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'3.44.1',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: '.txt'
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>