File.as_handle_and_flag

[speleo3]

Follow-up on #4377 ("mypy pre-commit hook").

• New function as_handle_and_flag
• New function check_handle_mode
• Use as_handle or as_handle_and_flag where appropriate
• Move _PathLikeTypes, _IOSource and _TextIOSource to Bio.File module

---

• I hereby agree to dual licence this and any previous contributions under both
  the Biopython License Agreement AND the BSD 3-Clause License.

• I have read the CONTRIBUTING.rst file, have run pre-commit
  locally, and understand that continuous integration checks will be used to
  confirm the Biopython unit tests and style checks pass with these changes.

• I have added my name to the alphabetical contributors listings in the files
  NEWS.rst and CONTRIB.rst as part of this pull request, am listed
  already, or do not wish to be listed. (This acknowledgement is optional.)

[peterjc]

I like the more consistent use of as_handle here

[mdehoon]

I am not a big fan of utility functions, as it is one more API to remember. In the past, we spent some effort removing such utility functions from Biopython because they were not consistently being used by developers, as they were not always aware of their existence. So I am hesitant to add more utility functions.
Notice also that the yield statement in as_handle creates an iterator class behind the scenes, and the simple operation of opening a file becomes an iteration.
In Bio.SeqIO, the iterator design is a bit strange in places. For example, FastaIterator inherits from SequenceIterator; calling next on FastaIterator calls next on self.records, which points to the return value of self.iterate, which is a generator as it uses yield. So now we have a double iterator.

[peterjc]

On the other hand, the helper function avoids a lot of repetitive boiler plate code. So I like this change in general.

I'm not sure we need the extra function as_handle_and_flag though - as it stands it only gets used once?

Any accidental double iteration in FastaIterator is best flagged separately - it sounds like the SequenceIterator isn't quite right.

[mdehoon]

I think the first step would be to fix the SequenceIterator. Once that is done, it will be more clear what a utility function should actually look like. Probably it should not be a function, but a class from which the SequenceIterator inherits.

The challenge is that SequenceIterator and its equivalent in Bio.Align etc. are non-trivial. I don't mind a bit of code duplication if it makes the class easier to understand, rather than adding a utility function as one more component into the mix.

[speleo3]

Opening a file with as_handle does not really become an iterator. It becomes a context manager via the contextlib.contextmanager decorator.

as_handle_and_flag is used 4 times.