mirror of https://github.com/scrapy/scrapy.git
201 lines
5.1 KiB
ReStructuredText
201 lines
5.1 KiB
ReStructuredText
.. _ref-newitem-fields:
|
|
|
|
===========
|
|
Item Fields
|
|
===========
|
|
|
|
.. module:: scrapy.newitem.fields
|
|
|
|
|
|
Field options
|
|
=============
|
|
|
|
Every ``Field`` class constructor accepts these arguments.
|
|
|
|
|
|
``default``
|
|
-----------
|
|
|
|
The default value for the field. See :ref:`topics-newitem-index-defaults`.
|
|
|
|
|
|
Field types
|
|
===========
|
|
|
|
These are the available built-in ``Field`` types. See
|
|
:ref:`ref-newitem-fields-custom-fields` for info on creating your own field types.
|
|
|
|
|
|
``BooleanField``
|
|
----------------
|
|
|
|
.. class:: BooleanField
|
|
|
|
A boolean (true/false) field.
|
|
|
|
|
|
``DateField``
|
|
-------------
|
|
|
|
.. class:: DateField
|
|
|
|
A date, represented in Python by a `datetime.date`_ instance.
|
|
|
|
.. _datetime.date: http://docs.python.org/library/datetime.html#datetime.date
|
|
|
|
|
|
``DateTimeField``
|
|
-----------------
|
|
|
|
.. class:: DateTimeField
|
|
|
|
A date with time, represented in Python by a `datetime.datetime`_ instance.
|
|
|
|
.. _datetime.datetime: http://docs.python.org/library/datetime.html#datetime.datetime
|
|
|
|
|
|
``DecimalField``
|
|
----------------
|
|
|
|
.. class:: DecimalField
|
|
|
|
A fixed-precision decimal number, represented in Python by a `Decimal`_
|
|
instance.
|
|
|
|
.. _Decimal: http://docs.python.org/library/decimal.html#decimal.Decimal
|
|
|
|
|
|
``FloatField``
|
|
--------------
|
|
|
|
.. class:: FloatField
|
|
|
|
A floating-point number represented in Python by a ``float`` instance.
|
|
|
|
|
|
``IntegerField``
|
|
----------------
|
|
|
|
.. class:: IntegerField
|
|
|
|
An integer.
|
|
|
|
|
|
``ListField``
|
|
-------------
|
|
|
|
.. class:: ListField(field)
|
|
|
|
A special field that works like a list of fields of another provided field kind.
|
|
|
|
:param field: The field which the elements of this list must conform to.
|
|
:type field: a :class:`~scrapy.newitem.fields.BaseField` object
|
|
|
|
Usage example::
|
|
|
|
class ExampleItem(Item)
|
|
names = fields.ListField(fields.TextField())
|
|
|
|
item = ExampleItem()
|
|
item['names'] = [u'John', u'Jeena']
|
|
|
|
|
|
``TextField``
|
|
-------------
|
|
|
|
.. class:: TextField
|
|
|
|
A unicode text.
|
|
|
|
This class overrides the following methods from :class:`BaseField`:
|
|
|
|
.. method:: from_unicode_list(unicode_list)
|
|
|
|
Return a unicode string composed by joining the elements of
|
|
``unicode_list`` with spaces.
|
|
|
|
For more info about this method see :class:`BaseField.from_unicode_list`.
|
|
|
|
|
|
``TimeField``
|
|
-------------
|
|
|
|
.. class:: TimeField
|
|
|
|
A time, represented in Python by a `datetime.time`_ instance.
|
|
|
|
.. _datetime.time: http://docs.python.org/library/datetime.html#datetime.time
|
|
|
|
.. _ref-newitem-fields-custom-fields:
|
|
|
|
|
|
Creating custom fields
|
|
======================
|
|
|
|
All field classes are subclasses of the :class:`BaseField` class (see below)
|
|
which you can also subclass to create your own custom fields.
|
|
|
|
You can also subclass a more specific field class, say :class:`DecimalField`,
|
|
to implement a ``PriceField``, for example.
|
|
|
|
|
|
BaseField class
|
|
---------------
|
|
|
|
.. class:: BaseField(default=None)
|
|
|
|
The base class for all fields. It only provides code for handling default
|
|
values, not any particular type. It cannot be used directly either, as its
|
|
:meth:`BaseField.to_python` method is not implemented.
|
|
|
|
The ``default`` argument (if given) must be of the type expected by this
|
|
field, or any type that is accepted by the :meth:`BaseField.to_python`
|
|
method of this field.
|
|
|
|
For example::
|
|
|
|
class NewsItem(Item):
|
|
content = fields.TextField() # correct, no default value
|
|
author = fields.TextField(default=u'Myself") # correct, with default value
|
|
published = fields.DateField(default=23) # wrong default type (will raise TypeError)
|
|
|
|
.. method:: to_python(value)
|
|
|
|
Convert the input value to the type expected by this field and return
|
|
it.
|
|
|
|
For example, :class:`IntegerField` would convert ``'1'`` to ``1``, while
|
|
:class:`DecimalField` would convert ``'1'`` to ``Decimal('1')`` and so
|
|
on.
|
|
|
|
This method is not implemented in the :class:`BaseField` class, so it
|
|
must always be implemented in all its subclasses, in order to be usable.
|
|
|
|
This method should raise ``TypeError`` if the input type is not
|
|
supported, and ``ValueError`` if the input type is support but its value
|
|
is not appropriate (for example, an integer outside a given range).
|
|
|
|
This method must always return object of the expected field type.
|
|
|
|
.. method:: from_unicode_list(unicode_list)
|
|
|
|
Take the input list of unicode strings and convert it to a proper value
|
|
with the type expected by this field. If no proper value if found,
|
|
``None`` is returned instead.
|
|
|
|
The default behaviour is to return the value of the first item of the
|
|
list, passed through the :meth:`to_python` method, or ``None`` if the
|
|
list is empty::
|
|
|
|
return self.to_python(unicode_list[0]) if unicode_list else None
|
|
|
|
This default behaviour is provided because it's the more common one, but
|
|
it's typical for :class:`BaseField` subclasses to override this method,
|
|
such as the :meth:`TextField.from_unicode_list` method.
|
|
|
|
.. method:: get_default()
|
|
|
|
Return the default value for this field, or ``None`` if the field
|
|
doesn't specify any.
|
|
|