Skip to main content

mutagroup

mutagroup defines mutation packs for a mutation-testing engine. A pack registers LibCST mutations and filters and supplies a cstvis.Collector for discovery and application of individual mutations. A supercollection runs multiple packs over the same source in a single coordinate discovery pass.

Define a pack

from libcst import Add, Subtract
from mutagroup import Context, MutationsCollection

mutations = MutationsCollection('I')


@mutations.mutation(13)
def change_add(node: Add) -> Subtract:
    return Subtract(
        whitespace_before=node.whitespace_before,
        whitespace_after=node.whitespace_after,
    )


@mutations.filter
def formatted_adds(node: Add) -> bool:
    return not node.whitespace_before.empty


@change_add.filter
def skip_generated(_node: Add, context: Context) -> bool:
    return context.comment != ' generated'

change_add.id is I-13. Use @mutations.mutation to take the lowest free positive number at registration time. Explicit numbers keep public IDs stable as a pack evolves. Registering a number twice in the same pack raises an error.

Mutations and both kinds of filters accept a node and an optional Context. cstvis resolves the first parameter's annotation. Matching collection filters run at most once per node, before bound filters. Bound filters apply to their own mutation and matching node types. A false result suppresses the corresponding coordinates.

When cstvis calls a mutation or one of its bound filters, context.meta includes mutation_id and mutation_name. These are the registered ID and the mutation handler's Python name. Custom metadata can use other keys.

Run one or more packs

from mutagroup import MutationsSuperCollection

packs = MutationsSuperCollection([mutations], metacode_key='muta')
source = 'a = 1 + 2 # muta: ignore[I-13]\nb = 3 + 4\n'
changer = packs.get_changer(source)
for coordinate in changer.iterate_coordinates():
    print(coordinate.converter_id, changer.apply_coordinate(coordinate))

Each .get_changer(source) call snapshots the registered mutations and filters. iterate_coordinates() discovers candidates from all packs in source order, with each pack's filters scoped to that pack. apply_coordinate() produces one mutant of the original source. Pack prefixes must be unique within a supercollection.

The default metacode key is muta. On the line where a node starts, # muta: ignore[I-13] and # muta: ignore["I-13"] suppress that mutation. # muta: ignore[I] suppresses mutations from pack I. A directive can list multiple IDs, as in # muta: ignore[I-13, J]. The short # muta ignore I-13 form also works on its own.

Pass project-wide mutation IDs to packs.get_changer(source, ignored=ids). For a standalone pack, use Changer(source, collector=mutations.collector(ignored=ids)) from cstvis.

Load packs from plugins

Define a pack in example_mutations/plugin.py in your plugin package. Use @mutations.plugin to register a function that takes no arguments and returns the pack.

from libcst import Integer
from mutagroup import MutationsCollection, mutations

pack = MutationsCollection('N')


@pack.mutation(1)
def replace_integer(node: Integer) -> Integer:
    return node.with_changes(value='0')


@mutations.plugin
def number_pack() -> MutationsCollection:
    return pack

In the plugin package's pyproject.toml, add an entry point that tells Pristan which module to import.

[project.entry-points.pristan]
example_mutations = 'example_mutations.plugin'

Run python -m pip install . from the plugin package's root in the Python environment that runs mutagroup. get_mutations() discovers the installed plugins and collects their packs into a supercollection.

from mutagroup import MutationsSuperCollection

packs = MutationsSuperCollection.get_mutations()
changer = packs.get_changer('answer = 42')
for coordinate in changer.iterate_coordinates():
    print(coordinate.converter_id, changer.apply_coordinate(coordinate))

Metadata

Release files for mutagroup 0.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mutagroup 0.0.2
File Size Uploaded Provenance Actions
mutagroup-0.0.2.tar.gz 12.3 kB With provenance Details for mutagroup-0.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mutagroup 0.0.2
File Interpreter ABI Platform Actions
mutagroup-0.0.2-py3-none-any.whl Python 3 none any Details for mutagroup-0.0.2-py3-none-any.whl

Total release size: 24.0 kB

Release files / mutagroup-0.0.2.tar.gz

Download URL mutagroup-0.0.2.tar.gz
Size 12.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9fa89ffed2f97832948fe4abd705870466960597c57869cae67cb184c37b2ef4
BLAKE2b-256 checksum
How to use checksums
43f631a42c05d5aaaa8fdc0d2f66b325a2f2bd6e00fd6379996e1d77006cba29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mutagroup-0.0.2-py3-none-any.whl

Download URL mutagroup-0.0.2-py3-none-any.whl
Size 11.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9c46a36d68b8ce321f367ae4da0cbbd34bc3f9f94043386837bb00e3d081d6f2
BLAKE2b-256 checksum
How to use checksums
9f2277ab9133329ee96760443ac2e3df0f7f89549607a26839efab20c9fb0b4c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for mutagroup 0.0.2

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mutagroup-0.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.0.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page