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
Quick start
(if uv is available)
Try codeblocks without installing:
uvx codeblocks --help
Install to PATH:
uv tool install codeblocks
codeblocks --help
Install with Python package manager
With pip:
pip install codeblocks
With uv:
uv add 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 with `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 COMMAND output. Return code 1 means block
would be modified.
--version Show the version and exit.
--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 <(codeblocks python README.md)
/dev/fd/63:5: error: Argument 2 to "plus" has incompatible type "str"; expected "int" [arg-type]
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 --checkis not supported. No lint or unit test support. In addition,codeblocksimplementation 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.
- codedown does not support processing and separate code block extraction
- cog is fully generic, but requires writing scripts embedded in Markdown
Metadata
Release files for codeblocks 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codeblocks-0.4.1.tar.gz | 15.7 kB | Without provenance | Details for codeblocks-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codeblocks-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for codeblocks-0.4.1-py3-none-any.whl |
Total release size: 24.1 kB
Release files / codeblocks-0.4.1.tar.gz
| Download URL | codeblocks-0.4.1.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4ea68184f7a3ddfb2234882abfdfc16b48947dd6f37c619b11fa6235763696f
|
|
BLAKE2b-256 checksum How to use checksums |
4859d42e6f547d670e91b0f90f0227b762c934d896dfdfb61e6cdaf1fc11112c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.5.1
|
Release files / codeblocks-0.4.1-py3-none-any.whl
| Download URL | codeblocks-0.4.1-py3-none-any.whl |
|---|---|
| Size | 8.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f2c918fdd6b1519880534c20fffe3d41d6469f83f45192f24fd96a6ae92eb1ac
|
|
BLAKE2b-256 checksum How to use checksums |
14d78bd241888969bb01c4541a32c11af0ce7439d30f730cd59163b37335b9f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.5.1
|
Security for codeblocks 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.