# Beatbox Recorder
<p align="center">
<img src="https://raw.githubusercontent.com/andrewlwn77/beatbox-recorder/main/docs/assets/beatbox.png" alt="Beatbox Logo" width="400"/>
</p>
## Overview
Beatbox is a lightweight Python library that records and replays function calls, making it perfect for testing, mocking, and debugging. It can capture the results of expensive operations, API calls, or complex computations and play them back instantly, significantly speeding up tests and development cycles.
## Requirements
- Python 3.9 or higher
## Features
- Record and playback function calls with identical results
- Support for both synchronous and asynchronous functions
- Handles complex Python types (sets, tuples, datetimes, custom objects)
- Graceful handling of circular references
- Easy storage management with JSON files
- Simple API with record/playback/bypass modes
## Installation
Using pip:
```bash
pip install beatbox-recorder
```
Using poetry:
```bash
poetry add beatbox-recorder
```
## Quick Start
```python
from beatbox import Beatbox, Mode
# Create a Beatbox instance
bb = Beatbox("my_storage.json")
# Function to wrap
async def fetch_user_data(user_id: int):
# Expensive API call or database query
response = await api.get_user(user_id)
return response.data
# Wrap the function
wrapped_fetch = bb.wrap(fetch_user_data)
# Record mode - will make real API calls and store results
bb.set_mode(Mode.RECORD)
user_data = await wrapped_fetch(123) # Makes actual API call
# Playback mode - will use stored results without making API calls
bb.set_mode(Mode.PLAYBACK)
user_data = await wrapped_fetch(123) # Returns stored result instantly
# Bypass mode - makes real API calls without recording
bb.set_mode(Mode.BYPASS)
user_data = await wrapped_fetch(123) # Makes actual API call
```
## Usage in Tests
```python
import pytest
from beatbox import Beatbox, Mode
@pytest.fixture
def recorder():
bb = Beatbox("test_storage.json")
return bb
def test_user_service(recorder):
user_service = UserService()
# Record actual API responses
recorder.set_mode(Mode.RECORD)
result = user_service.get_user(123)
# Use recorded responses in future test runs
recorder.set_mode(Mode.PLAYBACK)
cached_result = user_service.get_user(123)
assert cached_result == result
```
## Storage
Beatbox stores recorded function calls and their results in a JSON file. The storage format is:
```json
{
"hash_of_function_args": {
"result": "serialized_result",
"timestamp": "2024-01-01T00:00:00"
}
}
```
## Supported Types
Beatbox can handle serialization of:
- Basic Python types (str, int, float, bool, None)
- Collections (list, tuple, dict, set)
- Datetime objects
- Custom objects (serialized as dictionaries)
- Exceptions
- Circular references (replaced with placeholder)
- Range objects
## Error Handling
```python
from beatbox import NoRecordingError, SerializationError
try:
bb.set_mode(Mode.PLAYBACK)
result = wrapped_function(123)
except NoRecordingError:
# No recording found for these arguments
pass
except SerializationError:
# Failed to serialize/deserialize result
pass
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/andrewlwn77/beatbox-recorder-py",
"name": "beatbox-recorder",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "testing, mocking, recorder, playback",
"author": "Andrew Lewin",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/aa/b2/e567621c76a1b5d7618924579f80ee62d89857e844316c16dce03cfcc9b9/beatbox_recorder-1.0.1.tar.gz",
"platform": null,
"description": "# Beatbox Recorder\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/andrewlwn77/beatbox-recorder/main/docs/assets/beatbox.png\" alt=\"Beatbox Logo\" width=\"400\"/>\n</p>\n\n## Overview\n\nBeatbox is a lightweight Python library that records and replays function calls, making it perfect for testing, mocking, and debugging. It can capture the results of expensive operations, API calls, or complex computations and play them back instantly, significantly speeding up tests and development cycles.\n\n## Requirements\n\n- Python 3.9 or higher\n\n## Features\n\n- Record and playback function calls with identical results\n- Support for both synchronous and asynchronous functions\n- Handles complex Python types (sets, tuples, datetimes, custom objects)\n- Graceful handling of circular references\n- Easy storage management with JSON files\n- Simple API with record/playback/bypass modes\n\n## Installation\n\nUsing pip:\n```bash\npip install beatbox-recorder\n```\n\nUsing poetry:\n```bash\npoetry add beatbox-recorder\n```\n\n## Quick Start\n\n```python\nfrom beatbox import Beatbox, Mode\n\n# Create a Beatbox instance\nbb = Beatbox(\"my_storage.json\")\n\n# Function to wrap\nasync def fetch_user_data(user_id: int):\n # Expensive API call or database query\n response = await api.get_user(user_id)\n return response.data\n\n# Wrap the function\nwrapped_fetch = bb.wrap(fetch_user_data)\n\n# Record mode - will make real API calls and store results\nbb.set_mode(Mode.RECORD)\nuser_data = await wrapped_fetch(123) # Makes actual API call\n\n# Playback mode - will use stored results without making API calls\nbb.set_mode(Mode.PLAYBACK)\nuser_data = await wrapped_fetch(123) # Returns stored result instantly\n\n# Bypass mode - makes real API calls without recording\nbb.set_mode(Mode.BYPASS)\nuser_data = await wrapped_fetch(123) # Makes actual API call\n```\n\n## Usage in Tests\n\n```python\nimport pytest\nfrom beatbox import Beatbox, Mode\n\n@pytest.fixture\ndef recorder():\n bb = Beatbox(\"test_storage.json\")\n return bb\n\ndef test_user_service(recorder):\n user_service = UserService()\n \n # Record actual API responses\n recorder.set_mode(Mode.RECORD)\n result = user_service.get_user(123)\n \n # Use recorded responses in future test runs\n recorder.set_mode(Mode.PLAYBACK)\n cached_result = user_service.get_user(123)\n assert cached_result == result\n```\n\n## Storage\n\nBeatbox stores recorded function calls and their results in a JSON file. The storage format is:\n\n```json\n{\n \"hash_of_function_args\": {\n \"result\": \"serialized_result\",\n \"timestamp\": \"2024-01-01T00:00:00\"\n }\n}\n```\n\n## Supported Types\n\nBeatbox can handle serialization of:\n- Basic Python types (str, int, float, bool, None)\n- Collections (list, tuple, dict, set)\n- Datetime objects\n- Custom objects (serialized as dictionaries)\n- Exceptions\n- Circular references (replaced with placeholder)\n- Range objects\n\n## Error Handling\n\n```python\nfrom beatbox import NoRecordingError, SerializationError\n\ntry:\n bb.set_mode(Mode.PLAYBACK)\n result = wrapped_function(123)\nexcept NoRecordingError:\n # No recording found for these arguments\n pass\nexcept SerializationError:\n # Failed to serialize/deserialize result\n pass\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Record and playback function calls for testing and mocking",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/andrewlwn77/beatbox-recorder-py",
"Repository": "https://github.com/andrewlwn77/beatbox-recorder-py"
},
"split_keywords": [
"testing",
" mocking",
" recorder",
" playback"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2398443837a66022c8c2985c396705d16d00564f40fb66f7b26c4e60f04160be",
"md5": "3ce6b1f8a084800616f7d6acd8d03e33",
"sha256": "8a90c5dc38d8a34001088b40384524e9ccc9fdf2aa641cc60b59aaf0f126b5e8"
},
"downloads": -1,
"filename": "beatbox_recorder-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ce6b1f8a084800616f7d6acd8d03e33",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 5872,
"upload_time": "2024-12-23T18:33:45",
"upload_time_iso_8601": "2024-12-23T18:33:45.856930Z",
"url": "https://files.pythonhosted.org/packages/23/98/443837a66022c8c2985c396705d16d00564f40fb66f7b26c4e60f04160be/beatbox_recorder-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aab2e567621c76a1b5d7618924579f80ee62d89857e844316c16dce03cfcc9b9",
"md5": "6b1a6dc713afb8010be7701ca8c28e26",
"sha256": "3ea7d2ede10d4662acd7bed12fbfda9a8ec572b69479e925142b4f7f6f2c4d18"
},
"downloads": -1,
"filename": "beatbox_recorder-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6b1a6dc713afb8010be7701ca8c28e26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 5364,
"upload_time": "2024-12-23T18:33:48",
"upload_time_iso_8601": "2024-12-23T18:33:48.117021Z",
"url": "https://files.pythonhosted.org/packages/aa/b2/e567621c76a1b5d7618924579f80ee62d89857e844316c16dce03cfcc9b9/beatbox_recorder-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-23 18:33:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andrewlwn77",
"github_project": "beatbox-recorder-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "beatbox-recorder"
}
JSON
