Typing Stubs for Braintree

Common errors

• ModuleNotFoundError: No module named 'braintree'

  cause The actual `braintree` runtime library is not installed in your environment, only the type stubs.
  fix Run `pip install braintree` to install the core Braintree SDK.

• error: Library "braintree" has no attribute "Configuration" (reportMissingModuleStubs)

  cause Your type checker (e.g., mypy, pylance) cannot find the type definition for `Configuration` within the `braintree` module. This usually means `types-braintree` is not installed, not correctly picked up, or is outdated relative to your `braintree` version.
  fix Ensure `types-braintree` is installed (`pip install types-braintree`) and your type checker is configured to use it. Also, verify both `braintree` and `types-braintree` are up-to-date.

• error: Name "Environment" is not defined

  cause If this error comes from a type checker, it means the type information for `braintree.Environment` is not available. This can happen if `types-braintree` is missing or not properly linked by the type checker.
  fix Install `types-braintree` (`pip install types-braintree`) to provide the necessary type definitions for Braintree enums and classes.

Warnings

• gotcha The `types-braintree` package only provides type hints for the `braintree` library. It does not provide any runtime functionality. You must install the `braintree` package itself for your code to run.
  Fix: Ensure both `pip install braintree` and `pip install types-braintree` are run in your environment.
• gotcha Mismatching versions between `braintree` and `types-braintree` can lead to incorrect type checking results. Newer features in `braintree` might not yet have stubs, or outdated stubs might conflict with runtime changes.
  Fix: Keep both `braintree` and `types-braintree` up to date. If type errors persist for new features, consider contributing to typeshed or temporarily suppressing specific type checker errors.
• breaking Recent versions of `types-braintree` (and `typeshed` generally) require Python 3.10 or newer. Users on older Python versions will encounter installation errors or unexpected type checking behavior.
  Fix: Upgrade your Python environment to 3.10 or newer. If you must use an older Python version, you might need to pin `types-braintree` to an older compatible version, which might lack stubs for newer `braintree` features.
• gotcha When configuring Braintree, always use `braintree.Environment.Sandbox` for testing and `braintree.Environment.Production` with your actual production keys for live transactions. Using sandbox credentials in production or vice-versa will lead to errors.
  Fix: Ensure your `BRAINTREE_ENVIRONMENT` and corresponding `merchant_id`, `public_key`, `private_key` environment variables are correctly set for your target environment (Sandbox or Production).

Install

• pip install braintree types-braintree Install Braintree SDK and its type stubs

Imports

• Configuration

  import braintree; braintree.Configuration(...)

  Used to set up your Braintree environment (sandbox/production) and credentials. These are runtime imports from the `braintree` library, for which `types-braintree` provides type hints.
• BraintreeGateway

  import braintree; braintree.BraintreeGateway(...)

  The main entry point for interacting with the Braintree API. These are runtime imports from the `braintree` library, for which `types-braintree` provides type hints.
• Environment

  import braintree; braintree.Environment.Sandbox

  Enum for specifying the Braintree environment (Sandbox, Production). These are runtime imports from the `braintree` library, for which `types-braintree` provides type hints.

Quickstart

This quickstart demonstrates how to configure the Braintree gateway using environment variables and generate a client token. This code uses the actual `braintree` library; `types-braintree` merely provides static type checking for this code.

import braintree
import os

# Configure Braintree Gateway using environment variables for security
gateway = braintree.BraintreeGateway(
    braintree.Configuration(
        environment=os.environ.get('BRAINTREE_ENVIRONMENT', braintree.Environment.Sandbox),
        merchant_id=os.environ.get('BRAINTREE_MERCHANT_ID', 'your_sandbox_merchant_id'),
        public_key=os.environ.get('BRAINTREE_PUBLIC_KEY', 'your_sandbox_public_key'),
        private_key=os.environ.get('BRAINTREE_PRIVATE_KEY', 'your_sandbox_private_key')
    )
)

# Example: Generate a client token (common for web/mobile integrations)
try:
    client_token = gateway.client_token.generate({})
    print(f"Generated Client Token: {client_token}")
except Exception as e:
    print(f"Error generating client token: {e}")