Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

# cutting module

Utilities for cutting code.

## collect_blocks function

    collect_blocks(
        lines
    )

Collect blocks in the lines.

## cut_and_save function

    cut_and_save(
        code,
        section_name,
        path=None,
        mkdir_kwargs=None,
        **kwargs
    )

Cut an annotated section from the code and save to a file.

For arguments see cut_from_code().

## cut_and_save_func function

    cut_and_save_func(
        func,
        *args,
        **kwargs
    )

Cut an annotated function section from a module and save to a file.

For arguments see cut_and_save().

## cut_and_save_module function

    cut_and_save_module(
        module,
        *args,
        **kwargs
    )

Cut an annotated section from a module and save to a file.

For arguments see cut_and_save().

## cut_from_code function

    cut_from_code(
        code,
        section_name,
        prepend_lines=None,
        append_lines=None,
        out_lines_callback=None,
        return_lines=False,
        **kwargs
    )

Parse and cut an annotated section from the code.

The section should start with `# % <section section_name>` and end with `# % </section>`.

You can also define blocks. Each block should start with `# % <block block_name>` and end with `# % </block>`. Blocks will be collected into the dictionary `blocks` before cutting and can be then inserted using Python expressions (see below).

To skip multiple lines of code, place them between `# % <skip [expression]>` and `# % </skip>`, where expression is optional.

To uncomment multiple lines of code, place them between `# % <uncomment [expression]>` and `# % </uncomment>`, where expression is optional.

Everything else after `# %` will be evaluated as a Python expression and should return either None (= skip), a string (= insert one line of code) or an iterable of strings (= insert multiple lines of code). The latter will be appended to the queue and parsed.

Every expression is evaluated strictly, that is, any evaluation error will raise an error and stop the program. To evaluate softly without raising any errors, prepend `?`. The context includes `lines`, `blocks`, `section_name`, `line`, `out_lines`, and `**kwargs`.

## suggest_module_path function

    suggest_module_path(
        section_name,
        path=None,
        mkdir_kwargs=None
    )

Suggest a path to the target file.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings