@handle_urls() with item return type

[BurnzZ]

Addresses approach 1 of https://github.com/scrapinghub/web-poet/issues/77

TODO:

• [x] Documentation overhaul
  • [x] docstrings
  • [x] tutorials
    • [x] overriding to_return item using @handle_urls
• [x] Consider renaming OverrideRule to something else (candidate: ApplyRule)
• [x] ~Consider renaming OverrideRule.instead_of to something else~ (hopefully to match the @handle_urls parameter). Or the other way around: renaming @handle_urls's overrides parameter.
• [x] Consider renaming handle_urls's data_type to something else (ensure that it's consistent with OverrideRule as well)
• [x] Consistent use of the term "item type" vs "data type" vs "item class" in docstrings, variables, and parameters.
• [x] ~Handling the case of not needing all fields (recommendation for frameworks like scrapy-poet)~

[codecov[bot]]

Codecov Report

Merging #84 (383b4f7) into master (551aa3b) will increase coverage by 0.00%. The diff coverage is 100.00%.

:exclamation: Current head 383b4f7 differs from pull request most recent head 2c570e2. Consider uploading reports for the commit 2c570e2 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #84   +/-   ##
=======================================
  Coverage   99.81%   99.82%           
=======================================
  Files          17       18    +1     
  Lines         553      583   +30     
=======================================
+ Hits          552      582   +30     
  Misses          1        1           

Impacted Files	Coverage Δ
web_poet/_typing.py	100.00% <100.00%> (ø)
web_poet/overrides.py	100.00% <100.00%> (ø)
web_poet/pages.py	100.00% <100.00%> (ø)
web_poet/rules.py	100.00% <100.00%> (ø)
web_poet/utils.py	100.00% <100.00%> (ø)

[kmike]

hey @BurnzZ! I think we can solve "Handling the case of not needing all fields (recommendation for frameworks like scrapy-poet)" separately. These seem to be two independent features.

[BurnzZ]

I think this is ready for a proper review since the new API has been more or less validated in scrapy-poet's test cases: https://github.com/scrapinghub/scrapy-poet/pull/88/files#diff-a5ce1f1bde36b639be5be17fed1ed35ffb018c1fefcf4544c0e3fac120ca58eb

[kmike]

Thanks @BurnzZ, great work!