Streams API

Author: lovelydinosaur

docs/streams.md

@@ -10,23 +10,22 @@ The base `Stream` class. The core of the interface is a subset of Python's `io.I
 
 * `.read(size=-1)` - *(bytes)* Return the bytes from the data stream. If the `size` argument is omitted or negative then the entire stream will be read. If `size` is an positive integer then the call returns at most `size` bytes. A return value of `b''` indicates the end of the stream has been reached.
 * `.close()` - Close the stream. Any further operations will raise a `ValueError`.
-* `.closed` - *(bool)* Return a boolean indicating if the stream is closed or not.
 
-Additionally, the following are also defined...
+Additionally, the following properties are also defined...
 
-* `.rewind()` - Rewind the current position to the start of the stream. Some implementations may raise a `ValueError`. For example file streams are rewindable, while http streams are not.
-* `.size` - *(int or None)* Return an integer indicating the size of the stream, or `None` if the size is unknown. When working with HTTP/1.1 streams with a known size will include a `Content-Length: <size>` header, while unsized streams will include a `Content-Encoding: chunked` header and use chunked transfer framing.
+* `.size` - *(int or None)* Return an integer indicating the size of the stream, or `None` if the size is unknown. When working with HTTP this is used to either set a `Content-Length: <size>` header, or a `Content-Encoding: chunked` header.
+* `.content_type` - *(str or None)* Return a string indicating the content type of the data, or `None` if the content type is unknown. When working with HTTP this is used to optionally set a `Content-Type` header.
 
 The `Stream` interface and `ContentType` interface are closely related, with streams being used as the abstraction for the bytewise representation, and content types being used to encapsulate the parsed data structure.
 
 For example, encoding some `JSON` data...
 
 ```python
 >>> data = httpx.JSON({'name': 'zelda', 'score': '478'})
->>> stream, ct_header = data.encode()
+>>> stream = data.encode()
 >>> stream.read()
 b'{"name":"zelda","score":"478"}'
->>> ct_header
+>>> stream.content_type
 'application/json'
 ```
 
@@ -46,8 +45,10 @@ b'{"msg": "Hello, world!"}'
 
 A byte stream returning content from a file.
 
+The standard pattern for instantiating a `FileStream` is to use `File` as a context manager:
+
 ```python
->>> with httpx.FileStream.open('upload.json') as s:
+>>> with httpx.File('upload.json') as s:
 ...     s.read()
 b'{"msg": "Hello, world!"}'
 ```
@@ -56,9 +57,11 @@ b'{"msg": "Hello, world!"}'
 
 A byte stream returning multipart upload data.
 
+The standard pattern for instantiating a `MultiPartStream` is to use `MultiPart` as a context manager:
+
 ```python
 >>> files = {'avatar-upload': 'image.png'}
->>> with httpx.MultiPartStream(files=files) as s:
+>>> with httpx.MultiPart(files=files) as s:
 ...     s.read()
 # ...
 ```

src/ahttpx/_content.py

@@ -16,21 +16,9 @@
     "HTML",
 ]
 
-# https://github.com/nginx/nginx/blob/master/conf/mime.types
-_content_types = {
-    ".json": "application/json",
-    ".js": "application/javascript",
-    ".html": "text/html",
-    ".css": "text/css",
-    ".png": "image/png",
-    ".jpeg": "image/jpeg",
-    ".jpg": "image/jpeg",
-    ".gif": "image/gif",
-}
-
 
 class Content:
-    def encode(self) -> tuple[Stream, str]:
+    def encode(self) -> Stream:
         raise NotImplementedError()
 
 
@@ -73,11 +61,11 @@ def __init__(
 
     # Content API
 
-    def encode(self) -> tuple[Stream, str]:
-        stream = ByteStream(str(self).encode("ascii"))
+    def encode(self) -> Stream:
+        content = str(self).encode("ascii")
         content_type = "application/x-www-form-urlencoded"
-        return (stream, content_type)
-    
+        return ByteStream(content, content_type)
+
     # Dict operations
 
     def keys(self) -> typing.KeysView[str]:
@@ -172,17 +160,8 @@ def name(self) -> str:
     def size(self) -> int:
         return os.path.getsize(self._path)
 
-    def content_type(self) -> str:
-        _, ext = os.path.splitext(self._path)
-        ct = _content_types.get(ext, "application/octet-stream")
-        if ct.startswith('text/'):
-            ct += "; charset='utf-8'"
-        return ct
-
-    def encode(self) -> tuple[Stream, str]:
-        stream = FileStream.open(self._path)
-        content_type = self.content_type()
-        return (stream, content_type)
+    def encode(self) -> Stream:
+        return FileStream(self._path)
 
     def __lt__(self, other: typing.Any) -> bool:
         return isinstance(other, File) and other._path < self._path
@@ -249,7 +228,7 @@ def get_list(self, key: str) -> list[File]:
         return list(self._dict.get(key, []))
 
     # Content interface
-    def encode(self) -> tuple[Stream, str]:
+    def encode(self) -> Stream:
         return MultiPart(files=self).encode()
 
     # Builtins
@@ -282,16 +261,15 @@ class JSON(Content):
     def __init__(self, data: typing.Any) -> None:
         self._data = data
 
-    def encode(self) -> tuple[Stream, str]:
+    def encode(self) -> Stream:
         content = json.dumps(
             self._data,
             ensure_ascii=False,
             separators=(",", ":"),
             allow_nan=False
         ).encode("utf-8")
-        stream = ByteStream(content)
         content_type = "application/json"
-        return (stream, content_type)
+        return ByteStream(content, content_type)
 
     def __repr__(self) -> str:
         return f"<JSON {self._data!r}>"
@@ -301,10 +279,10 @@ class Text(Content):
     def __init__(self, text: str) -> None:
         self._text = text
 
-    def encode(self) -> tuple[Stream, str]:
-        stream = ByteStream(self._text.encode("utf-8"))
+    def encode(self) -> Stream:
+        content = self._text.encode("utf-8")
         content_type = "text/plain; charset='utf-8'"
-        return (stream, content_type)
+        return ByteStream(content, content_type)
 
     def __repr__(self) -> str:
         return f"<Text {self._text!r}>"
@@ -314,10 +292,10 @@ class HTML(Content):
     def __init__(self, text: str) -> None:
         self._text = text
 
-    def encode(self) -> tuple[Stream, str]:
-        stream = ByteStream(self._text.encode("utf-8"))
+    def encode(self) -> Stream:
+        content = self._text.encode("utf-8")
         content_type = "text/html; charset='utf-8'"
-        return (stream, content_type)
+        return ByteStream(content, content_type)
 
     def __repr__(self) -> str:
         return f"<HTML {self._text!r}>"
@@ -353,12 +331,10 @@ def form(self) -> Form:
     def files(self) -> Files:
         return self._files
 
-    def encode(self) -> tuple[Stream, str]:
+    def encode(self) -> Stream:
         form = [(key, value) for key, value in self._form.items()]
         files = [(key, file._path) for key, file in self._files.items()]
-        stream = MultiPartStream(form, files, boundary=self._boundary)
-        content_type = f"multipart/form-data; boundary={self._boundary}"
-        return (stream, content_type)
+        return MultiPartStream(form, files, boundary=self._boundary)
 
     def __repr__(self) -> str:
         return f"<MultiPart form={self._form.multi_items()!r}, files={self._files.multi_items()!r}>"

src/ahttpx/_headers.py

@@ -23,14 +23,14 @@
 
 def headername(name: str) -> str:
     if name.strip(VALID_HEADER_CHARS) or not name:
-        raise ValueError("Invalid HTTP header name {key!r}.")
+        raise ValueError(f"Invalid HTTP header name {name!r}.")
     return name
 
 
 def headervalue(value: str) -> str:
     value = value.strip(" ")
     if not value or not value.isascii() or not value.isprintable():
-        raise ValueError("Invalid HTTP header value {key!r}.")
+        raise ValueError(f"Invalid HTTP header value {value!r}.")
     return value
 
 

src/ahttpx/_request.py

@@ -34,11 +34,7 @@ def __init__(
             elif isinstance(content, Stream):
                 self.stream = content
             elif isinstance(content, Content):
-                assert isinstance(content, Content)
-                # Eg. Request("POST", "https://www.example.com", content=Form(...))
-                stream, content_type = content.encode()
-                self.headers = self.headers.copy_set("Content-Type", content_type)
-                self.stream = stream
+                self.stream = content.encode()
             else:
                 raise TypeError(f'Expected `Content | Stream | bytes | None` got {type(content)}')
 
@@ -54,6 +50,9 @@ def __init__(
             elif content_length > 0:
                 self.headers = self.headers.copy_set("Content-Length", str(content_length))
 
+            if self.stream.content_type is not None:
+                self.headers = self.headers.copy_set("Content-Type", self.stream.content_type)
+
     @property
     def body(self) -> bytes:
         if not hasattr(self, '_body'):

src/ahttpx/_response.py

@@ -94,10 +94,7 @@ def __init__(
             elif isinstance(content, Stream):
                 self.stream = content
             elif isinstance(content, Content):
-                # Eg. Response(200, content=HTML(...))
-                stream, content_type = content.encode()
-                self.headers = self.headers.copy_set("Content-Type", content_type)
-                self.stream = stream
+                self.stream = content.encode()
             else:
                 raise TypeError(f'Expected `Content | Stream | bytes | None` got {type(content)}')
 
@@ -114,6 +111,9 @@ def __init__(
             else:
                 self.headers = self.headers.copy_set("Content-Length", str(content_length))
 
+            if self.stream.content_type is not None:
+                self.headers = self.headers.copy_set("Content-Type", self.stream.content_type)
+
     @property
     def reason_phrase(self):
         return _codes.get(self.status_code, "Unknown Status Code")