kgb

library7.3pypypi✓ verified 25d ago

kgb is a Python library that provides utilities for creating function spies in unit tests, offering a powerful alternative to traditional mocking. It intercepts and records calls to functions, tracking arguments and return values, and can modify function behavior at the bytecode level. Unlike some mocking frameworks, kgb can spy on top-level functions in addition to class methods. It supports popular testing frameworks like unittest, pytest, nose, and nose2, and maintains an active release cadence, with recent versions adding support for the latest Python releases.

testing

pip install kgb

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · KGB

kgb

testingpythonv7.3

Install

1.6s avg

Import

151ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v7.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.168s · 18.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.134s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SpyAgency

✓ from kgb import SpyAgency

For unittest-based test suites, mix this into your test class.

assert_spy_called_with

✓ from kgb.asserts import assert_spy_called_with

Standalone assertion methods introduced in v7.0, usable without mixing SpyAgency.

This quickstart demonstrates how to use `kgb` within a `unittest.TestCase` to spy on a method, mock its return value, and then assert that the method was called with specific arguments. The `SpyAgency` is mixed into the test class, and `spy_on` is used to intercept calls.

import unittest from kgb import SpyAgency, SpyOpReturn class MyService: def fetch_data(self, url): # In a real application, this might make a network request return f"Actual data from {url}" class TestMyService(SpyAgency, unittest.TestCase): def test_fetch_data_called_and_mocked(self): service = MyService() # Spy on the fetch_data method and make it return a mocked value self.spy_on(service.fetch_data, op=SpyOpReturn("Mocked Data!")) # Call the method that is now spied upon result = service.fetch_data("https://example.com/api/v1/data") # Assertions using kgb's spy capabilities self.assertEqual(result, "Mocked Data!") self.assert_spy_called(service.fetch_data) self.assert_spy_called_with(service.fetch_data, "https://example.com/api/v1/data") # To run this example (typically done via a test runner like `python -m unittest`): # if __name__ == '__main__': # unittest.main()

Debug

Known issues

breakingVersion 7.0 dropped official support for Python 2.6, 3.4, and 3.5. Users on these Python versions must use `kgb` versions older than 7.0.

fix

Upgrade Python to 3.6+ or pin `kgb<7.0` in your dependencies. Python 3.13 and 3.14 are supported in later 7.x releases.

affects: >=7.0

deprecatedCamelCase assertion methods (e.g., `assertSpyCalledWith`) are deprecated in favor of snake_case equivalents (e.g., `assert_spy_called_with`) for improved readability and consistency. While the old versions still exist, new code should use snake_case.

fix

Update assertion calls from `assertSpyCalledWith` to `assert_spy_called_with`, `assertHasSpy` to `assert_has_spy`, etc.

affects: >=7.0

breakingPrior to kgb 2.0, spying on standard functions required accessing a special `.spy` attribute (e.g., `func.spy.called_with()`), which was inconsistent with methods. This `.spy` attribute has been removed.

fix

Directly use assertion methods on the spied function/method, e.g., `func.called_with()`. All spy interactions now behave consistently.

affects: <2.0 to >2.0

gotchaSpying on methods wrapped in decorators that do not preserve the original function's name can cause errors. `kgb` will attempt to detect this and warn you.

fix

When using `spy_on`, provide the original function's name via the `func_name` argument (e.g., `spy_agency.spy_on(BadClass.good_func, owner=BadClass, func_name='good_func')`).

affects: >=7.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'kgb'

The 'kgb' library is not installed in your Python environment or the Python interpreter cannot find it in its search path.

fix

Install the kgb library using pip: `pip install kgb`

ImportError: cannot import name 'Spy' from 'kgb'

The 'Spy' class (or related components like 'SpyAgency') is not directly exposed under the top-level 'kgb' module; it resides in a submodule or needs to be imported differently.

fix

Import 'SpyAgency' (the primary way to manage spies) from the 'kgb' module: `from kgb import SpyAgency`

AttributeError: 'function' object has no attribute 'spy'

This error typically occurs when using an older code style (pre-kgb 2.0) with a newer version of the kgb library. In older versions, spy methods were accessed via a '.spy' attribute (e.g., `my_func.spy.called`). kgb 2.0 and later versions made spy methods directly accessible on the spied function/method object itself (e.g., `my_func.called`).

fix

Remove the '.spy' attribute from your calls. For example, change `my_func.spy.called` to `my_func.called`, and `my_func.spy.assert_called_with()` to `my_func.assert_called_with()`. Alternatively, if using a `SpyAgency`, you'd use its assertion methods like `spy_agency.assert_spy_called(my_func)`.

Upgrade

Version history

7.3latest on PyPI · released Dec 11, 2025

Audit

Dependencies

pythonrequiredCore dependency for Python >=2.7 and !=3.0-3.5, with explicit support up to 3.14.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/beanbaginc/kgb ↗

packagehttps://pypi.org/project/kgb/ ↗

docshttps://github.com/beanbaginc/kgb ↗