Экспорт фидов
Одна из наиболее часто требуемых функций при реализации парсеров — это возможность правильно хранить собранные данные и, довольно часто, это означает создание «экспортного файла» с собранными данными (обычно называемого «экспортным фидом») для использования другими системами.
Scrapy предоставляет эту функциональность прямо из коробки с помощью функции экспорта фидов, которая позволяет создавать фиды с извлеченными элементами, используя несколько форматов сериализации и механизмы хранения.
Форматы сериализации
Для сериализации собранных данных в экспорте фидов используется код экспорта элементов. Данные форматы поддерживаются «из коробки»:
Но вы также можете расширить поддерживаемый формат с помощью параметра FEED_EXPORTERS
.
JSON
Значение для ключа
format
в настройкеFEEDS
:json
Используемый экспортёр:
JsonItemExporter
См. это предупреждение, если вы используете JSON с большими фидами.
Строки JSON
Значение ключа
format
в настройкеFEEDS
:jsonlines
Используемый экспортёр:
JsonLinesItemExporter
CSV
Значение для ключа
format
в настройкеFEEDS
:csv
Используемый экспортер:
CsvItemExporter
Чтобы указать столбцы для экспорта и их порядок, используйте
FEED_EXPORT_FIELDS
. Другие экспортеры фидов также могут использовать эту опцию, но она важна для CSV, потому что в отличие от многих других форматов экспорта CSV использует фиксированный заголовок.
XML
Значение для ключа
format
в настройкеFEEDS
:xml
Используемый экспортёр:
XmlItemExporter
Пикл
Значение для ключа
format
в настройкеFEEDS
:pickle
Используемый экспортёр:
PickleItemExporter
Маршал
Значение ключа
format
в настройкеFEEDS
:marshal
Используемый экспортёр:
MarshalItemExporter
Хранилища
При использовании экспорта фидов вы определяете, где хранить фид, используя один или несколько URI (с помощью параметра FEEDS
). Экспорт фида поддерживает несколько типов серверной части хранилища, которые определяются схемой URI.
Бэкэнды хранилищ поддерживаются «из коробки»:
S3 (требуется botocore)
Облачное хранилище Google (GCS) (требуется google-cloud-storage)
Некоторые серверные части хранилища могут быть недоступны, если требуемые внешние библиотеки недоступны. Например, серверная часть S3 доступна, только если установлена библиотека botocore.
Параметры URI хранилища
URI хранилища также может содержать параметры, которые заменяются при создании фида. Данные параметры следующие:
%(time)s
— заменяется меткой времени при создании фида%(name)s
— заменяется именем паука
Любой другой именованный параметр заменяется одноименным атрибутом паука. Например, %(site_id)s
будет заменен атрибутом spider.site_id
в момент создания фида.
Вот несколько примеров для иллюстрации:
Храните на FTP, используя один каталог для каждого паука:
ftp://user:[email protected]/scraping/feeds/%(name)s/%(time)s.json
Храните в S3, используя один каталог для каждого паука:
s3://mybucket/scraping/feeds/%(name)s/%(time)s.json
Примечание
Аргументы паука становятся атрибутами паука, поэтому их также можно использовать в качестве параметров URI хранилища.
Бэкэнды хранения
Локальная файловая система
Фиды хранятся в локальной файловой системе.
Схема URI:
file
Пример URI:
file:///tmp/export.csv
Требуемые внешние библиотеки: нет
Обратите внимание, что для хранилища локальной файловой системы (только) вы можете пропустить схему, если укажете абсолютный путь, например /tmp/export.csv
. Однако это работает только в системах Unix.
FTP
Фиды хранятся на FTP-сервере.
Схема URI:
ftp
Пример URI:
ftp://user:[email protected]/path/to/export.csv
Требуемые внешние библиотеки: нет
FTP поддерживает два разных режима подключения: активный или пассивный. Scrapy по умолчанию использует пассивный режим подключения. Чтобы вместо этого использовать активный режим подключения, устанавливает для параметра FEED_STORAGE_FTP_ACTIVE
значение True
.
Данный бэкэнд хранилища использует задержку доставки файла.
S3
Фиды хранятся на Amazon S3.
Схема URI:
s3
Примеры URI:
s3://mybucket/path/to/export.csv
s3://aws_key:aws_secret@mybucket/path/to/export.csv
Необходимые внешние библиотеки: botocore >= 1.4.87
Учётные данные AWS могут быть переданы как пользователь/пароль в URI, или они могут быть переданы через следующие настройки:
AWS_SESSION_TOKEN
(требуется только для временной безопасности реквизитов для входа)
Вы также можете определить настраиваемый ACL и настраиваемую конечную точку для экспортированных фидов, используя данный параметр:
Данный бэкэнд хранилища использует задержку доставки файла.
Облачное хранилище Google (GCS)
Добавлено в версии 2.3.
Фиды хранятся на Google Cloud Storage.
Схема URI:
gs
Примеры URI:
gs://mybucket/path/to/export.csv
Необходимые внешние библиотеки: google-cloud-storage.
Дополнительные сведения об аутентификации см. в документации Google Cloud .
Вы можете установить Идентификатор проекта и Список контроля доступа (ACL) с помощью следующих настроек:
Данный бэкэнд хранилища использует задержку доставки файла.
Стандартный вывод
Фиды записываются в стандартный вывод процесса Scrapy.
Схема URI:
stdout
Пример URI:
stdout:
Требуемые внешние библиотеки: нет
Отложенная доставка файла
Как указано выше, некоторые из описанных механизмов хранения используют отложенную доставку файлов.
Данные серверные части хранилища не загружают элементы в URI фида, поскольку данные элементы сканируются. Вместо этого Scrapy записывает элементы во временный локальный файл, и только после того, как все содержимое файла будет записано (т. е. в конце сканирования), данный файл будет загружен в URI фида.
Если вы хотите, чтобы доставка элементов началась раньше при использовании одного из данных бэкэндов хранилища, используйте FEED_EXPORT_BATCH_ITEM_COUNT
, чтобы разделить выходные элементы на несколько файлов с указанным максимальным количеством элементов на файл. Таким образом, как только в файле будет достигнуто максимальное количество элементов, данный файл будет доставлен в URI фида, что позволит начать доставку элемента до окончания сканирования.
Фильтрация элементов
Добавлено в версии VERSION.
Вы можете фильтровать элементы, которые хотите разрешить для определенного фида, используя параметр item_classes
в опции фидов. В фид будут добавлены только элементы указанных типов.
Параметр item_classes
реализуется классом ItemFilter
, который является значением по умолчанию для item_filter
опция фида.
Вы можете создать свой собственный класс фильтрации, реализовав метод accepts
ItemFilter
и взяв feed_options
в качестве аргумента.
Например:
class MyCustomFilter:
def __init__(self, feed_options):
self.feed_options = feed_options
def accepts(self, item):
if "field1" in item and item["field1"] == "expected_data":
return True
return False
Вы можете назначить свой собственный класс фильтрации item_filter
опции фида. См. примеры в FEEDS
.
ItemFilter
Постобработка
Добавлено в версии VERSION.
Scrapy предоставляет возможность активировать плагины для постобработки фидов перед их экспортом в хранилища фидов. Помимо использования встроенные плагины, вы можете создать свой собственный плагины.
Данные плагины можно активировать с помощью опции фида postprocessing
. Опция должна быть передана списком плагинов пост-обработки в том порядке, в котором вы хотите, чтобы фид обрабатывался. Данные плагины могут быть объявлены либо как строка импорта, либо с импортированным классом плагина. Параметры в плагины могут быть переданы через параметры фида. См. примеры в опции фида.
Встроенные плагины
Пользовательские плагины
Каждый плагин — это класс, который должен реализовывать следующие методы:
- __init__(self, file, feed_options)
Инициализировать плагин.
- Параметры
file – файловый объект, в котором реализованы как минимум методы write, tell и close
feed_options (
dict
) – фид-специфичные опции
- write(self, data)
Обработать и записать данные (
bytes
илиmemoryview
) в целевой файл плагина. Он должен возвращать количество записанных байтов.
- close(self)
Закрыть целевой файловый объект.
Чтобы передать параметр вашему плагину, используйте опции фида. Затем вы можете получить доступ к этим параметрам из метода __init__
вашего плагина.
Настройки
Это параметры, используемые для настройки экспорта фидов:
FEEDS
(обязательно)
FEEDS
Добавлено в версии 2.1.
По умолчанию: {}
Словарь, в котором каждый ключ является URI фида (или объектом pathlib.Path
), а каждое значение представляет собой вложенный словарь, содержащий параметры конфигурации для конкретного фида.
Данный параметр необходим для включения функции экспорта фидов.
См. Бэкэнды хранения для поддерживаемых схем URI.
Например:
{
'items.json': {
'format': 'json',
'encoding': 'utf8',
'store_empty': False,
'item_classes': [MyItemClass1, 'myproject.items.MyItemClass2'],
'fields': None,
'indent': 4,
'item_export_kwargs': {
'export_empty_fields': True,
},
},
'/home/user/documents/items.xml': {
'format': 'xml',
'fields': ['name', 'price'],
'item_filter': MyCustomFilter1,
'encoding': 'latin1',
'indent': 8,
},
pathlib.Path('items.csv.gz'): {
'format': 'csv',
'fields': ['price', 'name'],
'item_filter': 'myproject.filters.MyCustomFilter2',
'postprocessing': [MyPlugin1, 'scrapy.extensions.postprocessing.GzipPlugin'],
'gzip_compresslevel': 5,
},
}
Ниже приведён список принятых ключей и параметр, который используется в качестве резервного значения, если данный ключ не предоставлен для определенного определения фида:
format
: модель формата сериализации.Данный параметр является обязательным, нет резервного значения.
batch_item_count
: возвращается кFEED_EXPORT_BATCH_ITEM_COUNT
.Добавлено в версии 2.3.0.
encoding
: возвращается кFEED_EXPORT_ENCODING
.fields
: возвращается кFEED_EXPORT_FIELDS
.item_classes
: список классов элемента для экспорта.Если не определено или пусто, экспортируются все элементы.
Добавлено в версии VERSION.
item_filter
: класс фильтра для фильтрации элементов для экспорта.По умолчанию используется
ItemFilter
.Добавлено в версии VERSION.
indent
: возвращается кFEED_EXPORT_INDENT
.item_export_kwargs
:dict
с ключевыми аргументами для соответствующего класса экспортера элементов.Добавлено в версии 2.4.0.
overwrite
: следует ли перезаписать файл, если он уже существует (True
), или добавить к его содержимому (False
).Значение по умолчанию зависит от серверной части хранилища:
Локальная файловая система:
False
FTP:
True
Примечание
Некоторые FTP-серверы могут не поддерживать добавление к файлам (команда FTP
APPE
).S3:
True
(добавление не поддерживается)Стандартный вывод:
False
(перезапись не поддерживается)
Добавлено в версии 2.4.0.
store_empty
: возвращается кFEED_STORE_EMPTY
.uri_params
: возвращается кFEED_URI_PARAMS
.postprocessing
: список плагинов для использования при постобработке.Плагины будут использоваться в порядке переданного списка.
Добавлено в версии VERSION.
FEED_EXPORT_ENCODING
По умолчанию: None
Кодировка, которая будет использоваться для фида.
Если не задано или установлено значение None
(по умолчанию), он использует UTF-8 для всего, кроме вывода JSON, который использует безопасную числовую кодировку (последовательности \uXXXX
) по историческим причинам.
Используйте utf-8
, если вы хотите использовать UTF-8 и для JSON.
FEED_EXPORT_FIELDS
По умолчанию: None
Список полей для экспорта (необязательно). Пример: FEED_EXPORT_FIELDS = ["foo", "bar", "baz"]
.
Используйте опцию FEED_EXPORT_FIELDS, чтобы определить поля для экспорта и их порядок.
Когда FEED_EXPORT_FIELDS пуст или None (по умолчанию), Scrapy использует поля, определённые в объектах элемента, полученные вашим пауком.
Если экспортёру требуется фиксированный множество полей (это случай для формата экспорта CSV) и FEED_EXPORT_FIELDS пусто или None, то Scrapy пытается вывести имена полей из экспортированных данных — в настоящее время он использует имена полей из первого элемента.
FEED_EXPORT_INDENT
По умолчанию: 0
Количество пробелов, используемых для отступа вывода на каждом уровне. Если FEED_EXPORT_INDENT
— неотрицательное целое число, тогда элементы массива и члены объекта будут красиво напечатаны с этим уровнем отступа. При уровне отступа 0
(по умолчанию) или отрицательном каждый элемент помещается в новую строку. None
выбирает наиболее компактное представление.
В настоящее время реализовано только в JsonItemExporter
и XmlItemExporter
, т. е. при экспорте в .json
или .xml
.
FEED_STORE_EMPTY
По умолчанию: False
Следует ли экспортировать пустые фиды (т. е. фиды без элементов).
FEED_STORAGES
По умолчанию: {}
Dict, содержащий дополнительные серверные части хранилища фидов, поддерживаемые вашим проектом. Ключи — это схемы URI, а значения — это пути к классам хранения.
FEED_STORAGE_FTP_ACTIVE
По умолчанию: False
Следует ли использовать режим активного подключения при экспорте фидов на FTP-сервер (True
) или вместо этого использовать режим пассивного подключения (False
, по умолчанию).
Для получения информации о режимах FTP-соединения см. В чём разница между активным и пассивным FTP?.
FEED_STORAGE_S3_ACL
По умолчанию: ''
(пустая строка)
Строка, содержащая настраиваемый ACL для фидов, экспортированных в Amazon S3 вашим проектом.
Полный список доступных значений см. в разделе Стандартный ACL в документации Amazon S3.
FEED_STORAGES_BASE
Дефолт:
{
'': 'scrapy.extensions.feedexport.FileFeedStorage',
'file': 'scrapy.extensions.feedexport.FileFeedStorage',
'stdout': 'scrapy.extensions.feedexport.StdoutFeedStorage',
's3': 'scrapy.extensions.feedexport.S3FeedStorage',
'ftp': 'scrapy.extensions.feedexport.FTPFeedStorage',
}
Dict, содержащий встроенные серверные модули хранения фидов, поддерживаемые Scrapy. Вы можете отключить любой из данных бэкэндов, назначив None
их схеме URI в FEED_STORAGES
. Например, чтобы отключить встроенное серверное хранилище FTP (без замены), поместите его в свой settings.py
:
FEED_STORAGES = {
'ftp': None,
}
FEED_EXPORTERS
По умолчанию: {}
Словарь, содержащий дополнительные экспортеры, поддерживаемых вашим проектом. Ключи — это форматы сериализации, а значения — пути к классам экспортера элемента.
FEED_EXPORTERS_BASE
Дефолт:
{
'json': 'scrapy.exporters.JsonItemExporter',
'jsonlines': 'scrapy.exporters.JsonLinesItemExporter',
'jl': 'scrapy.exporters.JsonLinesItemExporter',
'csv': 'scrapy.exporters.CsvItemExporter',
'xml': 'scrapy.exporters.XmlItemExporter',
'marshal': 'scrapy.exporters.MarshalItemExporter',
'pickle': 'scrapy.exporters.PickleItemExporter',
}
Словарь, содержащий встроенные экспортеры фидов, поддерживаемые Scrapy. Вы можете отключить любой из данных экспортёров, назначив None
их формату сериализации в FEED_EXPORTERS
. Например, чтобы отключить встроенный экспортёр CSV (без замены), поместите его в свой settings.py
:
FEED_EXPORTERS = {
'csv': None,
}
FEED_EXPORT_BATCH_ITEM_COUNT
Добавлено в версии 2.3.0.
По умолчанию: 0
Если присвоено целое число больше 0
, Scrapy генерирует несколько выходных файлов, сохраняя до указанного количества элементов в каждом выходном файле.
При создании нескольких выходных файлов вы должны использовать по крайней мере один из следующих заполнителей в URI фида, чтобы указать, как создаются разные имена выходных файлов:
%(batch_time)s
— заменяется меткой времени при создании фида (например,2020-03-28T14-45-08.237134
)%(batch_id)d
— заменяется порядковым номером партии, отсчитываемым от 1.Используйте форматирование строки в стиле printf, чтобы изменить числовой формат. Например, чтобы сделать идентификатор партии 5-значным числом путём введения ведущих нулей по мере необходимости, используйте
%(batch_id)05d
(например,3
становится00003
,123
становится00123
).
Например, если ваши настройки включают:
FEED_EXPORT_BATCH_ITEM_COUNT = 100
И ваша командная строка crawl
:
scrapy crawl spidername -o "dirname/%(batch_id)d-filename%(batch_time)s.json"
Командная строка выше может создать дерево каталогов, например:
->projectname
-->dirname
--->1-filename2020-03-28T14-45-08.237134.json
--->2-filename2020-03-28T14-45-09.148903.json
--->3-filename2020-03-28T14-45-10.046092.json
Где первый и второй файлы содержат ровно 100 элементов. Последний содержит 100 или меньше элементов.
FEED_URI_PARAMS
По умолчанию: None
Строка с путём импорта функции для установки параметров, применяемых с форматирование строки в стиле printf к URI фида.
Сигнатура функции должна быть следующей:
- scrapy.extensions.feedexport.uri_params(params, spider)
Возвращает
dict
пар «ключ-значение» для применения к URI фида с помощью форматирования строки в стиле printf.- Параметры
params (dict) – пары «ключ-значение» по умолчанию в частности: —
batch_id
: идентификатор пакета файлов. См.FEED_EXPORT_BATCH_ITEM_COUNT
. ЕслиFEED_EXPORT_BATCH_ITEM_COUNT
— это0
,batch_id
всегда будет1
. .. versionadded :: 2.3.0 —batch_time
: Дата и время UTC в формате ISO с заменой:
на-
. См.FEED_EXPORT_BATCH_ITEM_COUNT
. .. versionadded :: 2.3.0 —time
:batch_time
, с микросекундами, установленными на0
.spider (scrapy.Spider) – источник паука элементов фида
Например, чтобы включить name
исходного паука в URI фида:
Определяет следующую функцию где-нибудь в своём проекте:
# myproject/utils.py def uri_params(params, spider): return {**params, 'spider_name': spider.name}
Укажите
FEED_URI_PARAMS
на эту функцию в своих настройках:# myproject/settings.py FEED_URI_PARAMS = 'myproject.utils.uri_params'
Используйте
%(spider_name)s
в URI вашего фида:scrapy crawl <spider_name> -o "%(spider_name)s.jl"