Stream API/specs: File.stream! vs IO.stream

File.stream! has a line that’s easy to miss in the docs:

Operating the stream can fail on open for the same reasons as File.open!/2

“Operating” is the key part - you can File.stream! things that don’t exist, and you won’t get the exception until something forces the stream.

For instance:

iex(1)> File.stream!("nosuchfile.txt")

%File.Stream{
  line_or_bytes: :line,
  modes: [:raw, :read_ahead, :binary],
  path: "nosuchfile.txt",
  raw: true
}

iex(2)> File.stream!("nosuchfile.txt") |> Enum.to_list()

** (File.Error) could not stream "nosuchfile.txt": no such file or directory
    (elixir 1.13.0) lib/file/stream.ex:83: anonymous fn/3 in Enumerable.File.Stream.reduce/3
    (elixir 1.13.0) lib/stream.ex:1517: anonymous fn/5 in Stream.resource/3
    (elixir 1.13.0) lib/enum.ex:4143: Enum.reverse/1
    (elixir 1.13.0) lib/enum.ex:3488: Enum.to_list/1

IO.stream can’t fail in any of these ways since it takes either a PID (that you’d get from calling File.open! and possibly getting an exception) or an atom (to refer to stdio), so it doesn’t get a !.

So I didn’t notice that actual line but I’m certainly familiar with the behavior that a File stream will fail when you try to iterate on it. I am less familiar with working with IO streams though so that was probably a bad assumption of mine that there were some cases that might cause an error at that point. I guess it’s just that lazy evaluation is an interesting edge case for this convention. My first reaction is that even if using the stream might create an error at a certain point, the function name should only express the possible return values, but it’s clear why that would be difficult to adhere to in this case.

Interestingly, my case involves different stream sources so it complicates even further. if a stream API might return an IO stream or a File stream, how should it be named? stream! because in certain conditions an error might be raised on iteration?