Posting this in discussions because it’s more of an open question about API design/conventions, but while looking through the documentation around streams, I found myself wondering why File includes a stream! function whereas IO has stream. According to specs, both functions appear to work similarly, returning an Enumerable directly (not wrapped in a tuple), and neither mentions any error cases I noticed, so why the different name?

My impression was that there is a pretty strong convention that a ! suffix in a function should always indicate that an error could be expected in certain conditions, whereas a function without ! should never be expected to return an error, but could return either a “status tuple” (actually not sure if there’s a more technical term for {:ok, res}/{:error, res} return values) or a result more directly, which I guess would mean that IO.stream is more “correct,” since, unlike File.read!, File.stream! will not error even when the path is invalid, etc?

Mostly just curious because I am designing a stream API for one of my own modules where most of the functions return status couples, but I don’t foresee any error cases for the streaming API. Appreciate any input!