---
id: itemadapter
version: "0.13.1"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# itemadapter — Common interface for data container classes

License: permissive · Maintenance: active · Downloads: 2.9M/mo

## What it is and what it does

ItemAdapter is a wrapper class that normalizes access to different data container types—dicts, dataclasses, attrs objects, pydantic models, and Scrapy items—under a single dict-like interface. You wrap an object in ItemAdapter and then read, modify, and query it using standard dictionary operations (indexing, get, update, len) regardless of whether the underlying object is a plain dict, a dataclass, or a Scrapy Item.

The package is designed for code that needs to handle multiple container types uniformly, particularly in data pipelines and web scraping workflows. It implements Python's MutableMapping protocol, so adapters feel like dictionaries. It also provides utility methods like asdict() for recursive conversion to plain dicts, and class-level methods to inspect field names and metadata from item classes before instantiation.

Use it for:

- Normalize access to Scrapy items and plain dicts in a single pipeline without type-checking branches.
- Build generic data transformation code that works with dataclasses, attrs, or pydantic models interchangeably.
- Extract and convert nested item structures to plain dicts for JSON serialization or logging.
- Inspect field metadata and names from dataclass or pydantic models at runtime for validation or schema generation.
- Write middleware or utilities that accept multiple item types and treat them uniformly.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

ItemAdapter wraps data container objects (dicts, dataclasses, attrs, pydantic, Scrapy items) to provide a uniform dict-like interface for reading and modifying them regardless of their underlying type.

Yes. ItemAdapter is actively maintained, has no runtime dependencies, installs with low friction, carries no security vulnerabilities, and solves a real problem for anyone working with multiple data container types. It's particularly valuable in Scrapy projects but useful anywhere you need a uniform interface across dicts, dataclasses, attrs, and pydantic models.

## Install

pip install itemadapter
uv add itemadapter
poetry add itemadapter

## Installing itemadapter

Before you install: Low friction: pure Python wheel with no runtime dependencies. Actively maintained with recent commits; last release 218 days ago.

License in practice: BSD-3-Clause is permissive; you can use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.

Quickstart:

from dataclasses import dataclass
from itemadapter import ItemAdapter

@dataclass
class Item:
    name: str
    price: float

obj = Item(name='foo', price=20.5)
adapter = ItemAdapter(obj)
adapter['name'] = 'bar'
print(adapter.asdict())

Requires Python 3.9+; optional dependencies (scrapy, attrs, pydantic) needed only if working with those specific item types.

Verify before relying:

- Whether the package is actively used in production Scrapy pipelines or primarily in standalone data-handling contexts.
- Performance characteristics when adapting deeply nested or large item structures.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

uniform interface for data containers, dict-like wrapper for dataclasses, scrapy item adapter, abstract data container access, multi-type object wrapper, dataclass dict interface, pydantic attrs dict wrapper, data-container-abstraction, scrapy-integration, dataclass-wrapper

[View on SkillFed](https://skillfed.io/packages/itemadapter) · [View on PyPI](https://pypi.org/project/itemadapter/)