ItemAdapter

0.13.1 · active · verified Fri Apr 10

ItemAdapter provides a common interface for various data container classes like dictionaries, dataclasses, attrs, Pydantic models, and Scrapy Items. It allows uniform access and manipulation of fields across different item types, simplifying data processing logic. The library is actively maintained by the Scrapy project, with frequent minor releases (roughly every 1-3 months) to keep up with Python versions and dependency updates. The current version is 0.13.1.

Warnings

breaking ItemAdapter has progressively dropped support for older Python versions. As of v0.10.0, Python 3.8 is no longer supported. Prior to this, v0.9.0 dropped 3.7, and v0.8.0 dropped 3.6. Ensure your Python environment meets the minimum requirement (Python 3.9+ for versions >=0.10.0).
Fix: Upgrade your Python environment to 3.9 or higher if using itemadapter versions 0.10.0+.
breaking The undocumented predicate functions `is_attrs_instance()`, `is_dataclass_instance()`, `is_pydantic_instance()`, and `is_scrapy_item()` from the `itemadapter.utils` module were deprecated in v0.5.0 and completely removed in v0.11.0.
Fix: Remove any usage of these `itemadapter.utils` functions from your code. ItemAdapter's core functionality handles item type detection internally.
gotcha Versions of itemadapter prior to v0.11.0 (e.g., v0.9.0 explicitly stated Pydantic >= 2 was not supported) do not properly support Pydantic v2 models. Using Pydantic v2 with older itemadapter versions will lead to incorrect behavior or errors.
Fix: If you are using Pydantic v2, ensure you upgrade itemadapter to v0.11.0 or newer for full compatibility.

Install

pip install itemadapter Install stable version

Imports

ItemAdapter
```
from itemadapter import ItemAdapter
```
AdapterError
```
from itemadapter import AdapterError
```

Quickstart

This quickstart demonstrates how to use `ItemAdapter` to create a unified interface for different item types, specifically a Python dataclass and a dictionary. It shows how to access field names and values using both dictionary-like access and `get_value()`, and how to check if an item is mutable for value assignment.

from dataclasses import dataclass
from itemadapter import ItemAdapter

# Define a simple dataclass item
@dataclass
class ProductItem:
    name: str
    price: float
    tags: list[str]

# Create instances of different item types
dataclass_item = ProductItem(name="Wireless Mouse", price=25.99, tags=["electronics", "peripherals"])
dict_item = {"name": "Mechanical Keyboard", "price": 120.00, "tags": ["gaming", "peripherals"]}

# Use ItemAdapter to interact with items uniformly
adapter_dc = ItemAdapter(dataclass_item)
adapter_dict = ItemAdapter(dict_item)

print(f"Dataclass Item (Type: {type(adapter_dc.item)}):")
print(f"  Field Names: {adapter_dc.field_names()}")
print(f"  Name: {adapter_dc['name']}")
print(f"  Price (get_value): {adapter_dc.get_value('price')}")

print(f"\nDictionary Item (Type: {type(adapter_dict.item)}):")
print(f"  Field Names: {adapter_dict.field_names()}")
print(f"  Name: {adapter_dict['name']}")
print(f"  Price (get_value): {adapter_dict.get_value('price')}")

# ItemAdapter also supports setting values if the underlying item is mutable
if adapter_dc.is_mutable:
    adapter_dc['price'] = 22.99
    print(f"\nUpdated dataclass item price: {adapter_dc['price']}")

view raw JSON →