An example usage:

>>> s = 'Hello world'
>>> t = buffer(s, 6, 5)
>>> t
<read-only buffer for 0x10064a4b0, size 5, offset 6 at 0x100634ab0>
>>> print t
world

The buffer in this case is a sub-string, starting at position 6 with length 5, and it doesn't take extra storage space - it references a slice of the string.

This isn't very useful for short strings like this, but it can be necessary when using large amounts of data. This example uses a mutable bytearray:

>>> s = bytearray(1000000)   # a million zeroed bytes
>>> t = buffer(s, 1)         # slice cuts off the first byte
>>> s[1] = 5                 # set the second element in s
>>> t[0]                     # which is now also the first element in t!
'\x05'

This can be very helpful if you want to have more than one view on the data and don't want to (or can't) hold multiple copies in memory.

Note that buffer has been replaced by the better named memoryview in Python 3, though you can use either in Python 2.7.

Note also that you can't implement a buffer interface for your own objects without delving into the C API, i.e. you can't do it in pure Python.

You need to use the same type definition as your base. You can use the same type alias here by importing it from _typeshed package, provided you put it under a TYPE_CHECKING guard:

from io import RawIOBase
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from _typeshed import MaybeNone, WriteableBuffer

class Reader(RawIOBase):
    def readinto(self, buf: WriteableBuffer) -> int | MaybeNone:
        ...

You can count on the _typeshed package existing when running under a type checker, because the type checker brings along that package. This is how pyright knows what the signature for RawIOBase.readinto() is, for example. I added MaybeNone to the above for the same reason, because that's also part of the documented signature.

Alternatively, because WriteableBuffer is just a type alias for collections.abc.Buffer, the following also works (replacing MaybeNone with a redefinition):

from collections.abc import Buffer
from io import RawIOBase
from typing import Any, TypeAlias

type MaybeNone = Any

class Reader(RawIOBase):
    def readinto(self, buf: Buffer) -> int | MaybeNone:
        ...

See The Any Trick for an explanation as to why MaybeNone is an alias for Any.

Starting with Python 3.12, collections.abc.Buffer can be used like so:

from collections.abc import Buffer

def foo(buffer: Buffer):
    pass