Merge pull request #134 from piercefreeman/feature/update-docs-for-ne…

…w-website

Update docstrings for new website

Cargo.toml

@@ -53,3 +53,8 @@ harness = false
 path = "src/benches/lexers_benchmark.rs"
 name = "lexers_benchmark"
 harness = false
+
+[lints.rust]
+# Global allow to fix pymethods's macro expansion, which can't be
+# escaped with an inline #[allow]
+non_local_definitions = "allow"

mountaineer/__tests__/actions/test_passthrough_dec.py

@@ -188,7 +188,7 @@ async def test_can_call_iterable():
     assert isinstance(return_value_sync, StreamingResponse)
 
     # StreamingResponses are intended to be read by an ASGI server, so we'll use the TestClient to simulate one instead of calling directly
-    controller_definition = app.definition_for_controller(controller)
+    controller_definition = app._definition_for_controller(controller)
     passthrough_url = controller_definition.get_url_for_metadata(
         get_function_metadata(controller.get_data)
     )
@@ -229,7 +229,7 @@ def call_passthrough(self, payload: dict) -> JSONResponse:
     controller = ExampleController()
     app.register(controller)
 
-    controller_definition = app.definition_for_controller(controller)
+    controller_definition = app._definition_for_controller(controller)
 
     client = TestClient(app.app)
     response = client.post(

mountaineer/__tests__/actions/test_sideeffect_dec.py

@@ -322,7 +322,7 @@ def call_sideeffect(self, payload: dict) -> None:
     controller = ExampleController()
     app.register(controller)
 
-    controller_definition = app.definition_for_controller(controller)
+    controller_definition = app._definition_for_controller(controller)
     sideeffect_url = controller_definition.get_url_for_metadata(
         get_function_metadata(ExampleController.call_sideeffect)
     )

mountaineer/__tests__/test_app.py

@@ -224,14 +224,14 @@ def client_function(self) -> None:
     )
 
     # Test that the controller definitions remain separate
-    assert parent_controller.definition
-    assert child_controller.definition
+    assert parent_controller._definition
+    assert child_controller._definition
 
-    assert parent_controller.definition.render_router
-    assert child_controller.definition.render_router
+    assert parent_controller._definition.render_router
+    assert child_controller._definition.render_router
 
-    parent_routes = parent_controller.definition.render_router.routes
-    child_routes = child_controller.definition.render_router.routes
+    parent_routes = parent_controller._definition.render_router.routes
+    child_routes = child_controller._definition.render_router.routes
 
     assert len(parent_routes) == 1
     assert parent_routes[0].path == "/parent"  # type: ignore
@@ -287,7 +287,7 @@ class MockConfig(ConfigBase):
         mock_resolve_package_path.return_value = tmp_path
 
         app = AppController(config=MockConfig())
-        assert app.view_root == tmp_path / "views"
+        assert app._view_root == tmp_path / "views"
 
         assert mock_resolve_package_path.call_count == 1
         assert mock_resolve_package_path.call_args[0] == ("test_webapp",)
@@ -437,7 +437,7 @@ def target_fn(a: int, b: str):
     }
 
     app = AppController(view_root=Path(""))
-    assert app.get_value_mask_for_signature(
+    assert app._get_value_mask_for_signature(
         signature(target_fn),
         values,
     ) == {

mountaineer/__tests__/test_app_manager.py

@@ -213,7 +213,7 @@ async def test_handle_dev_exception(manager: DevAppManager):
         if controller.controller.__class__.__name__
         != manager.exception_controller.__class__.__name__
     ]
-    manager.app_controller.controller_names.remove(
+    manager.app_controller._controller_names.remove(
         manager.exception_controller.__class__.__name__
     )
 

mountaineer/__tests__/test_controller.py

@@ -45,6 +45,6 @@ def test_resolve_paths(tmp_path: Path):
     assert controller.resolve_paths(view_base)
 
     # Now ensure that the paths are correctly set
-    assert controller.view_base_path == view_base
-    assert controller.ssr_path == ssr_base / "stub_controller.js"
-    assert controller.bundled_scripts == [f"stub_controller-{random_hash}.js"]
+    assert controller._view_base_path == view_base
+    assert controller._ssr_path == ssr_base / "stub_controller.js"
+    assert controller._bundled_scripts == [f"stub_controller-{random_hash}.js"]

mountaineer/actions/passthrough_dec.py

@@ -88,25 +88,25 @@ def passthrough(*args, **kwargs):  # type: ignore
     `JSONResponse` if you need full flexibility on return headers and content structure.
 
     If you do return a JSONResponse note that we will handle the merging of the response for you - so
-    on the client side you will still access your endpoint contents with:
+    on the client side you will still access your endpoint contents as `response.passthrough`.
 
-    ```typescript
-    const response = await serverState.my_action({});
-    console.log(response.passthrough);
+    ```typescript {{ sticky: True }}
+    const response = await serverState.my_action({
+        name: "John Appleseed",
+    });
+    console.log(response.passthrough.name);
     ```
 
-    Usage:
-
-    ```python
+    ```python {{ sticky: True }}
     from pydantic import BaseModel
 
     class ResponseModel(BaseModel):
-        pass
+        name: str
 
     class MyController(ControllerBase):
         @passthrough
-        async def my_action(self) -> ResponseModel:
-            ...
+        async def my_action(self, name: str) -> ResponseModel:
+            return ResponseModel(name=name)
     ```
 
     :param exception_models: List of APIException subclasses that this function is known

mountaineer/actions/sideeffect_dec.py

@@ -79,6 +79,34 @@ def sideeffect(*args, **kwargs):  # type: ignore
     on return headers and content structure. Unlike @passthrough, it does not allow you to provide a non-JSON response since we need
     to internally merge it with render() sideeffect update.
 
+    ```python {{sticky: True}}
+    from mountaineer import sideeffect, RenderBase, ControllerBase, Depends
+    from iceaxe import DBConnection, select
+    from iceaxe.mountaineer import DatabaseDependencies
+
+    from myapp import models
+
+    class ControllerRender(RenderBase):
+        count: str
+
+    class MyController(ControllerBase):
+        async def render(
+            self,
+            db_connection: DBConnection = Depends(DatabaseDependencies.get_db_connection),
+        ) -> ControllerRender:
+            elements = await db_connection.exec(select(models.MyModel.id))
+            return ControllerRender(count=len(elements))
+
+        @sideeffect
+        async def increment_count(
+            self,
+            db_connection: DBConnection = Depends(DatabaseDependencies.get_db_connection),
+        ) -> None:
+            new_model = models.MyModel()
+            await db_connection.insert([new_model])
+
+    ```
+
     :param exception_models: List of APIException subclasses that this function is known
         to throw. These will be parsed and available to frontend clients.
     :type exception_models: list[Type[APIException]] | None
@@ -260,7 +288,7 @@ async def get_render_parameters(
         }
     )
 
-    if not controller.definition:
+    if not controller._definition:
         raise RuntimeError(
             "Controller definition is not set. This might indicate you're calling a"
             " sideeffect from outside of an AppController context."
@@ -272,8 +300,8 @@ async def get_render_parameters(
     # match non-relevant paths.
     # https://github.com/encode/starlette/blob/5c43dde0ec0917673bb280bcd7ab0c37b78061b7/starlette/routing.py#L544
     for route in (
-        controller.definition.render_router.routes
-        if controller.definition.render_router is not None
+        controller._definition.render_router.routes
+        if controller._definition.render_router is not None
         else []
     ):
         match, child_scope = route.matches(view_request.scope)