Экспорт фидов

Одна из наиболее часто требуемых функций при реализации парсеров — это возможность правильно хранить собранные данные и, довольно часто, это означает создание «экспортного файла» с собранными данными (обычно называемого «экспортным фидом») для использования другими системами.

Scrapy предоставляет эту функциональность прямо из коробки с помощью функции экспорта фидов, которая позволяет создавать фиды с извлеченными элементами, используя несколько форматов сериализации и механизмы хранения.

Форматы сериализации

Для сериализации собранных данных в экспорте фидов используется код экспорта элементов. Данные форматы поддерживаются «из коробки»:

Но вы также можете расширить поддерживаемый формат с помощью параметра FEED_EXPORTERS.

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.

Параметры URI хранилища

URI хранилища также может содержать параметры, которые заменяются при создании фида. Данные параметры следующие:

  • %(time)s — заменяется меткой времени при создании фида

  • %(name)s — заменяется именем паука

Любой другой именованный параметр заменяется одноименным атрибутом паука. Например, %(site_id)s будет заменен атрибутом spider.site_id в момент создания фида.

Вот несколько примеров для иллюстрации:

  • Храните на FTP, используя один каталог для каждого паука:

    • ftp://user:password@ftp.example.com/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:pass@ftp.example.com/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, или они могут быть переданы через следующие настройки:

Вы также можете определить настраиваемый 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

Добавлено в версии 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).

    Значение по умолчанию зависит от серверной части хранилища:

    Добавлено в версии 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 фида:

  1. Определяет следующую функцию где-нибудь в своём проекте:

    # myproject/utils.py
    def uri_params(params, spider):
        return {**params, 'spider_name': spider.name}
    
  2. Укажите FEED_URI_PARAMS на эту функцию в своих настройках:

    # myproject/settings.py
    FEED_URI_PARAMS = 'myproject.utils.uri_params'
    
  3. Используйте %(spider_name)s в URI вашего фида:

    scrapy crawl <spider_name> -o "%(spider_name)s.jl"