======= ========================== SEP 3 Title List fields API Author Pablo Hoffman Created 2009-07-21 Status Obsolete by :ref:sep-008 ======= ==========================

========================= SEP-002 - List fields API

This page presents different usage scenarios for the new multi-valued field, called !ListField.

Proposed Implementation

.. code-block:: python

#!python from scrapy.item.fields import BaseField

class ListField(BaseField): def init(self, field, default=None): self._field = field super(ListField, self).init(default)

   def to_python(self, value):
       if hasattr(value, "__iter__"):  # str/unicode not allowed
           return [self._field.to_python(v) for v in value]
       else:
           raise TypeError("Expected iterable, got %s" % type(value).__name__)

   def get_default(self):
       # must return a new copy to avoid unexpected behaviors with mutable defaults
       return list(self._default)

Usage Scenarios

Defining a list field

.. code-block:: python

#!python from scrapy.item.models import Item from scrapy.item.fields import ListField, TextField, DateField, IntegerField

class Article(Item): categories = ListField(TextField) dates = ListField(DateField, default=[]) numbers = ListField(IntegerField, [])

Another case of products and variants which highlights the fact that it's important to instantiate !ListField with field instances, not classes:

.. code-block:: python

#!python from scrapy.item.models import Item from scrapy.item.fields import ListField, TextField

class Variant(Item): name = TextField()

class Product(Variant): variants = ListField(ItemField(Variant))

Assigning a list field

.. code-block:: python

#!python i = Article()

i["categories"] = [] i["categories"] = ["politics", "sport"] i["categories"] = ["test", 1] # -> raises TypeError i["categories"] = asd # -> raises TypeError

i["dates"] = [] i["dates"] = ["2009-01-01"] # raises TypeError? (depends on TextField)

i["numbers"] = ["1", 2, "3"] i["numbers"] # returns [1, 2, 3]

Default values

.. code-block:: python

#!python i = Article()

i["categories"] # raises KeyError i.get("categories") # returns None

i["numbers"] # returns []

Appending values

.. code-block:: python

#!python i = Article()

i["categories"] = ["one", "two"] i["categories"].append(3) # XXX: should this fail?