A few design considerations:

• I used the namesReader andWriter to match existing ABC names intyping/collections.abc. Alternatives areReadable andWritable, but I think they are used more rarely for these kind of (pseudo-)protocols.SupportsX would work forWriter, but not forReader, since the latter supports multiple methods. (Any we maybe want to useSupportsRead etc. at some point for tighter protocols.)
• I would prefer these protocols to be inio, where they fit better thematically, but that would require importingtyping with unforseeable (performance) implications for such a foundational module.
• I deliberated using tighter protocols, but for ease of use reasons – and since they are mostly an alternative to usingIO et al. – I went with larger protocols for now.
• Seekable (with methodsseek andtell) would be an interesting addition as well, but I think this should wait for easy protocol composition.

https://cpython-previews--127648.org.readthedocs.build/en/127648/library/typing.html#abcs-and-protocols-for-working-with-i-o

I would prefer these protocols to be inio, where they fit better thematically, but that would require importingtyping with unforseeable (performance) implications for such a foundational module.

io feels like a more natural home to me too. Could you not do something similar to the pseudo-protocol ABCs incollections.abc,contextlib andos.path? The approach there is:

• Make the classes ABCs rather than protocols
• But document them as protocols
• And write__subclasshook__ methods so that they behave identically to runtime-checkable Protocols in theirisinstance()/issubclass() behaviour:

  cpython/Lib/contextlib.py

  Lines 34 to 38 in023b7d2

  	@classmethod
  	def__subclasshook__(cls,C):
  	ifclsisAbstractContextManager:
  	return_collections_abc._check_methods(C,"__enter__","__exit__")
  	returnNotImplemented

• And special-case the ABCs intyping.py so that thetyping module treats them identically to protocols:

  cpython/Lib/typing.py

  Lines 1940 to 1948 in023b7d2

  	_PROTO_ALLOWLIST= {
  	'collections.abc': [
  	'Callable','Awaitable','Iterable','Iterator','AsyncIterable',
  	'AsyncIterator','Hashable','Sized','Container','Collection',
  	'Reversible','Buffer',
  	],
  	'contextlib': ['AbstractContextManager','AbstractAsyncContextManager'],
  	'os': ['PathLike'],
  	}

• And pretend in typeshed that they're protocols, so that type checkers treat them as protocols (I feel likepython/typeshed@f554f54 missed the point there slightly)

That feels terribly hackish to me, even if there is precedence. And in my experience, hackish stuff often falls on one's feet one way or the other. But I can move it toio if that's the consensus.

This has been the way thecollections.abc andcontextlib ABCs have always worked. As far as I'm aware, it's worked pretty well up to now. And it doesn't actually feel like the most hackish part ofcollections.abc ;)

Well, considering thattyping.is_protocol uses the_is_protocol marker to determine whether something is a protocol, I guess that's the official way to mark protocols at runtime, not the fact that they are derived fromProtocol. Whichcontradicts the typing spec at the moment. This all seems a bit precarious to me.

I'm open to something less hacky if you can find a generalized solution that doesn't make_collections_abc depend ontyping (which would significantly slow down startup for all Python applications, since_collections_abc is imported as part of Python's initialisation).

considering thattyping.is_protocol uses the_is_protocol marker to determine whether something is a protocol, I guess that's the official way to mark protocols at runtime, not the fact that they are derived fromProtocol. Whichcontradicts the typing spec at the moment.

I don't think the typing spec needs to be cognisant of the hacks we use to make things work at runtime in the stdlib! This knowledge is irrelevant for third-party users of protocols, to users of type checkers and to implementers of type checkers. It's definitely not encouraged for any external users to make use of the_is_protocol attribute.

CI seems flaky, failures are unrelated.

I'll leave it a little bit in case any of the other reviewers here have any remaining concerns before merging

Could this be merged before the next alpha next week?

I only saw the update now, great that it's merged!

I have a few comments. I hope they're not too bothersome - I just think these protocols are important so it's worth the effort.

Can the docs include type annotations? I know that Sphinx supports it. Given that this is meant for static typing, it makes sense to me to include.

I think it is important to document the expected semantics of these methods, otherwise you don't really know what you're going to get when you accept aReader orWriter. What I can think of:

• What should happen on EOF?
• Is EOF sticky?
• Short reads/writes
• What does it mean to omitsize?
• What happens onsize 0?
• Issize allowed to be -1 or more generally negative?
• Canread return value beNone? Empty?
• Canwrite return value be 0?
• Expected exceptions --IOError?

I don't like the parameter namesize, because from the caller perspective it is not exactly a size of anything. I would have preferred justn. But, I see this name is already used e.g.IOBase and consistency probably wins the argument here.

The docs say "If size is specified, it should be an integer, and at most size items (bytes/characters) will be read" and "Write data to the output stream and return the number of items (bytes/characters) written". I would drop the "(bytes/characters)" sinceT is not necessarily that.

The docs say "The following protocols can be used for annotating function and method arguments for simple stream reading or writing operations". I have two nitpicks:

• What is annotated is the parameter, not the argument (= a value for a parameter in a specific invocation). So would change "arguments" -> "parameters".
• I don't think it is just for simple operations, so I'd remove "simple".

I thinkT should have some bound. I think at leastSized, it's hard to interpret the return value without a notion of size.

A merged PR is probably not the best place to discuss this, but a few points:

Can the docs include type annotations?

Personally, I'd be fine with, and actually prefer if the docs used type annotations more, but I didn't want to divert from the existing style in the documentation.

I think it is important to document the expected semantics of these methods

While it would make sense to me to document some of those semantics (e.g. size must be>= 1), most are not part of this protocol. Exceptions and EOF are not concepts that are understood by those protocols.

I would drop the "(bytes/characters)" since T is not necessarily that.

It might have been clearer to say "(e.g. bytes or characters)", but I think calling out those specific types here makes the documentation clearer, as in 99% of cases it will be either of those. Otherwise the concept of "item" is a bit nebulous.

I think T should have some bound.

I don't think it's necessary to make the protocol more complex. Whoever is using the protocol will have to choose an type that they can work with.

Also in general, protocols are not a replacement for API documentation. It doesn't make too much sense to include expectations around a protocol that can't be checked statically. To document these expectations is the responsibility of the author of a function that uses these protocols, and to follow them is the responsibility of the user. These expectations can vary significantly from function to function.

(Please feel free to ignore this if you don't want to discuss this further -- I couldn't resist posting another comment...)

If I understand correctly, you prefer a narrow approach to these protocols because 1) they can't be checked statically 2) semantics can vary between uses. My replies:

1. In an ideal world, it would be possible to convey all semantics in a static way. But if it's not possible, documentation is the alternative. Stated differently, the Platonic ideal of theReader interface contains all of its (agreed) semantics, but its projection onto the Python type system is incomplete, so the documentation should try its best to fill the gap. That's how I view it at least.

2. Why should the semantics vary between uses? A single set of semantics has a big advantage - it reduces (N impls * M uses) coordination points to N + M. As an implementer, I can (implicitly or explicitly) follow the protocol and don't need to invent or document my semantics. As a user, I write to a single set of semantics, not needing to handle multiple sets, defensively protect against unknown ones, or document my expectations. As a "middleware" (e.g. aBufferedReader which adds buffering to any reader), I can take any generic reader. What's the advantage of allowing implementations to be inconsistent on something like how EOF is signaled?