use method to create PDFPageInterpreter's parsers

[snoyer]

Pull request

This PR allows subclasses of PDFPageInterpreter to control the initialization of the underlying PDFContentParser.

How Has This Been Tested?

Existing tests are passing so if nothing else the change does not seem to break anything.

I am using this change for a use-case where I need to correlate low level info (operators in streams) with high level info (graphic state) and therefore need to be able to get a handle on the parser during execution (from the do_...() methods). The idea is to do something like this:

class MyPageInterpreter(PDFPageInterpreter):
    def create_parser(self, valid_streams: Sequence[PDFStream]):
        self._parser = MyContentParser(valid_streams)
        return self._parser

    def do_S(self):
        if self.graphicstate.scolor == (1, 0, 0):
            print(f"red stroke at pos {self._parser.current_pos} in {self._parser.current_stream}")

class MyContentParser(PDFContentParser):
    @property
    def current_pos(self):
        return self.bufpos + self.charpos

    @property
    def current_stream(self):
        stream = self.streams[self.istream - 1]
        assert isinstance(stream, PDFStream)
        return stream

I can provide a full minimal example and/or add it as a proper test if needed.

Checklist

• I have read CONTRIBUTING.md.
• I have added a concise human-readable description of the change to CHANGELOG.md.
• I have tested that this fix is effective or that this feature works.
• I have added docstrings to newly created methods and classes.
• I have updated the README.md and the readthedocs documentation. Or verified that this is not necessary.