Names for communication ABCs

[njsmith]

One of the major blockers for stabilizing Trio is that we need to stabilize our ABCs for channels/streams/pipes/whatever-they're-called. We've been iterating for a while, and I feel like we're pretty close on the core semantics, and I really want this to be done, but the fact is that I'm just not happy with the names, and those are kind of crucial. So here's an issue to try to sort it out once and for all.

Along the way, I've realized that there isn't really anything Trio-specific about these ABCs, and there are a bunch of advantages to making these ABCs something more widely used across the async Python ecosystem. So also CC'ing for feedback: @asvetlov @1st1 @agronholm @glyph (and feel free to add others). And I'll briefly review what we're trying to do for context before digging into the naming issue.

What problem are we trying to solve?

There are two main concepts that I think we need ABCs for:

• communication channels used to transmit/receive bytes (right now Trio calls this a trio.abc.Stream)
• communication channels used to transmit/receive objects of a given type (right now Trio calls this a trio.abc.Channel[T])

There are many many concrete implementations of each. Trio currently ships with ~7 different implementations of its byte-oriented communication ABC (sockets, TLS, Unix pipes, Windows named pipes, ...) and we expect to add more; it's also an interface that's commonly exposed and consumed by third-party libraries (think of SSH channels, HTTP streaming response bodies, QUIC connections, ...).

Object-wise communication is maybe a bit less familiar because most frameworks don't call it out as a single category, but it's also something you see all over the place. Some examples:

• asyncio Queues or Golang channels
• fundamental framing protocols like length-prefixing or newline-termination are strategies for converting an individual-byte-oriented channel into a bytes-object-oriented channel
• a lot of sans-io libraries like h11, wsproto, h2 are essentially designed to convert a stream-of-individual-bytes into a stream-of-event-objects
• Websockets are a channel for sending/receiving Union[bytes, str] objects

Having standard ABCs for these has a lot of benefits:

• Most obviously, it provides "one obvious way to do it", so developers can focus on the interesting parts instead of looking up whether they're supposed to call read or recv or receive or get
• It lets us write generic algorithms that work on arbitrary implementations. Example: Trio's TLS implementation can be composed with any compliant byte-stream implementation. A generic JSONChannel could be wrapped around any Channel[bytes] implementer to convert it into a Channel[JSONObject]. There's more discussion in Provide some standard mechanism for splitting a stream into lines, and other basic protocol tasks #796
• Something that surprised me, but that's becoming a major issue: having a standard convention across async libraries makes life much easier for packages that want to support multiple async libraries.
• Something that surprised me even more: aside from the asyncio/trio split, having standard abstractions here is the best way to write generic, composable sans-io protocols, because sans-io is basically another kind of I/O system, and Python's async/await is generic enough be repurposed for this. For more details see Provide some standard mechanism for splitting a stream into lines, and other basic protocol tasks #796 (comment)

If this is such a generic problem, then why should Trio be the one to solve it?

Well, no-one else seems to be working on it, and we need it :-). And of course we'd be happy if our work is useful to more people.

Asyncio will be adding an asyncio.Stream class in 3.8, but it doesn't seem to be intended as a generic abstraction with multiple implementations. It's a specific concrete class that's tightly tied to the asyncio's transport/protocols layer, and it exposes a rich public interface that includes buffering, line-splitting, fixed-length reads, and TLS.

This means that whenever someone needs a new kind of Stream object, they have two options: they can either define a new type that quacks like a Stream, which means they have to re-implement all this functionality from scratch. Or else, they have to implement their new functionality using the transport/protocols layer and then wrap an asyncio.Stream around it; but using the asyncio transport/protocol layer is awkward, adds overhead, and makes it very difficult to support other async libraries. Neither option is very appealing. IMO what we need is a minimal core interface, so that it's easy to implement, and then higher-level tools like buffering, line-splitting, TLS, etc. can be written once and re-used on any object that implements the byte-wise ABC.

And asyncio doesn't have an object-based communication abstraction at all, which IMO is a major missed opportunity.

Twisted OTOH does have standard abstractions for all these things, but they were designed 15+ years ago, long before async/await existed, and I think we can do better now. Heck, even the replacement @glyph's been working on for half a decade now predates async/await.

So the field seems wide open here.

What's already working?

We've been iterating on our APIs for these for a year+ now, and I think we're converging on a pretty solid design. You can see the current version in our docs: https://trio.readthedocs.io/en/stable/reference-io.html#abstract-base-classes

There are some details we're still sorting out – if you're curious see #1125, #823 / #1181, #371, #636 – but I don't want to get into the details too much because they're not really on-topic for this issue and I don't think they'll affect the overall adoption of the ABCs.

OK so what's this issue about then?

Like I said above, Trio currently uses trio.abc.Stream for the byte-wise interface, and trio.abc.Channel[T] for the object-wise interface. These names have two major problems:

• They're both completely generic. In regular English, "stream" and "channel" mean basically the same thing. This means that the names don't tell you anything about which is which, or how they're similar, or how they're different. And this is unfortunate, because while these concepts are fairly simple and fundamental, experience says that it really takes some work for new users to wrap their heads around them. Anything we can do to make that easier will help a lot.

  Also it personally took me like 6 months to stop mixing up the names and saying "stream" where I meant "channel" or vice-versa, which I just can't ignore. If I can't keep them straight, then how can I expect anyone else to keep them straight.

• There actually is an important conceptual relationship between them that IMO we should emphasize. Conceptually, byte-streams are basically object-streams where the object type is "a single byte". But if you try to use an interface designed for sending/receiving objects to send/receive individual bytes, then it'll be ridiculously inefficient, so instead you need a vectorized interface that works on whole bytestrings at once. A nice thing about framing things this way is that it emphasizes one of the things that always trips people up, which is that byte-streams don't preserve framing – because they're really a stream of individual bytes.

So I think the right way to do it is to present the object-wise interface as the more fundamental one, and the byte-wise interface as a specialized variant. And we can communicate that right in the names, by calling the object-wise interface X[T], and the byte-wise interface a ByteX.

And then when someone asks what the difference is between a ByteX and an X[bytes], we can say: This is an X[bytes]. This is a ByteX. (click the images to see the animations)

But what should X be?

Can we steal from another system?

As mentioned above, AsyncIO has a concrete class Stream for byte-wise communication and a concrete class Queue for object-wise communication, but no relevant ABCs.

Go has a concrete type chan for communicating objects within a single process, and abstract Reader and Writer interfaces for byte-wise communication.

Nodejs has an abstract Stream interface, that they use for both byte-wise and object-wise communication. There's a mode argument you can set when creating the stream, that determines whether bytestrings can be rechunked or not. (It's pretty similar to some of the approaches we considered and rejected in #959.) The byte-wise mode is the default, and the object-wise mode seems like an afterthought (e.g. the docs say that nodejs itself never uses the object-wise mode).

Rust's Tokio module has an abstract Stream interface, which is basically equivalent to an async iterator in Python, or what Trio calls a trio.abc.ReceiveChannel[T]. And they also have an abstract Sink interface, which is equivalent to what Trio currently calls a trio.abc.SendChannel[T]. For bytes, they have abstract interfaces called AsyncRead and AsyncWrite. And they have generic framing tools to convert an AsyncRead into a Stream, or convert an AsyncWrite into a Sink.

Java's java.nio library uses Channel to mean, basically, anything with a close method (like Trio's AsyncResource). And then it has sub-interfaces like ByteChannel for byte-oriented communication. I don't think there's any abstract interface for framed/object-wise communication. Java's java.io library uses Stream to refer to byte-wise communication, and Reader and Writer for character-wise communication.

Swift NIO has an abstract Channel interface for byte-wise communication, and I don't see any interfaces for framed/object-wise communication.

My takeaways:

There's no general consensus on terminology. The words "stream" and "channel" show up a lot, but the meanings aren't consistent. "Read" and "write" are also popular, and are used consistently for byte-oriented interfaces.

There isn't any consensus on the basic concepts either! A major part of our ABC design is the insight that object-wise and byte-wise communication are both fundamental concepts, and that it's valuable to have standard interfaces to express both of them, and how they relate. But most of these frameworks only think seriously about byte-wise communication, and treat object-wise communication as an unrelated problem if they consider it at all. Tokio is the main exception, but their terminology is either ad hoc or motivated by other Rust-specific stuff. So we can't just steal an existing solution.

OK so what are our options?

I tried to brainstorm all the potential names I could think of, assuming we go with the X + ByteX pattern described above:

• Channel[T] + ByteChannel, e.g. you could use a MemoryChannel to pass objects between tasks, and a SocketByteChannel to represent a TCP connection
• Stream[T] + ByteStream, e.g. MemoryStream, SocketByteStream
• Tube[T] + ByteTube, e.g. MemoryTube, SocketByteTube
• Flow[T] + ByteFlow, e.g. MemoryFlow, SocketByteFlow
• Transport[T] + ByteTransport, e.g. MemoryTransport, SocketByteTransport
• Hose[T] + ByteHose, e.g. MemoryHose, SocketByteHose
• Ferry[T] + ByteFerry, e.g. MemoryFerry, SocketByteFerry
• Duct[T] + ByteDuct, e.g. MemoryDuct, SocketByteDuct
• Vent[T] + ByteVent, e.g. MemoryVent, SocketByteVent
• Pipe[T] + BytePipe, e.g. MemoryPipe, SocketBytePipe
• Port[T] + BytePort, e.g. MemoryPort, SocketBytePort

Criteria: I think ideally our core name should be a common, concrete English word that's short to say and to type, because those make the best names for fundamental concepts. It shouldn't be too "weird" or controversial, because people dislike weird names and will refuse to adopt them even if everything else is good. And of course we want it to be unambiguous, so we need to avoid name clashes.

Unfortunately it's really hard to get all of these at once, which is why I got stuck :-)

Stream is really solid on the first two criteria: it's one syllable, common, uncontroversial. But! It clashes with asyncio.Stream. That's not a problem for adoption in the Trio ecosystem. But it might be a major problem if we want this to get uptake across Python more broadly.

The other obvious option is Channel, but I'm really hesitant because it's more cumbersome: 2 syllables on their own aren't too bad, but by the time you start talking about a SocketByteChannel it feels extremely Java, not Python.

For some reason Transport doesn't bother me as much, even though it's two syllables as well, but then you have the clash with the whole protocols/transport terminology, and that also seems like it could be pretty confusing. And we're generally trying to move away from protocols/transports, but I don't want to have to tell beginners "we recommend you use Transports instead of protocols/transports". That's just going to make them more confused.

Among the rest, Tube is tempting as a simple, short, concrete word that doesn't conflict with anything in Trio or asyncio, and fits very nicely with illustrations like the ones I linked above, where there's a literal tube with objects moving through it. But... @glyph has been trying to make his tubes a thing for half a decade now. I think the proposal here is totally compatible with the goals and vision behind his version of tubes, and much more likely to get wider traction going forward. But OTOH the details are very different. So I can't tell whether using the name here would be the sincerest form of flattery, or super-rude, or both at once.

What do y'all think?

[smurfix]

IMO what we need is a minimal core interface, so that it's easy to implement, and then higher-level tools like buffering, line-splitting, TLS, etc. can be written once and re-used on any object that implements the byte-wise ABC

Strongly seconded. In an ideal world we would rework asyncio.Stream to do exactly this, instead of releasing it in 3.8 with all these bells and whistles … but I'm afraid it's too late for that.

I'd go with Flow.

[1st1]

In an ideal world we would rework asyncio.Stream to do exactly this, instead of releasing it in 3.8 with all these bells and whistles …

Well, in an ideal world we would just have Trio to be the default framework of choice for async in all languages. The reality is different though: asyncio.Stream is designed the way it is designed to preserve backwards compatibility, and so unfortunately there's not a lot of room left to change it. Not including it in 3.8 wouldn't change any of that.

That said, if there's something we can do to make it easier for people to write adapters from Trio streams to asyncio Streams (if that's even a thing) we'll gladly consider that!

[sorcio]

• There actually is an important conceptual relationship between them that IMO we should emphasize. Conceptually, byte-streams are basically object-streams where the object type is "a single byte". But if you try to use an interface designed for sending/receiving objects to send/receive individual bytes, then it'll be ridiculously inefficient, so instead you need a vectorized interface that works on whole bytestrings at once.

Can this be made part of the same abstract interface? What receive_some() is saying is "I want some sequential items of type T, if you're able to provide them" and returns a Sequence[T]ish. The way the underlying buffer is managed is left to the individual implementation. A default implementation can just basically return [await self.receive()]. Something backed by a file object might translate it into a read(). On the other hand, I believe that a bytestream kind of object can always have a pretty inefficient receive() method that takes a single byte off the underlying buffer, e.g. read(1). I'm not sure this would ever be useful for anything other than bytes, but maybe the mismatch is smaller if we think of stream operations as just "arbitrary sequential chunks of the basic type"?

This would be more problematic for send_all() because it cannot guarantee in general that the sequence is kept intact, i.e. if you translate it into a series of send() you might get interleaved sends from other tasks. But we already have the same problem in Trio Stream right now, and maybe it becomes more obvious.

[asvetlov]

Agree with @1st1
asyncio.Stream was not designed from scratch but just a merge of already existing StreamReader + StreamWriter APIs plus some backward-compatible improvements.
Sorry, in asyncio we should provide very conservative backward compatibility politics for any change.
Sometimes it prevents us from making code as beautiful as possible but this is the CPython game rule.

[smurfix]

That said, if there's something we can do to make it easier for people to write adapters from Trio streams to asyncio Streams (if that's even a thing) we'll gladly consider that!

Umm, yeah. My take would be to make the whole thing modular.

Details: Add a BaseStream abstract interface that requires just the three basic methods (read_some, write_all, close). Create a TransportStream class that implements this interface in terms of protocol+transport compatibility, ideally with the aim of someday deprecating protocols and transports altogether. (Sync callback hell.)
Let Stream be a shallow class that implements all the complicated read and write operations in terms of calling read and write of an underlying BaseStream object.
Create a SSLFilter class that implements SSL on top of that. Stream.start_tls can then simply push a SSLFilter below itself. Implement aBufferFilter` that buffers data for you.

Most of these filters would even be framework agnostic; they would work with trio, asyncio, or whateverio. (As long as nobody needs sub-tasks or timeouts, of course.) You don't even need to write the SSLFilter, as Trio already has one. Steal it. Everything else seems reasonably trivial at first glance.

NB: IMHO: Whoever invented a write method which one may or may not await deserves [removed]. Ugh.

[1st1]

NB: IMHO: Whoever invented a write method which one may or may not await deserves [removed]. Ugh.

Oh, hm, that was me. We're still debating about that though. One of the solutions is to add await Stream.send() and keep Stream.write() as is (i.e. not returning a `Future). Do you think that would be a better idea? (Because we still can change it!)

[smurfix]

Yes, please. Or call it write_all like in Trio.

Arguments against this idea: (a) this prevents automated testing (with mypy et al.) whether somebody forgot an await, (b) prevents automatic warnings when one of these awaitables is garbage collected without having been awaited on (these are very helpful IME), (c) requires everybody who implements this interface to add an unlimited send buffer and to copy/reimplement the special dance you'd need to return such an awaitable.

[1st1]

Details: Add a BaseStream abstract interface that requires just the three basic methods (read_some, write_all, close). Create a TransportStream class that implements this interface in terms of protocol+transport compatibility, ideally with the aim of someday deprecating protocols and transports altogether. (Sync callback hell.)
Let Stream be a shallow class that implements all the complicated read and write operations in terms of calling read and write of an underlying BaseStream object.
Create a SSLFilter class that implements SSL on top of that. Stream.start_tls can then simply push a SSLFilter below itself. Implement aBufferFilter` that buffers data for you.

I actually like all of this.

BUT asyncio.Stream.write() is this weird method that's currently can be awaited or not really.
asyncio.Stream.close() isn't awaitable and just broken in my opinion. Our goal is to make the API nicer and less confusing, and returning an optional Future did look like an acceptable solution.

[1st1]

How about Trio renames read_some() to read() as is makes it easier for us. I'm against having read_some() as a simple alias for read().

We can maybe work around the weird nature of write(). Options: revert the change, add send() or writeall(); deprecate write() and drain().

And lastly we'll have a problem with asyncio.Stream.close(), which should be awaitable but isn't quite.

[smurfix]

asyncio.Stream.close() isn't awaitable and just broken

Well, sometimes you really do need to kill off a connection Right Now, no matter what. I'd rename it to abort and deprecate close, though.

The nice, everybody-should-use-it async version might be named aclose …

[1st1]

I've discussed this with @ambv and here's the plan I like for 3.8:

• asyncio.Stream.write() will start throwing a DeprecationWarning asking people to add an await if they didn't;

• asyncio.Stream.close() will start throwing a DeprecationWarning asking people to add an await if they didn't;

• asyncio.Stream.drain() & asyncio.Stream.wait_closed() will start throwing a DeprecationWarning telling about a scheduled removal (in Python 3.12) when used on Process.std* streams;

• asyncio.Stream.drain() & asyncio.Stream.wait_closed() will not work at all on Streams created via new 3.8 APIs: connect() & StreamServer.

---

Well, sometimes you really do need to kill off a connection Right Now, no matter what. I'd rename it to abort and deprecate close, though.

I'm fine with adding Stream.abort(), not super excited about your ideas about the close()/aclose() method.

The key question I have now is this: If we do the above, would that be better for Trio in any way?

[smurfix]

The key question I have now is this: If we do the above, would that be better for Trio in any way?

Well, I'm not @njsmith but from my PoV, yes sure. Splitting up Stream would also help a lot, not just for Trio interoperability; I should be able to help out if there's a chance to get that into 3.8 even though my free time is annyoingly limited.

The other problem that we still have is the one this topic is supposed to be about, i.e. naming things. If asyncio is set on keeping plain Stream for what Nathaniel tried to name ByteStream, which I personally can live with, that requires us to come up with a reasonable name for pipes/flows/whatever that happen to not consist of chunks of bytes.

[1st1]

I should be able to help out if there's a chance to get that into 3.8 even though my free time is annyoingly limited.

Sure, we'd accept help. Splitting up sounds interesting, as I'm a big fan of composable component-oriented APIs such as Twitter's Finagle.

cc @asvetlov

[agronholm]

I'm all for standardization across the board, especially if it ends up allowing me to reduce the code base of AnyIO. Because the semantics of network functionality of the various I/O libraries were so wildly different, I had to invent my own. I would jump at the opportunity to throw out that code and piggyback on the individual network layers of each framework, provided that the semantics were in harmony with each other. But, it seems like there will be a long way to go until that happens.

I have no real preferences about the naming of the ABCs, so long as they're descriptive and everybody agrees on them.

@1st1 Are you still planning to make that asyncio-next library?

[njsmith]

@smurfix

Whoever invented a write method which one may or may not await deserves

Hey man, I know this was humorous exaggeration, but let's criticize tech not people, and skip the violent imagery. I edited your post to remove that bit.

@1st1

How about Trio renames read_some() to read() as is makes it easier for us. I'm against having read_some() as a simple alias for read().

Trio currently calls the method receive_some, and it has different semantics from your read: with no arguments, receive_some returns an arbitrary sized chunk of data, while read with no arguments consumes the whole stream until EOF. This kind of issue is why we've avoided using read as our verb. We also have a dedicated issue for method names with more discussion: #1125

The different names also have a potential advantage here: they mean the same object could potentially expose both a backwards-compatible set of operations for legacy asyncio code, and also implement this hypothetical ABC we're talking about with the improved semantics. (And the new methods could skip straight to the desired semantics while the old ones are working their way through their deprecation periods.)

There is one big conflict though: iteration. Trio's byte stream interface allows async iteration and it returns arbitrary byte chunks. asyncio.Stream also supports async iteration, but it returns lines. IMO the Trio version is substantially more useful – we only added this recently and it made a lot of code simpler. But you can't support both on the same object at the same time.

We don't have to sort out all the details right now, but maybe for 3.8 you might consider replacing asyncio.Stream.__aiter__ with a generator method like asyncio.Stream.iterlines(), to keep your options open in the future?

@smurfix

Well, sometimes you really do need to kill off a connection Right Now, no matter what. I'd rename it to abort and deprecate close, though.

In Trio this is actually handled as part of the trio.abc.AsyncResource interface. It doesn't just tell you how to spell the close method name (aclose) but also specifies that it should normally do a graceful close, but if cancelled it must do a forceful close. This is necessary for general correctness, but it also means we don't need a separate method for abort – instead we have a helper trio.forceful_close that can do an abort on any kind of AsyncResource, by calling aclose and immediately cancelling it. The downside compared to your proposal is that it means forceful close is an async-colored operation, not sync-colored... but it turns out this actually has benefits, because for e.g. disk files, the OS doesn't provide any way to close it without blocking, so we actually need forceful close to be async-colored.