add docs for responses

Author: ZeroIntensity

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added tests for headers
 - Updated repr for `Route`
 - Patched responses with three values
+- Documented responses and result protocol
 
 ## [1.0.0-alpha2] - 2023-09-9
 

docs/components.md docs/responses.mddocs/components.md renamed to docs/responses.md

@@ -1,6 +1,42 @@
-# Components
+# Responses
 
-## Using built-in components
+## Basics
+
+view.py allows you to return three things from a route: the body, the headers, and the status code.
+
+You can simply return these via a tuple:
+
+```py
+@app.get("/")
+async def index():
+    return "you are not worthy", 400, {"x-worthiness": "0"}
+```
+
+In fact, it can be in any order you want:
+
+```py
+@app.get("/")
+async def index():
+    return {"x-worthiness": "0"}, "you are not worthy", 400
+```
+
+### Result Protocol
+
+If you need to return a more complicated object, you can put a `__view_result__` function on it:
+
+```py
+class MyObject:
+    def __view_result__(self) -> str:
+        return "123"
+
+@app.get("/")
+async def index():
+    return MyObject()
+```
+
+## Components
+
+### Using built-in components
 
 You can import any standard HTML components from the `view.components` module:
 
@@ -36,7 +72,7 @@ The above would translate to the following HTML snippet:
 </html>
 ```
 
-### Children
+#### Children
 
 You can pass an infinite number of children to a component, and it will be translated to the proper HTML:
 
@@ -54,7 +90,7 @@ Would translate to:
 </div>
 ```
 
-## Attributes
+### Attributes
 
 All built in components come with their respected attributes, per the HTML specification:
 
@@ -64,15 +100,15 @@ async def index():
     return html(lang="en")
 ```
 
-### Classes
+#### Classes
 
 Since the `class` keyword is reserved in Python, view.py uses the parameter name `cls` instead:
 
 ```py
 div(cls="hello")
 ```
 
-## Custom Components
+### Custom Components
 
 There's no need for any fancy mechanics when making a custom component, so you can just use a normal function:
 

mkdocs.yml

@@ -7,7 +7,7 @@ nav:
     - Home: index.md
     - Creating an app: creating.md
     - Running: running.md
-    - Components: components.md
+    - Responses: responses.md
     - Parameters: parameters.md
 
 theme:

tests/test_app.py

@@ -56,3 +56,26 @@ async def index():
         assert res.status == 201
         assert res.message == "123"
         assert res.headers["a"] == "b"
+
+
+@test("result protocol")
+async def _():
+    app = new_app()
+
+    class MyObject:
+        def __view_result__(self) -> str:
+            return "hello"
+
+    @app.get("/")
+    async def index():
+        return MyObject()
+
+    @app.get("/multi")
+    async def multi():
+        return 201, MyObject()
+
+    async with app.test() as test:
+        assert (await test.get("/")).message == "hello"
+        res = await test.get("/multi")
+        assert res.message == "hello"
+        assert res.status == 201