# hypothesmith
Hypothesis strategies for generating Python programs, something like CSmith.
This is definitely pre-alpha, but if you want to play with it feel free!
You can even keep the shiny pieces when - not if - it breaks.
Get it today with [`pip install hypothesmith`](https://pypi.org/project/hypothesmith/),
or by cloning [the GitHub repo](https://github.com/Zac-HD/hypothesmith).
You can run the tests, such as they are, with `tox` on Python 3.6 or later.
Use `tox -va` to see what environments are available.
## Usage
This package provides two Hypothesis strategies for generating Python source code.
The generated code will always be syntatically valid, and is useful for testing
parsers, linters, auto-formatters, and other tools that operate on source code.
> DO NOT EXECUTE CODE GENERATED BY THESE STRATEGIES.
>
> It could do literally anything that running Python code is able to do,
> including changing, deleting, or uploading important data. Arbitrary
> code can be useful, but "arbitrary code execution" can be very, very bad.
#### `hypothesmith.from_grammar(start="file_input", *, auto_target=True)`
Generates syntactically-valid Python source code based on the grammar.
Valid values for ``start`` are ``"single_input"``, ``"file_input"``, or
``"eval_input"``; respectively a single interactive statement, a module or
sequence of commands read from a file, and input for the eval() function.
If ``auto_target`` is ``True``, this strategy uses ``hypothesis.target()``
internally to drive towards larger and more complex examples. We recommend
leaving this enabled, as the grammar is quite complex and only simple examples
tend to be generated otherwise.
#### `hypothesmith.from_node(node=libcst.Module, *, auto_target=True)`
Generates syntactically-valid Python source code based on the node types
defined by the [`LibCST`](https://libcst.readthedocs.io/en/latest/) project.
You can pass any subtype of `libcst.CSTNode`. Alternatively, you can use
Hypothesis' built-in `from_type(node_type).map(lambda n: libcst.Module([n]).code`,
after Hypothesmith has registered the required strategies. However, this does
not include automatic targeting and limitations of LibCST may lead to invalid
code being generated.
## Notable bugs found with Hypothesmith
- [BPO-40661, a segfault in the new parser](https://bugs.python.org/issue40661),
was given maximum priority and blocked the planned release of CPython 3.9 beta1.
- [BPO-38953](https://bugs.python.org/issue38953) `tokenize` -> `untokenize` roundtrip bugs.
- [BPO-42218](https://bugs.python.org/issue42218) mishandled error case in new PEG parser.
- [`lib2to3` errors on \r in comment](https://github.com/psf/black/issues/970)
- [Black fails on files ending in a backslash](https://github.com/psf/black/issues/1012)
- [At least three round-trip bugs in LibCST](https://github.com/Instagram/LibCST#acknowledgements)
([search commits for "hypothesis"](https://github.com/Instagram/LibCST/search?q=Fix+hypothesis&type=commits))
- [Invalid code generated by LibCST](https://github.com/Instagram/LibCST/issues/287)
### Changelog
Patch notes [can be found in `CHANGELOG.md`](https://github.com/Zac-HD/hypothesmith/blob/master/CHANGELOG.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/Zac-HD/hypothesmith",
"name": "hypothesmith",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "python testing fuzzing property-based-testing",
"author": "Zac Hatfield-Dodds",
"author_email": "zac@hypothesis.works",
"download_url": "https://files.pythonhosted.org/packages/e3/f6/1a64114dee6c46985482c35bdbc12025db59973a0225eec47ac4d306030f/hypothesmith-0.3.3.tar.gz",
"platform": null,
"description": "# hypothesmith\nHypothesis strategies for generating Python programs, something like CSmith.\n\nThis is definitely pre-alpha, but if you want to play with it feel free!\nYou can even keep the shiny pieces when - not if - it breaks.\n\nGet it today with [`pip install hypothesmith`](https://pypi.org/project/hypothesmith/),\nor by cloning [the GitHub repo](https://github.com/Zac-HD/hypothesmith).\n\nYou can run the tests, such as they are, with `tox` on Python 3.6 or later.\nUse `tox -va` to see what environments are available.\n\n## Usage\nThis package provides two Hypothesis strategies for generating Python source code.\n\nThe generated code will always be syntatically valid, and is useful for testing\nparsers, linters, auto-formatters, and other tools that operate on source code.\n\n> DO NOT EXECUTE CODE GENERATED BY THESE STRATEGIES.\n>\n> It could do literally anything that running Python code is able to do,\n> including changing, deleting, or uploading important data. Arbitrary\n> code can be useful, but \"arbitrary code execution\" can be very, very bad.\n\n#### `hypothesmith.from_grammar(start=\"file_input\", *, auto_target=True)`\n\nGenerates syntactically-valid Python source code based on the grammar.\n\nValid values for ``start`` are ``\"single_input\"``, ``\"file_input\"``, or\n``\"eval_input\"``; respectively a single interactive statement, a module or\nsequence of commands read from a file, and input for the eval() function.\n\nIf ``auto_target`` is ``True``, this strategy uses ``hypothesis.target()``\ninternally to drive towards larger and more complex examples. We recommend\nleaving this enabled, as the grammar is quite complex and only simple examples\ntend to be generated otherwise.\n\n#### `hypothesmith.from_node(node=libcst.Module, *, auto_target=True)`\n\nGenerates syntactically-valid Python source code based on the node types\ndefined by the [`LibCST`](https://libcst.readthedocs.io/en/latest/) project.\n\nYou can pass any subtype of `libcst.CSTNode`. Alternatively, you can use\nHypothesis' built-in `from_type(node_type).map(lambda n: libcst.Module([n]).code`,\nafter Hypothesmith has registered the required strategies. However, this does\nnot include automatic targeting and limitations of LibCST may lead to invalid\ncode being generated.\n\n## Notable bugs found with Hypothesmith\n- [BPO-40661, a segfault in the new parser](https://bugs.python.org/issue40661),\n was given maximum priority and blocked the planned release of CPython 3.9 beta1.\n- [BPO-38953](https://bugs.python.org/issue38953) `tokenize` -> `untokenize` roundtrip bugs.\n- [BPO-42218](https://bugs.python.org/issue42218) mishandled error case in new PEG parser.\n- [`lib2to3` errors on \\r in comment](https://github.com/psf/black/issues/970)\n- [Black fails on files ending in a backslash](https://github.com/psf/black/issues/1012)\n- [At least three round-trip bugs in LibCST](https://github.com/Instagram/LibCST#acknowledgements)\n ([search commits for \"hypothesis\"](https://github.com/Instagram/LibCST/search?q=Fix+hypothesis&type=commits))\n- [Invalid code generated by LibCST](https://github.com/Instagram/LibCST/issues/287)\n\n### Changelog\n\nPatch notes [can be found in `CHANGELOG.md`](https://github.com/Zac-HD/hypothesmith/blob/master/CHANGELOG.md).\n",
"bugtrack_url": null,
"license": "MPL 2.0",
"summary": "Hypothesis strategies for generating Python programs, something like CSmith",
"version": "0.3.3",
"project_urls": {
"Funding": "https://github.com/sponsors/Zac-HD",
"Homepage": "https://github.com/Zac-HD/hypothesmith"
},
"split_keywords": [
"python",
"testing",
"fuzzing",
"property-based-testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69bc78dcf42c6eaaf7d628f061f1e533a596f5bca2a53be2b714adc5d370d48e",
"md5": "21fb494f63838043adcacc592a575da6",
"sha256": "fdb0172f9de97d09450da40da7da083fdd118bcd2f88b1a2289413d2d496b1b1"
},
"downloads": -1,
"filename": "hypothesmith-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "21fb494f63838043adcacc592a575da6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19247,
"upload_time": "2024-02-16T20:20:47",
"upload_time_iso_8601": "2024-02-16T20:20:47.059289Z",
"url": "https://files.pythonhosted.org/packages/69/bc/78dcf42c6eaaf7d628f061f1e533a596f5bca2a53be2b714adc5d370d48e/hypothesmith-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3f61a64114dee6c46985482c35bdbc12025db59973a0225eec47ac4d306030f",
"md5": "c18c367585a8b4ffffd252c71727f9c4",
"sha256": "96c14802d6c8e85d8975264176878db54b28d2ed921fdbfedc2e6b8ce3c81716"
},
"downloads": -1,
"filename": "hypothesmith-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "c18c367585a8b4ffffd252c71727f9c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25529,
"upload_time": "2024-02-16T20:21:24",
"upload_time_iso_8601": "2024-02-16T20:21:24.511046Z",
"url": "https://files.pythonhosted.org/packages/e3/f6/1a64114dee6c46985482c35bdbc12025db59973a0225eec47ac4d306030f/hypothesmith-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-16 20:21:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Zac-HD",
"github_project": "hypothesmith",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "hypothesmith"
}
JSON
