{"id":2542,"library":"itemadapter","title":"ItemAdapter","description":"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.","status":"active","version":"0.13.1","language":"python","source_language":"en","source_url":"https://github.com/scrapy/itemadapter","tags":["data structures","adapter","scrapy","dataclasses","attrs","pydantic"],"install":[{"cmd":"pip install itemadapter","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"ItemAdapter","correct":"from itemadapter import ItemAdapter"},{"symbol":"AdapterError","correct":"from itemadapter import AdapterError"}],"quickstart":{"code":"from dataclasses import dataclass\nfrom itemadapter import ItemAdapter\n\n# Define a simple dataclass item\n@dataclass\nclass ProductItem:\n    name: str\n    price: float\n    tags: list[str]\n\n# Create instances of different item types\ndataclass_item = ProductItem(name=\"Wireless Mouse\", price=25.99, tags=[\"electronics\", \"peripherals\"])\ndict_item = {\"name\": \"Mechanical Keyboard\", \"price\": 120.00, \"tags\": [\"gaming\", \"peripherals\"]}\n\n# Use ItemAdapter to interact with items uniformly\nadapter_dc = ItemAdapter(dataclass_item)\nadapter_dict = ItemAdapter(dict_item)\n\nprint(f\"Dataclass Item (Type: {type(adapter_dc.item)}):\")\nprint(f\"  Field Names: {adapter_dc.field_names()}\")\nprint(f\"  Name: {adapter_dc['name']}\")\nprint(f\"  Price (get_value): {adapter_dc.get_value('price')}\")\n\nprint(f\"\\nDictionary Item (Type: {type(adapter_dict.item)}):\")\nprint(f\"  Field Names: {adapter_dict.field_names()}\")\nprint(f\"  Name: {adapter_dict['name']}\")\nprint(f\"  Price (get_value): {adapter_dict.get_value('price')}\")\n\n# ItemAdapter also supports setting values if the underlying item is mutable\nif adapter_dc.is_mutable:\n    adapter_dc['price'] = 22.99\n    print(f\"\\nUpdated dataclass item price: {adapter_dc['price']}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or higher if using itemadapter versions 0.10.0+.","message":"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).","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Remove any usage of these `itemadapter.utils` functions from your code. ItemAdapter's core functionality handles item type detection internally.","message":"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.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"If you are using Pydantic v2, ensure you upgrade itemadapter to v0.11.0 or newer for full compatibility.","message":"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.","severity":"gotcha","affected_versions":"<0.11.0 when used with pydantic>=2"}],"env_vars":null,"search_vec":"'-3':53 '0.13.1':68 '1':52 'access':24 'across':29 'activ':40 'adapt':71 'allow':22 'attr':15,74 'class':11 'common':5 'contain':10 'current':65 'data':9,34,69 'dataclass':14,73 'depend':62 'dictionari':13 'differ':30 'everi':51 'field':28 'frequent':47 'interfac':6 'item':20,31 'itemadapt':1,2 'keep':56 'librari':38 'like':12 'logic':36 'maintain':41 'manipul':26 'minor':48 'model':17 'month':54 'process':35 'project':45 'provid':3 'pydant':16,75 'python':59 'releas':49 'rough':50 'scrapi':19,44,72 'simplifi':33 'structur':70 'type':32 'uniform':23 'updat':63 'various':8 'version':60,66","created_at":"2026-04-11T01:32:30.422072+00:00","updated_at":"2026-04-16T15:49:15.686088+00:00","problems":[{"fix":"Install the library using pip: `pip install itemadapter`","cause":"The 'itemadapter' library is not installed in the Python environment where the code is being executed.","error":"ModuleNotFoundError: No module named 'itemadapter'"},{"fix":"Pass the actual data item to `ItemAdapter`, not an already-wrapped adapter. For example, if `adapter` is an `ItemAdapter` instance, use `adapter.item` to get the original item.","cause":"You are attempting to create an `ItemAdapter` instance by passing an already existing `ItemAdapter` object to its constructor, instead of the original data item (e.g., a dictionary, a dataclass, or a Scrapy Item).","error":"TypeError: No adapter found for objects of type: <class 'itemadapter.adapter.ItemAdapter'>"},{"fix":"Before accessing attributes or methods, check if the retrieved value is a list. If it is, iterate through the list or access a specific element (e.g., `item_adapter['date_field'][0].date()` if you expect a single date within a list).","cause":"A field accessed through `ItemAdapter` unexpectedly returned a list, and you attempted to call a method or access an attribute (like `.date()`) directly on that list, which is a common mistake when a field might contain single or multiple values.","error":"AttributeError: 'list' object has no attribute 'date'"},{"fix":"Ensure the field name is correct and present in the item. Alternatively, use the `.get()` method (e.g., `adapter.get('field_name', default_value)`) to provide a default value if the field might be missing, preventing a `KeyError`.","cause":"You are trying to access a field (key) on an `ItemAdapter` instance that does not exist in the underlying data item it wraps.","error":"KeyError: 'field_name'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.13.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/scrapy/itemadapter","docs":null,"changelog":"https://github.com/scrapy/itemadapter/blob/master/Changelog.md","pypi":"https://pypi.org/project/itemadapter/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}