Extract and process code blocks from Markdown files.
Project description
codeblocks
Extract and process code blocks from Markdown files. Now you can keep code examples automatically:
- formatted (e.g. using black for Python)
- type checked
- unit tested
- linted
- up-to-date with
--help
- etc
Install
With pip:
pip install codeblocks
With poetry:
poetry add codeblocks
Usage
Usage: codeblocks [OPTIONS] LANGUAGE FILE [COMMAND]...
Extract or process LANGUAGE code blocks in Markdown FILE.
Extract Python code blocks:
codeblocks python README.md
Reformat Python code blocks using black, in place:
codeblocks python README.md -- black -
Options:
--wrap Wrap each code block in a function.
--check Do not modify the file, just return the status. Return code 0 means
block matches the command output. Return code 1 means block would
be modified.
--help Show this message and exit.
Examples
Extract Python code blocks:
codeblocks python README.md
Check formatting of Python code blocks with black:
codeblocks --check python README.md -- black -
Reformat Python code blocks with black, in place:
codeblocks python README.md -- black -
Type check Python code blocks with mypy (--wrap
puts each code block into its own function):
mypy somemodule anothermodule <(codeblocks python --wrap README.md)
Insert the output of codeblock --help
into usage
block in this README.md:
codeblocks usage README.md -- codeblocks --help
Check that usage
block in this README.md is up-to-date with --help
output:
codeblocks --check usage README.md -- codeblocks --help
Full type checking example
def plus(x: int, y: int) -> int:
return x + y
plus(1, '2')
$ mypy --pretty --strict <(codeblocks python README.md)
/dev/fd/63:5: error: Argument 2 to "plus" has incompatible type "str"; expected "int"
plus(1, '2')
^
Found 1 error in 1 file (checked 1 source file)
Rationale
There are alternative tools, but none of them supported all of the cases above.
- prettier can reformat Markdown code blocks (PR), but it works only for supported languages like JavaScript. It does not support Python. No lint or unit test support.
- blacken-docs can reformat Python code blocks, but it does not support all black options. For example,
black --check
is not supported. No lint or unit test support. In addition,codeblocks
implementation is much simpler and is not coupled with black. - excode is very similar, but does not support in place modifications.
- gfm-code-blocks does not have command line interface.
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
codeblocks-0.2.2.tar.gz
(7.9 kB
view hashes)
Built Distribution
Close
Hashes for codeblocks-0.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b7e95956c446f39838e7305e0716a0ccb2eefb4d9fa7bd319fd474dc91105b06 |
|
MD5 | d9bebfc01dcb6db16acffd34ce229999 |
|
BLAKE2b-256 | 2190999086673a35d698f76e2d5d703a2768df62eb6eebf9c56b3c5d378cbe5c |