Placebo

Common errors

• ModuleNotFoundError: No module named 'boto3'

  cause Placebo is designed to mock `boto3` interactions but does not include `boto3` as a direct installation dependency. This error occurs if `boto3` is not installed in your environment.
  fix Install `boto3` alongside Placebo: `pip install boto3 placebo`.

• TypeError: a bytes-like object is required, not 'str' (or similar errors when processing binary data)

  cause This typically indicates an attempt to process binary response data (e.g., from S3 `get_object` calls) as a string. Older Placebo versions had issues with binary responses, and even with 0.10.0+, incorrect handling of the `StreamingBody` can lead to this.
  fix Ensure you are reading the `botocore.response.StreamingBody` as bytes or handling compression correctly. For example, `response['Body'].read()` will return bytes. If you need to decompress, use `gzip.GzipFile` with `io.BytesIO`.

• AWS calls are still being made to real endpoints even when Placebo is supposedly active.

  cause This can happen if `pill.record()` or `pill.playback()` was not called on the `Pill` object, if `boto3` clients were created before these methods were invoked, or if Placebo was attached to a different `boto3.Session` than the one being used.
  fix Verify that `pill.record()` or `pill.playback()` is explicitly called on the correct `Pill` instance, and that all `boto3` clients intended for mocking are instantiated *after* Placebo has been activated for that session.

Warnings

• breaking Placebo version 0.10.0, released in September 2021, officially dropped support for Python 2.x. Codebases still on Python 2.x will need to upgrade to Python 3.x to use this and future versions.
  Fix: Upgrade your Python environment to Python 3.x (e.g., Python 3.6+ is recommended by Placebo's PyPI classifiers).
• gotcha Older versions of Placebo (prior to 0.10.0) had a bug handling binary response bodies from AWS services, which could lead to incorrect data or errors during playback.
  Fix: Upgrade to Placebo version 0.10.0 or later to ensure correct handling of binary response bodies.
• gotcha When using `boto3.DEFAULT_SESSION`, Placebo may not correctly attach unless `boto3.setup_default_session()` is explicitly called beforehand. If you create `boto3` clients from a default session that hasn't been set up, Placebo might not intercept calls.
  Fix: Explicitly initialize the default session with `boto3.setup_default_session()` before attaching Placebo, or, preferably, create and pass a named `boto3.Session()` object to `placebo.attach()` for clearer scope.
• gotcha Clients created from a `boto3.Session` *before* `pill.record()` or `pill.playback()` is called might not be 'placebo-aware' and will still make live AWS calls. This was a bug fixed in 0.7.2, but misunderstanding the order of operations can still cause issues.
  Fix: Always call `pill.record()` or `pill.playback()` on the `Pill` object *before* creating any `boto3` clients from the associated session that you intend to mock.

Install

• pip install placebo Install latest version

Imports

• attach

  from placebo import attach

• Session
  wrong:

  import boto3; session = boto3.DEFAULT_SESSION

  correct:

  import boto3; boto3.Session()

  While `boto3.DEFAULT_SESSION` exists, it must be explicitly set up with `boto3.setup_default_session()` for Placebo to attach correctly, otherwise, directly creating a `boto3.Session()` is more reliable for explicit control.

Quickstart

This example demonstrates how to set up Placebo for both recording and playing back AWS API calls using `boto3`. It creates a `boto3` session, attaches Placebo to it with a specified data directory, and then, based on an environment variable, either records S3 `list_buckets` calls or plays them back from previously recorded JSON files.

import boto3
import placebo
import os

data_path = os.path.join(os.path.dirname(__file__), 'placebo_data')
os.makedirs(data_path, exist_ok=True)

session = boto3.Session(region_name='us-east-1')
pill = placebo.attach(session, data_path=data_path)

# --- Recording mode ---
# Set PLACEBO_MODE=record in environment variables to enable recording
# e.g., PLACEBO_MODE=record python your_script.py
if os.environ.get('PLACEBO_MODE') == 'record':
    print("Recording AWS calls...")
    pill.record()
    s3 = session.client('s3')
    try:
        s3.list_buckets()
        print("Buckets listed and recorded.")
    except Exception as e:
        print(f"Error during recording: {e}")

# --- Playback mode ---
# Default behavior, or set PLACEBO_MODE=playback
# e.g., PLACEBO_MODE=playback python your_script.py
else:
    print("Playing back recorded AWS calls...")
    pill.playback()
    s3 = session.client('s3')
    try:
        response = s3.list_buckets()
        print("Buckets listed from recording:")
        for bucket in response.get('Buckets', []):
            print(f" - {bucket['Name']}")
    except Exception as e:
        print(f"Error during playback: {e}")

# Clean up (optional, for demonstration purposes)
# import shutil
# if os.path.exists(data_path):
#     shutil.rmtree(data_path)