laboratory

What it is and what it does

Laboratory is a Python framework for running controlled experiments on refactored code in production. You define a control block (your existing, known-good code) and a candidate block (your new implementation), and Laboratory executes both in randomized order, compares their return values, records timing, catches exceptions in the candidate, and publishes results—while always returning the control value to the caller. This lets you gain confidence that a refactor is correct before fully committing to it, even in complex production environments with legacy data and high load.

The package is designed for critical code paths where correctness matters more than speed. You can ramp experiments up gradually by overriding the `enabled` method, customize comparison logic, add context for debugging, and implement your own `publish` method to send metrics and mismatches to monitoring systems. The main caveat is that code with side effects (database writes, state changes) is unsuitable because both branches will execute, potentially causing duplicate writes.

Use it for:

• Refactoring authorization or permission-checking logic in production while verifying the new code matches the old behavior.
• Gradually migrating from one database query strategy to another by running both and comparing results before switching fully.
• Testing a rewritten algorithm on real production data and load to catch edge cases that unit tests miss.
• Validating a new authentication method against the existing one without risking user lockouts.
• Ramping up a candidate implementation for only a subset of users or requests to limit blast radius if issues arise.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Laboratory lets you safely refactor critical code paths by running new and old implementations side-by-side in production, comparing their results, and collecting timing and error data without affecting the live control flow.

Yes, if you own critical code paths and want a structured way to validate refactors in production. The zero-dependency design and MIT license make it low-risk to add. However, the aging maintenance status (last release 2019) means you should verify it works with your target Python version and be prepared to maintain a fork if needed. Not suitable for code with side effects.

Install

laboratory on PyPI

pip install laboratory

uv add laboratory

poetry add laboratory

Installing laboratory

Before you install

Low friction: pure Python wheel with no runtime dependencies. However, the package is aging—last release was 2019-05-05 and last commit 2025-12-22, so while not abandoned, it receives infrequent updates.

License in practice

MIT license (permissive) means you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install laboratory

import laboratory

experiment = laboratory.Experiment()
experiment.control(old_func, args=[data])
experiment.candidate(new_func, args=[data])
result = experiment.conduct()  # returns old_func's value

Code with side effects (database writes, file I/O, state mutations) will execute in both control and candidate branches, causing duplicated writes—unsuitable for such operations.

Verify before relying

• Whether the package still works reliably with modern Python versions beyond those listed in classifiers (3.6 was the latest in the original release metadata).
• Current state of the GitHub repository and whether maintenance is truly active despite the aging status flag.

Package facts

Evidence: laboratory-1.0.2-py2.py3-none-any.whl

Tags

More Utilities packages