Improve error handling, documentation and tests of itertools

[mih]

Extracted and modified from #539

mypy complains:

datalad_next/itertools/itemize.py:110: error: Argument "sep" to "split" of "bytes" has incompatible type "str | bytes"; expected "Buffer | None"  [arg-type]
datalad_next/itertools/itemize.py:110: error: Argument "sep" to "split" of "str" has incompatible type "str | bytes"; expected "str | None"  [arg-type]
datalad_next/itertools/itemize.py:114: error: Argument 1 to "endswith" of "bytes" has incompatible type "str | bytes"; expected "Buffer | tuple[Buffer, ...]"  [arg-type]
datalad_next/itertools/itemize.py:114: error: Argument 1 to "endswith" of "str" has incompatible type "str | bytes"; expected "str | tuple[str, ...]"  [arg-type]
datalad_next/itertools/itemize.py:121: error: Unsupported operand types for + ("bytes" and "str")  [operator]
datalad_next/itertools/itemize.py:121: error: Unsupported operand types for + ("str" and "bytes")  [operator]
datalad_next/itertools/itemize.py:121: note: Both left and right operands are unions

[christian-monch]

Thanks for including the documentation here.

I just have a few remarks regarding the runtime of itemize when keep_ends=True is specified. The runtime is only depending on the value of keep_ends if sep is not None.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (54f8abe) 83.65% compared to head (4a54380) 92.66%.

❗ Current head 4a54380 differs from pull request most recent head 73a3d31. Consider uploading reports for the commit 73a3d31 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #548      +/-   ##
==========================================
+ Coverage   83.65%   92.66%   +9.00%     
==========================================
  Files         137      137              
  Lines       10035    10049      +14     
  Branches     1085     1086       +1     
==========================================
+ Hits         8395     9312     +917     
+ Misses       1632      713     -919     
- Partials        8       24      +16     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.