Contributing to Scrapy¶
Double check that you are reading the most recent version of this document at https://docs.scrapy.org/en/master/contributing.html
There are many ways to contribute to Scrapy. Here are some of them:
Blog about Scrapy. Tell the world how you’re using Scrapy. This will help newcomers with more examples and will help the Scrapy project to increase its visibility.
Join the Scrapy subreddit and share your ideas on how to improve Scrapy. We’re always open to suggestions.
Answer Scrapy questions at Stack Overflow.
Please report security issues only to email@example.com. This is a private list only open to trusted Scrapy developers, and its archives are not public.
Well-written bug reports are very helpful, so keep in mind the following guidelines when you’re going to report a new bug.
check the FAQ first to see if your issue is addressed in a well-known question
if you have a general question about Scrapy usage, please ask it at Stack Overflow (use «scrapy» tag).
check the open issues to see if the issue has already been reported. If it has, don’t dismiss the report, but check the ticket history and comments. If you have additional useful information, please leave a comment, or consider sending a pull request with a fix.
write complete, reproducible, specific bug reports. The smaller the test case, the better. Remember that other developers won’t have your project to reproduce the bug, so please include all relevant files required to reproduce it. See for example StackOverflow’s guide on creating a Minimal, Complete, and Verifiable example exhibiting the issue.
the most awesome way to provide a complete reproducible example is to send a pull request which adds a failing test case to the Scrapy testing suite (see Submitting patches). This is helpful even if you don’t have an intention to fix the issue yourselves.
include the output of
scrapy version -vso developers working on your bug know exactly which version and platform it occurred on, which is often very helpful for reproducing it, or knowing if it was already fixed.
The better a patch is written, the higher the chances that it’ll get accepted and the sooner it will be merged.
Well-written patches should:
contain the minimum amount of code required for the specific change. Small patches are easier to review and merge. So, if you’re doing more than one change (or bug fix), please consider submitting one patch per change. Do not collapse multiple changes into a single patch. For big changes consider using a patch queue.
pass all unit-tests. See Running tests below.
include one (or more) test cases that check the bug fixed or the new functionality added. See Writing tests below.
if you’re adding or changing a public (documented) API, please include the documentation changes in the same patch. See Documentation policies below.
if you’re adding a private API, please add a regular expression to the
docs/conf.pyto exclude the new private API from documentation coverage checks.
To see if your private API is skipped properly, generate a documentation coverage report as follows:
tox -e docs-coverage
The best way to submit a patch is to issue a pull request on GitHub, optionally creating a new issue first.
Remember to explain what was fixed or the new functionality (what it is, why it’s needed, etc). The more info you include, the easier will be for core developers to understand and accept your patch.
You can also discuss the new functionality (or bug fix) before creating the patch, but it’s always good to have a patch ready to illustrate your arguments and show that you have put some additional thought into the subject. A good starting point is to send a pull request on GitHub. It can be simple enough to illustrate your idea, and leave documentation/tests for later, after the idea has been validated and proven useful. Alternatively, you can start a conversation in the Scrapy subreddit to discuss your idea first.
Sometimes there is an existing pull request for the problem you’d like to solve, which is stalled for some reason. Often the pull request is in a right direction, but changes are requested by Scrapy maintainers, and the original pull request author hasn’t had time to address them. In this case consider picking up this pull request: open a new pull request with all commits from the original pull request, as well as additional changes to address the raised issues. Doing so helps a lot; it is not considered rude as soon as the original author is acknowledged by keeping his/her commits.
You can pull an existing pull request to a local branch
git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE
(replace “upstream” with a remote name for scrapy repository,
$PR_NUMBER with an ID of the pull request, and
with a name of the branch you want to create locally).
See also: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally#modifying-an-inactive-pull-request-locally.
When writing GitHub pull requests, try to keep titles short but descriptive. E.g. For bug #411: «Scrapy hangs if an exception raises in start_requests» prefer «Fix hanging when exception occurs in start_requests (#411)» instead of «Fix for #411». Complete titles make it easy to skim through the issue tracker.
Finally, try to keep aesthetic changes (PEP 8 compliance, unused imports removal, etc) in separate commits from functional changes. This will make pull requests easier to review and more likely to get merged.
Please follow these coding conventions when writing code for inclusion in Scrapy:
Unless otherwise specified, follow PEP 8.
It’s OK to use lines longer than 79 chars if it improves the code readability.
Don’t put your name in the code you contribute; git provides enough metadata to identify author of the code. See https://help.github.com/en/github/using-git/setting-your-username-in-git for setup instructions.
For reference documentation of API members (classes, methods, etc.) use
docstrings and make sure that the Sphinx documentation uses the
autodoc extension to pull the docstrings. API reference
documentation should follow docstring conventions (PEP 257) and be
IDE-friendly: short, to the point, and it may provide short examples.
Other types of documentation, such as tutorials or topics, should be covered in
files within the
docs/ directory. This includes documentation that is
specific to an API member, but goes beyond API reference documentation.
In any case, if something is covered in a docstring, use the
autodoc extension to pull the docstring into the
documentation instead of duplicating the docstring in files within the
To run all tests:
To run a specific test (say
tox -- tests/test_loader.py
To run the tests on a specific tox environment, use
-e <name> with an environment name from
tox.ini. For example, to run
the tests with Python 3.6 use:
tox -e py36
You can also specify a comma-separated list of environments, and use tox’s parallel mode to run the tests on multiple environments in parallel:
tox -e py36,py38 -p auto
To pass command-line options to pytest, add them after
-- in your call to tox. Using
-- overrides the
default positional arguments defined in
tox.ini, so you must include those
default positional arguments (
scrapy tests) after
-- as well:
tox -- scrapy tests -x # stop after first failure
tox -e py36 -- scrapy tests -n auto
To see coverage report install coverage
pip install coverage) and run:
see output of
coverage --help for more options like html or xml report.
All functionality (including new features and bug fixes) must include a test case to check that it works as expected, so please include tests for your patches if you want them to get accepted sooner.
Scrapy uses unit-tests, which are located in the tests/ directory. Their module name typically resembles the full path of the module they’re testing. For example, the item loaders code is in:
And their unit-tests are in:
You can use the following command to update the contents of the
docs/locales/ folder, which contains Gettext catalog template files
.pot) and message catalog files (
tox -e docs-i18n
Translators can transform catalog template files into message catalog files
.po) mapping source English messages to their translations in a different
language. Those message catalog files must be placed into
To build the documentation in a language other than English, using the compiled
message catalog files from the
locales/ folder, use
-D language=<language>, for example:
tox -e docs -- -D language=ru
When translating message catalog files, you will find reStructuredText syntax used, and you must be careful not to break the syntax or references when translating. Please, get familiar with reStructuredText syntax before you start working on a translation.
These are some common pieces of reStructuredText syntax that you may find in English messages, and guidelines for handling them in your translations:
word_cannot be translated. If you need to translate
word, send a pull request to transform it into
`word <word>`__, or open an issue requesting such a change.
`multiple words`_cannot be translated. If you need to translate
multiple words, send a pull request to transform it into
`multiple words <multiple words>`__, or open an issue requesting such a change.
`text <target>`_allows translating
targetis a URL, it may be translated as well.
If target is not a URL, but you would like to change the target URL to a localized equivalent URL, send a pull request to replace
targetwith the actual URL, or open an issue requesting such a change.
:ref:`id`will be automatically replaced by the translation of the title of the referenced page or section.
:ref:`text <id>`allows translating