extend Document.__getitem__ type annotation to reflect that the method also accepts slices

[Sorontik]

Problem
The type annotation of Document.__getitem__ is wrong:

def __getitem__(self, i: int =0):
        if isinstance(i, slice):

The type annotation of i requires it to be an int, but the implementation is obviously meant to also accept a slice (and works fine with slices)

Solution
extend the signature to a Union and add overloads to tell typecheckers which return values correspond to which argument types:

    @typing.overload
    def __getitem__(self, i: int) -> Page: ...
    
    @typing.overload
    def __getitem__(self, i: slice) -> list[Page]: ...

    def __getitem__(self, i: typing.Union[int, slice] =0) -> typing.Union[Page, list[Page]]:
        if isinstance(i, slice):
            return [self[j] for j in range(*i.indices(len(self)))]
        assert isinstance(i, int) or (isinstance(i, tuple) and len(i) == 2 and all(isinstance(x, int) for x in i)), \
                f'Invalid item number: {i=}.'
        if i not in self:
            raise IndexError(f"page {i} not in document")
        return self.load_page(i)

that way it reflects the reality of which argument types the methods actually accepts and which return value types they produce.
Note that the actual implementation remains unchanged besides the extension of the type annotation

Thanks to the overload for slices, typecheckers also correctly recognize, that the result of indexing with a slice is iterable
(Which is not the case if you just add the Unions to the signature, then the typechecker would complain that a Page is not iterable)

Alternatives
Ignore the problem until it is solved by the complete rework of type hints as mentioned by julian-smith-artifex-com:

We are looking at possible architectural changes that will allow better type hints in future. But it's quite an involved process so there are no timescales at the moment.
#3361 (comment)

but since there is no ETA for the overhaul and since this fix is so quick and straightforward, i believe it would still be worth it to implement it now

compatibility concerns

• typing.Union is already used repeatedly in the module
• typing.overload has not been used previously, but was introduced alongside typing.Union in python 3.5
• overloading should be fully transparent at runtime
• no functional changes are made to the actual implementation

therefore i don't see any compatibility concerns

[julian-smith-artifex-com]

Fixed in 1.24.10.