ENH: Allow DatasetMetadataExtractor.get_required_content() to return a generator

[jsheunis]

This PR:

• Adds logic to extract.py to allow either a returned bool or a yieldedGenerator to be interpreted correctly: If an extractor implements logic where any result record is yielded with a failure 'status' (i.e. equal to 'impossible' or 'error') the extractor infrastructure will signal an error and the extractor's extract method will not be called.
• Updates the docstring of DatasetMetadataExtractor.get_required_content() in extractors/base.by to indicate this change, especially to developers implementing extractors
• Adds missing return statements in extract.py where failures are yielded
• Updates related documentation
• Closes DatasetMetadataExtractor.get_required_content() should be able to yield datalad result dicts #356

[christian-monch]

Nice, thanks a lot. A few comments below

[codecov-commenter]

Codecov Report

Patch coverage: 30.76% and project coverage change: -0.14 ⚠️

Comparison is base (7a60107) 86.42% compared to head (932d211) 86.28%.

❗ Current head 932d211 differs from pull request most recent head 58c51e5. Consider uploading reports for the commit 58c51e5 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #361      +/-   ##
==========================================
- Coverage   86.42%   86.28%   -0.14%     
==========================================
  Files          88       88              
  Lines        4831     4841      +10     
==========================================
+ Hits         4175     4177       +2     
- Misses        656      664       +8     

Impacted Files	Coverage Δ
datalad_metalad/extract.py	88.28% <25.00%> (-2.78%)	⬇️
datalad_metalad/extractors/base.py	86.66% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[christian-monch]

LGTM, thanks @jsheunis

[jsheunis]

Great! @christian-monch feel free to merge if you're happy.