### Install checksum_dict Package

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Installs the checksum_dict library using pip. This is the first step to using the library's features for Ethereum address management.

```bash
pip install checksum_dict
```

--------------------------------

### ChecksumAddressDict - Basic Checksummed Dictionary in Python

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Demonstrates the usage of ChecksumAddressDict for storing and retrieving key-value pairs where keys are Ethereum addresses. It automatically converts any address format to EIP-55 compliant checksum format upon setting or getting values. This ensures consistent address handling.

```python
from checksum_dict import ChecksumAddressDict

# Create an empty dictionary
d = ChecksumAddressDict()

# Set a value using a lowercase address
lower = "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"
d[lower] = True

# The key is stored with proper checksum
print(d)
# Output: ChecksumAddressDict({'0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB': True})

# Retrieve value using any address format
print(d[lower])  # Output: True
print(d["0xB47E3CD837DDF8E4C57F05D70AB865DE6E193BBB"])  # Output: True
print(d["0xb47e3cd837dDF8e4c57f05d70Ab865de6e193BBB"])  # Output: True

# Initialize with a seed dictionary
seed = {"0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb": "CryptoPunks"}
d = ChecksumAddressDict(seed)
print(d)
# Output: ChecksumAddressDict({'0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB': 'CryptoPunks'})

# Initialize with an iterable of key-value tuples
pairs = [
    ("0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb", "CryptoPunks"),
    ("0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "BAYC"),
]
d = ChecksumAddressDict(pairs)
print(list(d.items()))
# Output: [('0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB', 'CryptoPunks'),
#          ('0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', 'BAYC')]

```

--------------------------------

### Token Instance Management with ChecksumAddressDict

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Demonstrates how to manage token instances using a dictionary that automatically handles checksumming of Ethereum addresses. It covers setting information, accessing cached instances, checking for existence, and deleting instances.

```python
from checksum_dict import Token

# Modify through one reference, visible through all
token1.set_info("CryptoPunks", "PUNK")
print(token3.name)  # Output: CryptoPunks

# Access cached instance using subscript notation
cached_token = Token["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"]
assert cached_token is token1

# Check if instance exists without creating it
existing = Token.get_instance("0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb")
print(existing is not None)  # Output: True

non_existing = Token.get_instance("0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d")
print(non_existing is None)  # Output: True

# Delete an instance from the cache
Token.delete_instance("0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb")
```

--------------------------------

### ChecksumAddressSingletonMeta - Thread-Safe Singleton Pattern in Python

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Demonstrates how to use ChecksumAddressSingletonMeta, a metaclass for creating thread-safe singleton instances keyed by Ethereum addresses. This ensures that for any given address, only one instance of a class exists throughout the application, regardless of the address's casing.

```python
from checksum_dict import ChecksumAddressSingletonMeta

# Define a class that uses the singleton metaclass
class Token(metaclass=ChecksumAddressSingletonMeta):
    def __init__(self, address: str):
        self.address = address
        self.name = None
        self.symbol = None

    def set_info(self, name: str, symbol: str):
        self.name = name
        self.symbol = symbol

# Create instances - same address always returns the same instance
token1 = Token("0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb")
token2 = Token("0xB47E3CD837DDF8E4C57F05D70AB865DE6E193BBB")  # uppercase
token3 = Token("0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB")  # checksummed

# All three variables reference the exact same instance
assert token1 is token2 is token3

```

--------------------------------

### Custom Exception Handling for Missing Addresses

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Demonstrates the use of a custom KeyError exception (ChecksumKeyError) provided by the library for more informative error messages when attempting to access non-existent addresses. It also shows that standard KeyError catching still works.

```python
from checksum_dict import ChecksumAddressDict, KeyError as ChecksumKeyError

d = ChecksumAddressDict()
d["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"] = True

try:
    # Access a non-existent address
    value = d["0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"]
except ChecksumKeyError as e:
    print(repr(e))
    # Output: <checksum_dict.KeyError('0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D')>

# Also works with standard KeyError catch
try:
    value = d["0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"]
except KeyError as e:
    print(f"Address not found: {e}")
```

--------------------------------

### Bypassing Checksumming with Low-Level Methods

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Illustrates how to use low-level methods (_setitem_nochecksum and _getitem_nochecksum) to bypass the checksumming process for performance gains when addresses are already known to be checksummed. This is applicable to both ChecksumAddressDict and DefaultChecksumDict.

```python
from checksum_dict import ChecksumAddressDict, DefaultChecksumDict

# For ChecksumAddressDict
d = ChecksumAddressDict()

# Use when you already have a checksummed address
checksummed_key = "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB"

# Set without re-checksumming (faster)
d._setitem_nochecksum(checksummed_key, {"balance": 100})

# Get without re-checksumming (faster)
value = d._getitem_nochecksum(checksummed_key)
print(value)  # Output: {'balance': 100}

# For DefaultChecksumDict - same methods available
dd = DefaultChecksumDict(int)
dd._setitem_nochecksum(checksummed_key, 42)
result = dd._getitem_nochecksum(checksummed_key)
print(result)  # Output: 42

# Note: _setitem_nochecksum validates address format
try:
    d._setitem_nochecksum("invalid", True)  # Raises ValueError
except ValueError as e:
    print(e)  # Output: 'invalid' is not a valid ETH address
```

--------------------------------

### ChecksumAddressDict Usage - Python

Source: https://github.com/bobthebuidler/checksum_dict/blob/master/README.md

Demonstrates how to use ChecksumAddressDict to store and retrieve values using Ethereum addresses as keys. It automatically checksums lowercase addresses upon insertion.

```python
from checksum_dict import ChecksumAddressDict

d = ChecksumAddressDict()
lower = "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"
d[lower] = True
print(d)
# >>> ChecksumAddressDict({'0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB': True})
print(d[lower])
# >>> True
```

--------------------------------

### Integrating with Brownie Contracts

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Shows how to use Brownie Contract objects directly as keys in a ChecksumAddressDict. The library automatically extracts and checksums the contract addresses, allowing retrieval using either the Contract object or its address string.

```python
from checksum_dict import ChecksumAddressDict
from brownie import Contract

# Initialize contracts (in a Brownie environment)
punks = Contract("0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb")
bayc = Contract("0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d")

# Use Contract objects directly as keys
metadata = ChecksumAddressDict()
metadata[punks] = {"name": "CryptoPunks", "supply": 10000}
metadata[bayc] = {"name": "Bored Ape Yacht Club", "supply": 10000}

# Retrieve using either Contract or address string
print(metadata[punks])  # Works with Contract object
print(metadata["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"])  # Works with string

# Keys are stored as checksummed strings
print(list(metadata.keys()))
# Output: ['0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB', '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D']
```

--------------------------------

### DefaultChecksumDict - Checksummed DefaultDict in Python

Source: https://context7.com/bobthebuidler/checksum_dict/llms.txt

Illustrates the use of DefaultChecksumDict, a defaultdict implementation that automatically checksums Ethereum addresses. When a non-existent key is accessed, it creates a default value using a provided factory function, ensuring addresses are always checksummed.

```python
from checksum_dict import DefaultChecksumDict

# Create a default dict with int as the default factory
d = DefaultChecksumDict(int)

# Access a non-existent key - returns default value (0 for int)
lower = "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"
print(d[lower])  # Output: 0

# The key is now in the dict with the default value
print(list(d.keys()))  # Output: ['0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB']

# Increment counter pattern
d["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"] += 1
print(d[lower])  # Output: 1

# Use with list as default factory for collecting items
balances = DefaultChecksumDict(list)
balances["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"].append({"token": "ETH", "amount": 1.5})
balances["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"].append({"token": "USDC", "amount": 1000})
print(balances["0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"])
# Output: [{'token': 'ETH', 'amount': 1.5}, {'token': 'USDC', 'amount': 1000}]

# Initialize with seed data
seed = {"0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d": 100}
d = DefaultChecksumDict(int, seed)
print(d["0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"])  # Output: 100

```

--------------------------------

### DefaultChecksumDict Usage - Python

Source: https://github.com/bobthebuidler/checksum_dict/blob/master/README.md

Illustrates the use of DefaultChecksumDict, a checksumming dictionary that also supports default factory functions, similar to Python's built-in defaultdict.

```python
from checksum_dict import DefaultChecksumDict

default = int
d = DefaultChecksumDict(default)
lower = "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb"
print(d[lower])
# >>> 0
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.