Document dependency between HttpRequest stream IO methods and body.

[Adam Johnson]

When accessing HttpRequest.body it's possible that it will raise RawPostDataException due to prior use of HttpRequest.read() / readline(). However there is no documentation covering this exception, nor any guidance about solving it. Other exceptions like RequestDataTooBig are covered.

Also the exception message is a little obscure: "You cannot access body after reading from request's data stream" . What's the 'data stream' here?

[Carlton Gibson]

I'm not entirely convinced here...

• It's a bit generous to say RequestDataTooBig is documented. It's mentioned, yes, but...
• IMO request's data stream is clear enough, since you're using the stream IO API (read() &co.)
• Part of this stuff is undocumented because internal no?

But I guess we could add a note to the ​`HttpRequest.read()` docs saying something like, "if read() is used prior to accessing body, body will no longer be available." The body docs link to read() saying "see more", but then there's nothing said so some expansion might be good.

(Given that all the stream IO methods have the same issue, perhaps the note needs to be in the body docs.)

[Adam Johnson]

It's a bit generous to say RequestDataTooBig is documented

Yes that's true. But at least one can search for it in the docs and find a sentence.

IMO request's data stream is clear enough, since you're using the stream IO API (read() &co.)

It's not always clear that the streaming API has been read, as the body can be read by some other code. The issue came up for me when trying to access .body after django-rest-framework had used .read().

Part of this stuff is undocumented because internal no?

I don't think this is internal - these are exceptions that users can see when trying to use the public interface in .body / read() etc.

I think only a few sentences are needed to describe the possible problems so that anyone trying to debug similar issues has more information to go on.

[Mariusz Felisiak]

​PR

[GitHub <noreply@…>]

In 060576b0:

Fixed #31739 -- Documented dependency between HttpRequest stream IO methods and body.

[Carlton Gibson <carlton.gibson@…>]

In 3756a05:

[3.1.x] Fixed #31739 -- Documented dependency between HttpRequest stream IO methods and body.

Backport of 060576b0abac460d72714e300aa709d1e7a87dd7 from master

[Carlton Gibson <carlton.gibson@…>]

In 502349ce:

[3.0.x] Fixed #31739 -- Documented dependency between HttpRequest stream IO methods and body.

Backport of 060576b0abac460d72714e300aa709d1e7a87dd7 from master