Mix natural language into your Python code
Project description
Maccarone: use English in your Python 🍝
Maccarone is an experimental tool that lets you write lines of English instead of Python in your Python source code. It looks like this:
def add_two_numbers(x, y):
#<<add the args>>
#<<argparse stuff>>
Maccarone lets you run that program like any other Python script:
$ python -m examples.add 2 2
The sum of 2 and 2 is 4
Caution
Be careful: Maccarone is an unstable and somewhat whimsical experiment.
Quickstart
Prerequisites
- Python 3.10+
- OpenAI API key with GPT-4 (
export OPENAI_API_KEY
)
Install
pip install maccarone
Configure
Set up Maccarone in your base package __init__.py
:
import maccarone
maccarone.enable()
Run
Natural-language snippets go inside special comment blocks:
#<<like this>>
#<<
# or this
#>>
Try it out with the add_two_numbers()
example above.
Note that the first run of a source file can take 10+ seconds while Maccarone generates code with GPT-4.
Usage guide
Snippet detection
Maccarone will preprocess:
- Any file that contains
#<<
, if you haveenable(py_string_matching=True)
(the default). - Any file with extension
.mn.py
.
Modules with an .mn.py
extension can be imported in your Python code just like regular .py
modules.
Distributing your code
You probably want to run Maccarone before you publish a package, but not after.
That outcome is easiest to achieve by:
- Adding
maccarone
only as a dev dependency. - Using the
.mn.py
extension for source files containing natural language snippets. - Running the standalone
maccarone
preprocessor during your package build process.
maccarone
will produce a .py
file for any .mn.py
found under a designated path:
$ ls examples/
add.mn.py fizzbuzz.mn.py __init__.py todo.mn.py
$ maccarone examples/
...
$ ls examples/
add.mn.py add.py fizzbuzz.mn.py fizzbuzz.py __init__.py todo.mn.py todo.py
You would typically run maccarone
before running, e.g., python -m build
and publishing the package.
Related work
FAQs
What prevents my programs from behaving differently every time I recompile?
The strength of your faith in GPT-4.
What about non-English languages?
They are likely to work, but less likely than English.
What does "maccarone" mean?
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for maccarone-0.0.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5ba84a70cbc7f6038322438316477a7c2276fd3d841a9797ba1b3a049dcdd8a0 |
|
MD5 | d58d51bad2532982407df72aaa727204 |
|
BLAKE2b-256 | d66518123ae6cf23838955a830e717e4ebf9a4c9f75e83aab918d091ccf2c386 |