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.

A plugin library can expose its MutationsCollection instance to the engine.

Metadata

Release files for mutagroup 0.0.1

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.1
File Size Uploaded Provenance Actions
mutagroup-0.0.1.tar.gz 11.4 kB With provenance Details for mutagroup-0.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 22.4 kB

Release files / mutagroup-0.0.1.tar.gz

Download URL mutagroup-0.0.1.tar.gz
Size 11.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4482ebea5ef1a2abb658278569ac420b975583c22a2a2c88a43d4e3ea88dd71d
BLAKE2b-256 checksum
How to use checksums
9cfae3ea58b7f62d801c1749f5faec624feba092e172c6f1af36792d25f5feea
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.1-py3-none-any.whl

Download URL mutagroup-0.0.1-py3-none-any.whl
Size 11.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ea35747ac092366c2cefe926e6ddf8bc1154fd3bfb6fc809ab7c51d2dfd73fba
BLAKE2b-256 checksum
How to use checksums
698dddc553d901c97d1f0d0b4dff79bd738e962f09f802f8197a0311afe66083
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.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.

Full provenance

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

Select from 2 files

Attestation for mutagroup-0.0.1.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.1 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