Add powers of two to integer constants

brand/README.md

@@ -0,0 +1,34 @@
+# Logos and other pretty things
+
+Hypothesis has a beautiful logo, thanks to the generous work of Libby Berrie in [issue #1519](https://github.com/HypothesisWorks/hypothesis/issues/1519).  The [CogWorks class of 2019](https://github.com/CogWorksBWSI) named the dragonfly "Scout", as a job description and after *To Kill a Mockingbird*.
+
+General guidelines:
+
+- Prefer vector (`.svg`) formats to raster formats (`.png`) wherever possible.  However, some viewers don't handle the layers well - e.g. the left eye might be drawn in front of the head - in which case you might prefer `.png`.
+- We consider the rainbow version to be canonical.  The blue variant is provided for cases such as monochrome versions or printing with a limited palette.
+
+With that in mind, you are welcome to use these logos to refer to Hypothesis - and if you're not sure whether a specific use is OK, please get in touch and ask!
+
+For example, we often bring Hypothesis stickers to conferences but can't make it to everything.  If you want to print your own Hypothesis stickers, upload `sticker.png` to [StickerMule](https://www.stickermule.com/custom-stickers) and pick one of the die-cut vinyl options - that's how we get ours!
+
+![Hypothesis stickers suitable for your laptop](./stickers.jpg)
+
+## Colour palette in GIMP format
+
+A [colour palette in GIMP format](hypothesis.gpl) (`.gpl`) is also provided with the intent of making it easier to produce graphics and documents which reuse the colours in the Hypothesis Dragonfly logo by Libby Berrie.
+
+The `hypothesis.gpl` file should be copied or imported to the appropriate location on your filesystem. For example:
+
+- `/usr/share/inkscape/palettes/` for Inkscape on Ubuntu 18.08
+- Edit -> Colors -> Import... then select the `hypothesis.gpl` file in Scribus on Ubuntu 18.08
+- Windows -> Dockable Dialogs -> Palettes -> Palettes Menu -> Add Palette -> Import from file... then select the `hypothesis.gpl` file in GIMP on Ubuntu 18.08
+
+Once imported, the colour palette is then available for easy manipulation of colours within the user interface.
+
+Inkscape:
+
+![Inkscape showing Hypothesis colour palette](inkscape.png)
+
+GIMP:
+
+![GIMP showing Hypothesis colour palette](gimp.png)

guides/README.md

@@ -0,0 +1,5 @@
+# Guides for Hypothesis Development
+
+This is a general collection of useful documentation for people working on Hypothesis.
+
+It is separate from the main documentation because it is not much use if you are merely *using* Hypothesis. It's purely for working on it, and aimed more at maintainers than casual contributors.

hypothesis-python/RELEASE.rst

@@ -0,0 +1,3 @@
+RELEASE_TYPE: patch
+
+Hypothesis now generates powers of 2 more often when using |st.integers|.

hypothesis-python/docs/reference/strategies.rst

@@ -33,7 +33,7 @@ Numeric
 Strings
 -------
 
-.. seealso::
+.. note::
 
   The |st.uuids| and |st.ip_addresses| strategies generate instances of :mod:`UUID <python:uuid>` and :mod:`IPAddress <python:ipaddress>` respectively. You can generate corresponding string values by using |.map|, such as ``st.uuids().map(str)``.
 

hypothesis-python/examples/README.md

@@ -0,0 +1,5 @@
+# Examples of Hypothesis usage
+
+This is a directory for examples of using Hypothesis that show case its features or demonstrate a useful way of testing something.
+
+Right now it's a bit small and fairly algorithmically focused. Pull requests to add more examples would be *greatly* appreciated, especially ones using e.g. the Django integration or testing something "Businessy".

hypothesis-python/src/hypothesis/core.py

@@ -151,7 +151,7 @@
 running_under_pytest = False
 pytest_shows_exceptiongroups = True
 global_force_seed = None
-# `threadlocal` stores "engine-global" constants, which are global relative to a
+# this variable stores "engine-global" constants, which are global relative to a
 # ConjectureRunner instance (roughly speaking). Since only one conjecture runner
 # instance can be active per thread, making engine constants thread-local prevents
 # the ConjectureRunner instances of concurrent threads from treading on each other.

hypothesis-python/src/hypothesis/internal/conjecture/providers.py

@@ -126,6 +126,30 @@
 CacheValueT: TypeAlias = tuple[tuple["ConstantT", ...], tuple["ConstantT", ...]]
 CONSTANTS_CACHE: LRUCache[CacheKeyT, CacheValueT] = LRUCache(1024)
 
+
+_constants_integers = (
+    # powers of 2
+    [2**n for n in range(16, 66)]
+    # powers of 10
+    + [10**n for n in range(5, 20)]
+    # factorials
+    + [math.factorial(n) for n in range(9, 21)]
+    # a few primorial numbers https://en.wikipedia.org/wiki/Primorial
+    + [
+        510510,
+        6469693230,
+        304250263527210,
+        32589158477190044730,
+    ]
+)
+_constants_integers.extend(
+    [n - 1 for n in _constants_integers] + [n + 1 for n in _constants_integers]
+)
+_constants_integers.extend([-x for x in _constants_integers])
+
+# arbitrary cutoffs to keep our list bounded
+assert all(50_000 <= abs(n) <= 2**66 for n in _constants_integers)
+
 _constant_floats = (
     [
         0.5,
@@ -193,14 +217,14 @@
     "Ⱥ",
     "Ⱦ",
     # ligatures
-    "æœÆŒffʤʨß"
+    "æœÆŒffʤʨß",
     # emoticons
     "(╯°□°）╯︵ ┻━┻)",
     # emojis
     "😍",
     "🇺🇸",
     # emoji modifiers
-    "🏻"  # U+1F3FB Light Skin Tone,
+    "🏻",  # U+1F3FB Light Skin Tone,
     "👍🏻",  # 👍 followed by U+1F3FB
     # RTL text
     "الكل في المجمو عة",
@@ -234,7 +258,7 @@
 # we don't actually care what order the constants are sorted in, just that the
 # ordering is deterministic.
 GLOBAL_CONSTANTS = Constants(
-    integers=SortedSet(),
+    integers=SortedSet(_constants_integers),
     floats=SortedSet(_constant_floats, key=float_to_int),
     bytes=SortedSet(),
     strings=SortedSet(_constant_strings),

hypothesis-python/src/hypothesis/vendor/pretty.py

@@ -424,7 +424,7 @@ def maybe_repr_known_object_as_call(
             return self.text("<...>")
         # Look up comments from slice_comments if we have arg_labels
         comments = {}
-        if arg_labels:
+        if arg_labels is not None:
             for key, sr in arg_labels.items():
                 if sr in self.slice_comments:
                     comments[key] = self.slice_comments[sr]

hypothesis-python/tests/README.md

@@ -0,0 +1,60 @@
+# Don't Panic
+
+The Hypothesis test suite is large, but we've written these notes to help you out.  It's aimed at contributors (new and old!) who know they need to add tests *somewhere*, but aren't sure where - or maybe need some hints on what kinds of tests might be useful.  Others might just be interested in how a testing library tests itself!
+
+## The very short version
+
+- To improve code coverage (eg because `./build.sh check-coverage` or CI is failing), go to `cover/`
+- For longer / system / integration tests, look in `nocover/`
+- For tests that require an optional dependency, look in the directory named for that dependency.
+
+> [!NOTE]
+> If you get stuck, just ask a maintainer to help out by mentioning them on GitHub. We'd love to help - and also get feedback on how this document could be better!
+
+## Some scenarios
+
+#### I'm adding or changing a strategy
+
+Check for a file specific to that strategy (eg `test_uuids.py` for the `uuids()` strategy).  Write tests for all invalid argument handling in `test_direct_strategies.py`.  Strategies with optional dependencies should go in `hypothesis.extras`, and the tests in their own module (ie not in `cover`).  When you think you might be done, push and let our CI system point out any failing tests or non-covered code!
+
+#### I've made some internal changes
+
+That's not very specific - you should probably refer to the test-finding tips in the next section.  Remember that `tests/cover` is reasonably quick unit-test style tests - you should consider writing more intensive integration tests too, but put them in `tests/nocover` with the others.
+
+## Finding particular tests
+
+With the sheer size and variety in this directory finding a specific thing can be tricky.  Tips:
+
+- Check for filenames that are relevant to your contribution.
+- Use `git grep` to search for keywords, e.g. the name of a strategy you've changed.
+- Deliberately break something related to your code, and see which tests fail.
+- Ask a maintainer!  Sometimes the structure is just arbitrary, and other tactics don't work - but we *want* to help!
+
+## About each group of tests
+
+Still here?  Here's a note on what to expect in each directory.
+
+* `common/`
+  * Useful shared testing code, including test setup and a few helper functions in `utils.py`.  Also read up on [pytest](https://docs.pytest.org/en/latest/contents.html>) features such as `mark.parametrize`, `mark.skipif`, and `raises` for other functions that are often useful when writing tests.
+* `conjecture/`
+   * As for `cover/`, but specific to `hypothesis.internal.conjecture`.
+* `cover/`
+  * The home of enough tests to get 100% branch coverage, as quickly as possible without compromising on test power.  This can be an intimidating target, but it's entirely achievable and the maintainers are (still) here to help.
+  * This directory alone has around two-thirds of the tests for Hypothesis (~8k of ~12k lines of code).  If you're adding or fixing tests, chances are therefore good that they're in here!
+* `datetime/`
+  * Tests which depend on the `pytz` or `dateutil` packages for timezones.
+* `django/`
+  * Tests for the Django extra.  Includes a toy application, to give us lots of models to generate.
+* `lark/`
+  * Tests for the Lark extra for context-free grammars, which depend on the `lark` package.
+* `nocover/`
+  * More expensive and longer-running tests, typically used to test trickier interactions or check for regressions in expensive bugs.  Lots of tests about how values shrink, databases, compatibility, etc.
+  * New tests that are not required for full coverage of code branches or behaviour should also go in `nocover`, to keep `cover` reasonably fast.
+* `numpy/`
+  * Tests for the Numpy extra.
+* `pandas/`
+  * Tests for the Pandas extra.
+* `pytest/`
+  * Hypothesis has excellent integration with `pytest`, though we are careful to support other test runners such as unittest.  This is where we test that our pytest integration is working properly.
+* `quality/`
+  * Tests that various hard-to-find examples do in fact get found by Hypothesis, as well as some stuff about example shrinking.  Mostly intended for tests of the form "Hypothesis finds an example of this condition" + assertions about which example it finds.