Repository navigation
Conversation
| ```python | ||
| >>> j = hip.JSON(...) | ||
| client = hip.Client() | ||
| form_content = hip.Form({'email': 'ada@example.com', 'message': 'Hello'}) |
There was a problem hiding this comment.
Could we use a single word variable here? content or data perhaps?
|
|
||
| ```python | ||
| >>> f = hip.Form(...) | ||
| json_content = hip.JSON({'title': 'A short guide', 'published': True}) |
| upload_content = hip.MultiPart( | ||
| form={'description': 'A butterfly'}, | ||
| files={'image': hip.File('image.png')}, | ||
| ) | ||
| response = client.post('https://www.example.com/images', content=upload_content) |
There was a problem hiding this comment.
| upload_content = hip.MultiPart( | |
| form={'description': 'A butterfly'}, | |
| files={'image': hip.File('image.png')}, | |
| ) | |
| response = client.post('https://www.example.com/images', content=upload_content) | |
| upload = hip.MultiPart( | |
| form={'description': 'A butterfly'}, | |
| files={'image': hip.File('image.png')}, | |
| ) | |
| response = client.post('https://www.example.com/images', content=upload) |
There was a problem hiding this comment.
Also, this example reminds me that I like this API!
| Although `ByteStream`, `FileStream`, and `MultiPartStream` implement the `Stream` | ||
| interface, they are not part of hip’s public API. Use the `Stream` interface when | ||
| working with streams. |
There was a problem hiding this comment.
Can we find a way to word this that doesn't name the classes? Eg...
The
Streaminterface is public API, although the implementation classes themselves are private.
| arriving. A short read does not by itself mean the stream has ended. When the | ||
| stream ends, a positive-size read returns b''. | ||
|
|
||
| `read(0)` returns `b''` without consuming data. Do not use it as an end-of-stream check. |
There was a problem hiding this comment.
I don't think this is the behaviour we want, because it's too easy to get caught out.
We could...
- Use
size <= 0as the "Until EOF" indicator? - Raise
ValueErroron size=0? - Something more carefully explicit?
There was a problem hiding this comment.
Removing this for now!
| Content streams returned by `Content.open()` are read-only. Calling `write()` on | ||
| one raises `NotImplementedError`. | ||
|
|
||
| A `NetworkStream` supports `write(data)`. It sends the supplied bytes and returns | ||
| `None` on success. |
There was a problem hiding this comment.
We're not currently documenting / exposing NetworkStream, and it's not part of the core API. (ie. users don't need to know about it in order to write client/server level code)
Perhaps we can re-write this slightly to omit mentioning it.
Eg.
Most stream implementations are for read-only data sources. However the
Streaminterface also allows for read/write or write-only implementations.
Or something along those lines?
There was a problem hiding this comment.
It was already a bit of a stretch, I think we can remove this line too.
|
Oh, thought... Since we've actually only got stubbed out API docs at the moment, should we match that super-concise style, and then think more holistically about expanding this page... https://www.encode.io/hip/api/ ...into prose docs? |
0cd0db1 to
47b1ebb
Compare
cgl
left a comment
cgl
left a comment
There was a problem hiding this comment.
Since we've actually only got stubbed out API docs at the moment, should we match that super-concise style, and then think more holistically about expanding this page... https://www.encode.io/hip/api/ ...into prose docs?
I am keen to have a more progressive approach, such as matching the rest of the docs to this prose style. I can hold this PR unmerged until then.
| arriving. A short read does not by itself mean the stream has ended. When the | ||
| stream ends, a positive-size read returns b''. | ||
|
|
||
| `read(0)` returns `b''` without consuming data. Do not use it as an end-of-stream check. |
There was a problem hiding this comment.
Removing this for now!
| Content streams returned by `Content.open()` are read-only. Calling `write()` on | ||
| one raises `NotImplementedError`. | ||
|
|
||
| A `NetworkStream` supports `write(data)`. It sends the supplied bytes and returns | ||
| `None` on success. |
There was a problem hiding this comment.
It was already a bit of a stretch, I think we can remove this line too.
| ```python | ||
| >>> j = hip.JSON(...) | ||
| client = hip.Client() | ||
| form_content = hip.Form({'email': 'ada@example.com', 'message': 'Hello'}) |
|
|
||
| ```python | ||
| >>> f = hip.Form(...) | ||
| json_content = hip.JSON({'title': 'A short guide', 'published': True}) |
| Although `ByteStream`, `FileStream`, and `MultiPartStream` implement the `Stream` | ||
| interface, they are not part of hip’s public API. Use the `Stream` interface when | ||
| working with streams. |
#30