命令行工具(Command line tools)

0.10 新版功能.

Scrapy是通过 scrapy 命令行工具进行控制的。这里我们称之为 “Scrapy tool” 以用来和子命令进行区分。对于子命令，我们称为 “command” 或者 “Scrapy commands”。

Scrapy tool 针对不同的目的提供了多个命令，每个命令支持不同的参数和选项。

(为了遵循更独立的 scrapyd-deploy, scrapy deploy 命令在1.0版本中被移除,请参考 部署您的项目 .)

调整设置

Scrapy将会在以下路径中寻找记录了配置参数的 scrapy.cfg 文件,该文件以ini的方式记录:

  • /etc/scrapy.cfg 或 c:\scrapy\scrapy.cfg (系统层面),
  • ~/.config/scrapy.cfg ($XDG_CONFIG_HOME) 及 ~/.scrapy.cfg ($HOME)作为全局(用户层面)设置, 以及
  • 在scrapy项目根路径下的 scrapy.cfg (参考之后的章节).
    从这些文件中读取到的设置按照以下的顺序合并:用户定义的值具有比系统级别的默认值更高的优先级,而项目定义的设置则会覆盖其他.

Scrapy也会读取并通过环境变量来设置.目前支持的有:

默认的Scrapy项目结构

在开始对命令行工具以及子命令的探索前，让我们首先了解一下Scrapy的项目的目录结构。

虽然可以被修改，但所有的Scrapy项目默认有类似于下边的文件结构:

  1. scrapy.cfg
  2. myproject/
  3.     __init__.py
  4.     items.py
  5.     pipelines.py
  6.     settings.py
  7.     spiders/
  8.         __init__.py
  9.         spider1.py
  10.         spider2.py
  11.         ...

scrapy.cfg 存放的目录被认为是 项目的根目录 。该文件中包含python模块名的字段定义了项目的设置。例如:

  1. [settings]
  2. default = myproject.settings

使用 scrapy 工具

您可以以无参数的方式启动Scrapy工具。该命令将会给出一些使用帮助以及可用的命令:

  1. Scrapy X.Y - no active project
  2.  
  3. Usage:
  4.   scrapy <command> [options] [args]
  5.  
  6. Available commands:
  7.   crawl         Run a spider
  8.   fetch         Fetch a URL using the Scrapy downloader
  9. [...]

如果您在Scrapy项目中运行，当前激活的项目将会显示在输出的第一行。上面的输出就是响应的例子。如果您在一个项目中运行命令将会得到类似的输出:

  1. Scrapy X.Y - project: myproject
  2.  
  3. Usage:
  4.   scrapy <command> [options] [args]
  5.  
  6. [...]

创建项目

一般来说，使用 scrapy 工具的第一件事就是创建您的Scrapy项目:

  1. scrapy startproject myproject

该命令将会在 myproject 目录中创建一个Scrapy项目。

接下来，进入到项目目录中:

  1. cd myproject

这时候您就可以使用 scrapy 命令来管理和控制您的项目了。

控制项目

您可以在您的项目中使用 scrapy 工具来对其进行控制和管理。

比如，创建一个新的spider:

  1. scrapy genspider mydomain mydomain.com

有些Scrapy命令(比如 crawl)要求必须在Scrapy项目中运行。您可以通过下边的 commands reference来了解哪些命令需要在项目中运行，哪些不用。

另外要注意，有些命令在项目里运行时的效果有些许区别。以fetch命令为例，如果被爬取的url与某个特定spider相关联，则该命令将会使用spider的动作(spider-overridden behaviours)。(比如spider指定的 user_agent)。该表现是有意而为之的。一般来说， fetch 命令就是用来测试检查spider是如何下载页面。

可用的工具命令(tool commands)

该章节提供了可用的内置命令的列表。每个命令都提供了描述以及一些使用例子。您总是可以通过运行命令来获取关于每个命令的详细内容:

  1. scrapy <command> -h

您也可以查看所有可用的命令:

  1. scrapy -h

Scrapy提供了两种类型的命令。一种必须在Scrapy项目中运行(针对项目(Project-specific)的命令)，另外一种则不需要(全局命令)。全局命令在项目中运行时的表现可能会与在非项目中运行有些许差别(因为可能会使用项目的设定)。

全局命令:

startproject

  • 语法: scrapy startproject <project_name>
  • 是否需要项目: no
    在 project_name 文件夹下创建一个名为 project_name 的Scrapy项目。

例子:

  1. $ scrapy startproject myproject

genspider

  • 语法: scrapy genspider [-t template] <name> <domain>
  • 是否需要项目: yes
    在当前项目中创建spider。

这仅仅是创建spider的一种快捷方法。该方法可以使用提前定义好的模板来生成spider。您也可以自己创建spider的源码文件。

例子:

  1. $ scrapy genspider -l
  2. Available templates:
  3.   basic
  4.   crawl
  5.   csvfeed
  6.   xmlfeed
  7.  
  8. $ scrapy genspider -d basic
  9. import scrapy
  10.  
  11. class $classname(scrapy.Spider):
  12.     name = "$name"
  13.     allowed_domains = ["$domain"]
  14.     start_urls = (
  15.         'http://www.$domain/',
  16.         )
  17.  
  18.     def parse(self, response):
  19.         pass
  20.  
  21. $ scrapy genspider -t basic example example.com
  22. Created spider 'example' using template 'basic' in module:
  23.   mybot.spiders.example

crawl

  • 语法: scrapy crawl <spider>
  • 是否需要项目: yes
    使用spider进行爬取。

例子:

  1. $ scrapy crawl myspider
  2. [ ... myspider starts crawling ... ]

check

  • 语法: scrapy check [-l] <spider>
  • 是否需要项目: yes
    运行contract检查。

例子:

  1. $ scrapy check -l
  2. first_spider
  3.   * parse
  4.   * parse_item
  5. second_spider
  6.   * parse
  7.   * parse_item
  8.  
  9. $ scrapy check
  10. [FAILED] first_spider:parse_item
  11. >>> 'RetailPricex' field is missing
  12.  
  13. [FAILED] first_spider:parse
  14. >>> Returned 92 requests, expected 0..4

list

  • 语法: scrapy list
  • 是否需要项目: yes
    列出当前项目中所有可用的spider。每行输出一个spider。

使用例子:

  1. $ scrapy list
  2. spider1
  3. spider2

edit

  • 语法: scrapy edit <spider>
  • 是否需要项目: yes
    使用 EDITOR 中设定的编辑器编辑给定的spider

该命令仅仅是提供一个快捷方式。开发者可以自由选择其他工具或者IDE来编写调试spider。

例子:

  1. $ scrapy edit spider1

fetch

  • 语法: scrapy fetch <url>
  • 是否需要项目: no
    使用Scrapy下载器(downloader)下载给定的URL，并将获取到的内容送到标准输出。

该命令以spider下载页面的方式获取页面。例如，如果spider有 USER_AGENT 属性修改了 User Agent，该命令将会使用该属性。

因此，您可以使用该命令来查看spider如何获取某个特定页面。

该命令如果非项目中运行则会使用默认Scrapy downloader设定。

例子:

  1. $ scrapy fetch --nolog http://www.example.com/some/page.html
  2. [ ... html content here ... ]
  3.  
  4. $ scrapy fetch --nolog --headers http://www.example.com/
  5. {'Accept-Ranges': ['bytes'],
  6.  'Age': ['1263   '],
  7.  'Connection': ['close     '],
  8.  'Content-Length': ['596'],
  9.  'Content-Type': ['text/html; charset=UTF-8'],
  10.  'Date': ['Wed, 18 Aug 2010 23:59:46 GMT'],
  11.  'Etag': ['"573c1-254-48c9c87349680"'],
  12.  'Last-Modified': ['Fri, 30 Jul 2010 15:30:18 GMT'],
  13.  'Server': ['Apache/2.2.3 (CentOS)']}

view

  • 语法: scrapy view <url>
  • 是否需要项目: no
    在浏览器中打开给定的URL，并以Scrapy spider获取到的形式展现。有些时候spider获取到的页面和普通用户看到的并不相同。因此该命令可以用来检查spider所获取到的页面，并确认这是您所期望的。

例子:

  1. $ scrapy view http://www.example.com/some/page.html
  2. [ ... browser starts ... ]

shell

  • 语法: scrapy shell [url]
  • 是否需要项目: no
    以给定的URL(如果给出)或者空(没有给出URL)启动Scrapy shell。查看 Scrapy终端(Scrapy shell) 获取更多信息。

例子:

  1. $ scrapy shell http://www.example.com/some/page.html
  2. [ ... scrapy shell starts ... ]

parse

  • 语法: scrapy parse <url> [options]
  • 是否需要项目: yes
    获取给定的URL并使用相应的spider分析处理。如果您提供 —callback 选项，则使用spider的该方法处理，否则使用 parse 。

支持的选项:

  • —spider=SPIDER: 跳过自动检测spider并强制使用特定的spider
  • —a NAME=VALUE: 设置spider的参数(可能被重复)
  • —callback or -c: spider中用于解析返回(response)的回调函数
  • —pipelines: 在pipeline中处理item
  • —rules or -r: 使用 CrawlSpider 规则来发现用来解析返回(response)的回调函数
  • —noitems: 不显示爬取到的item
  • —nolinks: 不显示提取到的链接
  • —nocolour: 避免使用pygments对输出着色
  • —depth or -d: 指定跟进链接请求的层次数(默认: 1)
  • —verbose or -v: 显示每个请求的详细信息
    例子:
  1. $ scrapy parse http://www.example.com/ -c parse_item
  2. [ ... scrapy log lines crawling example.com spider ... ]
  3.  
  4. >>> STATUS DEPTH LEVEL 1 <<<
  5. # Scraped Items  ------------------------------------------------------------
  6. [{'name': u'Example item',
  7.  'category': u'Furniture',
  8.  'length': u'12 cm'}]
  9.  
  10. # Requests  -----------------------------------------------------------------
  11. []

settings

  • 语法: scrapy settings [options]
  • 是否需要项目: no
    获取Scrapy的设定

在项目中运行时，该命令将会输出项目的设定值，否则输出Scrapy默认设定。

例子:

  1. $ scrapy settings --get BOT_NAME
  2. scrapybot
  3. $ scrapy settings --get DOWNLOAD_DELAY
  4. 0

runspider

  • 语法: scrapy runspider <spider_file.py>
  • 是否需要项目: no
    在未创建项目的情况下，运行一个编写在Python文件中的spider。

例子:

  1. $ scrapy runspider myspider.py
  2. [ ... spider starts crawling ... ]

version

  • 语法: scrapy version [-v]
  • 是否需要项目: no
    输出Scrapy版本。配合 -v 运行时，该命令同时输出Python, Twisted以及平台的信息，方便bug提交。

bench

0.17 新版功能.

  • 语法: scrapy bench
  • 是否需要项目: no
    运行benchmark测试。 Benchmarking 。

自定义项目命令

您也可以通过 COMMANDS_MODULE 来添加您自己的项目命令。您可以以 scrapy/commands 中Scrapy commands为例来了解如何实现您的命令。

COMMANDS_MODULE

Default: '' (empty string)

用于查找添加自定义Scrapy命令的模块。

例子:

  1. COMMANDS_MODULE = 'mybot.commands'

通过setup.py entry point来注册命令

注解

这是个实验性的特性,请谨慎使用.

您可以通过在库文件 setup.py 的entry point中添加scrapy.commands 部分来添加Scrapy命令.

以下是添加 my_command 命令的example:

  1. from setuptools import setup, find_packages
  2.  
  3. setup(name='scrapy-mymodule',
  4.   entry_points={
  5.     'scrapy.commands': [
  6.       'my_command=my_scrapy_module.commands:MyCommand',
  7.     ],
  8.   },
  9.  )