mountaineer 0.4.2.dev3__tar.gz → 0.5.0.dev1__tar.gz

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/.gitignore

@@ -173,6 +173,7 @@ test-project
 _server
 _ssr
 _static
+_metadata
 
 # Ignore template files that might be used locally for testing
 # but shouldn't be added to the downstream templates

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/Cargo.lock

@@ -535,7 +535,7 @@ dependencies = [
 
 [[package]]
 name = "mountaineer"
-version = "0.4.2-dev3"
+version = "0.5.0-dev1"
 dependencies = [
  "criterion",
  "deno_core_icudata",

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/Cargo.toml

@@ -15,7 +15,7 @@ harness = false
 
 [package]
 name = "mountaineer"
-version = "0.4.2-dev3"
+version = "0.5.0-dev1"
 edition = "2021"
 
 [dependencies]

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mountaineer
-Version: 0.4.2.dev3
+Version: 0.5.0.dev1
 Requires-Dist: pydantic
 Requires-Dist: fastapi
 Requires-Dist: inflection

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/ci_webapp/ci_webapp/app.py

@@ -5,6 +5,7 @@ from ci_webapp.config import AppConfig
 from ci_webapp.controllers.complex import ComplexController
 from ci_webapp.controllers.detail import DetailController
 from ci_webapp.controllers.home import HomeController
+from ci_webapp.controllers.root_layout import RootLayoutController
 from ci_webapp.controllers.stream import StreamController
 
 controller = AppController(
@@ -20,3 +21,4 @@ controller.register(HomeController())
 controller.register(DetailController())
 controller.register(ComplexController())
 controller.register(StreamController())
+controller.register(RootLayoutController())

mountaineer-0.5.0.dev1/ci_webapp/ci_webapp/controllers/root_layout.py

@@ -0,0 +1,23 @@
+from mountaineer import LayoutControllerBase, RenderBase
+from mountaineer.actions import sideeffect
+
+
+class RootLayoutRender(RenderBase):
+    layout_value: int
+
+
+class RootLayoutController(LayoutControllerBase):
+    view_path = "/app/layout.tsx"
+
+    def __init__(self):
+        super().__init__()
+        self.layout_value = 0
+
+    def render(self) -> RootLayoutRender:
+        return RootLayoutRender(
+            layout_value=self.layout_value,
+        )
+
+    @sideeffect
+    async def increment_layout_value(self) -> None:
+        self.layout_value += 1

mountaineer-0.5.0.dev1/ci_webapp/ci_webapp/views/app/layout.tsx

@@ -0,0 +1,25 @@
+import React, { ReactNode } from "react";
+import { useServer } from "./_server";
+
+const Layout = ({ children }: { children: ReactNode }) => {
+  const serverState = useServer();
+
+  return (
+    <div className="p-6">
+      <h1>Layout State: {serverState.layout_value}</h1>
+      <div>{children}</div>
+      <div>
+        <button
+          className="rounded-md bg-indigo-500 p-2 text-white"
+          onClick={async () => {
+            await serverState.increment_layout_value();
+          }}
+        >
+          Layout increment
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Layout;

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/create_mountaineer_app/create_mountaineer_app/templates/editor_configs/vim/.vimrc

@@ -2,7 +2,9 @@
 set wildignore+=*/_server/*
 set wildignore+=*/_ssr/*
 set wildignore+=*/_static/*
+set wildignore+=*/_metadata/*
 set path-=*/_server/**
 set path-=*/_ssr/**
 set path-=*/_static/**
-{% endif %}
+set path-=*/_metadata/**
+{% endif %}

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/create_mountaineer_app/create_mountaineer_app/templates/editor_configs/vscode/.vscode/settings.json

@@ -3,7 +3,8 @@
   "files.exclude": {
     "_server/": true,
     "_ssr/": true,
+    "_metadata/": true,
     "_static/": true
   }
 }
-{% endif %}
+{% endif %}

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/create_mountaineer_app/create_mountaineer_app/templates/project/.gitignore

@@ -13,6 +13,7 @@ node_modules
 _server
 _ssr
 _static
+_metadata
 .watchdog.lock
 
 # General Python excludes

mountaineer-0.5.0.dev1/docs_website/docs/api/controller.md

@@ -0,0 +1,7 @@
+# View Controller
+
+::: mountaineer.controller.ControllerBase
+
+# Layout Controller
+
+::: mountaineer.controller_layout.LayoutControllerBase

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/docs_website/docs/deploy.md

@@ -11,6 +11,7 @@ First, add the following to your `.dockerignore` file. This will prevent Docker
 **/_server
 **/_ssr
 **/_static
+**/_metadata
 ```
 
 ### Image 1: Frontend Dependencies

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/docs_website/docs/quickstart.md

@@ -294,9 +294,9 @@ export default Home;
 
 Go ahead and load it in your browser. If you open up your web tools, you can create a new Todo and see POST requests sending data to the backend and receiving the current server state. The actual data updates and merging happens internally by Mountaineer.
 
-![Getting Started Final TODO App](/media/final_todo_list.png){ height="400" }
+![Getting Started Final TODO App](media/final_todo_list.png){ height="400" }
 
-![Getting Started Final TODO App](/media/network_debug.png){ height="400" }
+![Getting Started Final TODO App](media/network_debug.png){ height="400" }
 
 You can use these serverState variables anywhere you'd use dynamic React state variables (useEffect, useCallback, etc). But unlike React state, these variables are automatically updated when a relevant sideeffect is triggered.
 

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/docs_website/docs/views.md

@@ -1,4 +1,4 @@
-# Frontend Views
+# Frontend Views & Layouts
 
 Your React app should be initialized in the `/views` folder of your Mountaineer project. This is the directory where we look for package.json and tsconfig.json, and where esbuild looks for specific build-time overrides. In other words, the views folder should look just like your frontend application if you were building a Single-Page-App (SPA). It's just embedded within your larger Mountaineer project and rendered separately.
 
@@ -84,7 +84,82 @@ This allows you to chain layouts before rendering the final, most specific page:
     /layout.tsx
 ```
 
-When rendering `dashboard/home/page.tsx`, the view will be wrapped in the `app/dashboard/layout.tsx` layout alongside `app/layout.tsx`. These layouts should only provide styling. Since the use of `useServer` would be ambiguous for layouts that are rendered by multiple components, they should not contain any logic or data fetching.
+When rendering `dashboard/home/page.tsx`, the view will be wrapped in the `app/dashboard/layout.tsx` layout alongside `app/layout.tsx`. These layout files will be automatically found by Mountaineer during the build process. They don't require any explicit declaration in your Python backend if you're just using them for styling.
+
+If you need more server side power and want to define them in Python, you can add a LayoutController that backs the layout.
+
+## Layout Controllers
+
+Layouts support most of the same controller logic that regular pages do. They can specify their own actions, both sideeffects and passthroughs, which will re-render the layout as required.
+
+```python title="/controllers/root_layout.py"
+from mountaineer import LayoutControllerBase, RenderBase
+from mountaineer.actions import sideeffect
+
+class RootLayoutRender(RenderBase):
+    layout_value: int
+
+class RootLayoutController(LayoutControllerBase):
+    view_path = "/app/layout.tsx"
+
+    def __init__(self):
+        super().__init__()
+        self.layout_value = 0
+
+    def render(self) -> RootLayoutRender:
+        return RootLayoutRender(
+            layout_value=self.layout_value,
+        )
+
+    @sideeffect
+    async def increment_layout_value(self) -> None:
+        self.layout_value += 1
+```
+
+All these functions are now exposed to the frontend layout, including the link generator, state, and any actions specified.
+
+```typescript title="/views/app/layout.tsx"
+import React, { ReactNode } from "react";
+import { useServer } from "./_server";
+
+const Layout = ({ children }: { children: ReactNode }) => {
+  const serverState = useServer();
+
+  return (
+    <div className="p-6">
+      <h1>Layout State: {serverState.layout_value}</h1>
+      <div>{children}</div>
+      <div>
+        <button
+          className="rounded-md bg-indigo-500 p-2 text-white"
+          onClick={async () => {
+            await serverState.increment_layout_value();
+          }}
+        >
+          Increase Ticker
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Layout;
+```
+
+Once your controller is declared, you'll need to mount your layout into the AppController like you do for regular pages.
+
+```python title="/app.py"
+app_controller = AppController(...)
+app_controller.register(RootLayoutController())
+```
+
+In general you can implement layout controllers just like you do for pages. But since they're shared across multiple pages there are a few important differences to keep in mind:
+
+- Layout controllers will be rendered in an isolated scope. Sideeffects in one layout controller won't affect the others.
+- Dependency injections are similarly isolated. They are run in an isolated, synthetic context and not with the same dependency injection parameters that the page uses.
+- Layout controllers don't modify the page signature. Query params on layouts won't be extracted, for instance.
+
+As long as you write your layout controllers without directly referencing the page that they might be wrapping, which is the case for most layouts, you should be good to go.
 
 ## Typescript Configuration
 

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/docs_website/pyproject.toml

@@ -4,6 +4,7 @@ version = "0.1.0"
 description = ""
 authors = ["Pierce Freeman <pierce@freeman.vc>"]
 readme = "README.md"
+package-mode = false
 
 [tool.poetry.dependencies]
 python = "^3.11"

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__init__.py

@@ -6,6 +6,7 @@ from mountaineer.actions import passthrough as passthrough, sideeffect as sideef
 from mountaineer.app import AppController as AppController
 from mountaineer.config import ConfigBase as ConfigBase
 from mountaineer.controller import ControllerBase as ControllerBase
+from mountaineer.controller_layout import LayoutControllerBase as LayoutControllerBase
 from mountaineer.dependencies import CoreDependencies as CoreDependencies
 from mountaineer.exceptions import APIException as APIException
 from mountaineer.js_compiler.postcss import PostCSSBundler as PostCSSBundler

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/actions/test_fields.py

@@ -1,4 +1,4 @@
-from typing import AsyncIterator, Iterator, Optional, Type
+from typing import AsyncIterator, Iterator, Optional, Type, cast
 
 import pytest
 from fastapi.responses import JSONResponse
@@ -15,6 +15,7 @@ from mountaineer.actions.fields import (
     get_function_metadata,
 )
 from mountaineer.actions.sideeffect import sideeffect
+from mountaineer.controller import ControllerBase
 from mountaineer.render import Metadata, RenderBase
 
 
@@ -27,6 +28,11 @@ class ExamplePassthroughModel(BaseModel):
     passthrough_value_a: str
 
 
+class ExampleController(ControllerBase):
+    async def render(self) -> None:
+        pass
+
+
 def basic_compare_model_fields(
     actual: dict[str, FieldInfo],
     expected: dict[str, FieldInfo],
@@ -113,8 +119,16 @@ def test_fuse_metadata_to_response_typehint(
     expected_sideeffect_fields: dict[str, FieldInfo],
     expected_passthrough_fields: dict[str, FieldInfo],
 ):
-    fused_model = fuse_metadata_to_response_typehint(metadata, render_model)
+    sample_controller = ExampleController()
+    raw_model = fuse_metadata_to_response_typehint(
+        metadata, sample_controller, render_model
+    )
+
+    assert "ExampleController" in raw_model.model_fields.keys()
 
+    fused_model = cast(
+        BaseModel, raw_model.model_fields["ExampleController"].annotation
+    )
     if expected_sideeffect_fields:
         assert "sideeffect" in fused_model.model_fields.keys()
         assert fused_model.model_fields["sideeffect"].annotation
@@ -131,7 +145,7 @@ def test_fuse_metadata_to_response_typehint(
             expected_passthrough_fields,
         )
 
-    assert fused_model.__name__ == expected_model_name
+    assert raw_model.__name__ == expected_model_name
 
 
 class ParentRender(RenderBase):
@@ -143,7 +157,7 @@ class ChildRender(ParentRender):
 
 
 def test_fuse_metadata_to_response_typehint_inherit_render():
-    class ParentController(BaseModel):
+    class ParentController(ControllerBase):
         def render(self) -> ParentRender:
             return ParentRender(render_value_a="example")
 
@@ -157,6 +171,7 @@ def test_fuse_metadata_to_response_typehint_inherit_render():
 
     model_fused = fuse_metadata_to_response_typehint(
         get_function_metadata(ChildController.sideeffect),
+        ChildController(),
         ChildRender,
     )
     assert set(

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/actions/test_passthrough.py

@@ -100,9 +100,11 @@ async def test_can_call_passthrough():
 
     # The response payload should be the same both both sync and async endpoints
     expected_response = {
-        "passthrough": ExamplePassthroughModel(
-            status="success",
-        )
+        "TestController": {
+            "passthrough": ExamplePassthroughModel(
+                status="success",
+            )
+        }
     }
 
     assert return_value_sync == expected_response

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/actions/test_sideeffect.py

@@ -101,11 +101,13 @@ async def call_sideeffect_common(controller: ControllerCommon):
 
         # The response payload should be the same both both sync and async endpoints
         expected_response = {
-            "sideeffect": ExampleRenderModel(
-                value_a="Hello",
-                value_b="World",
-            ),
-            "passthrough": None,
+            controller.__class__.__name__: {
+                "sideeffect": ExampleRenderModel(
+                    value_a="Hello",
+                    value_b="World",
+                ),
+                "passthrough": None,
+            }
         }
 
         assert return_value_sync == expected_response
@@ -277,8 +279,10 @@ def test_limit_codepath_experimental(
     elapsed = (monotonic_ns() - start) / 1e9
     assert response.status_code == 200
     assert response.json() == {
-        "sideeffect": {
-            "value_a": "Hello 1229",
+        "ExampleController": {
+            "sideeffect": {
+                "value_a": "Hello 1229",
+            }
         }
     }
 

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/client_builder/test_builder.py

@@ -8,6 +8,7 @@ import pytest
 from mountaineer.app import AppController
 from mountaineer.client_builder.builder import ClientBuilder
 from mountaineer.controller import ControllerBase
+from mountaineer.controller_layout import LayoutControllerBase
 
 
 class ExampleHomeController(ControllerBase):
@@ -169,3 +170,51 @@ def test_cache_is_outdated_url_change(
     )
 
     assert builder.cache_is_outdated() is True
+
+
+def test_validate_unique_paths_exact_definition(
+    builder: ClientBuilder,
+):
+    """
+    Two controllers can't manage the same view path.
+
+    """
+
+    class ConflictingDetailController(ControllerBase):
+        url = "/detail/other_url/"
+        view_path = "/detail/page.tsx"
+
+        def render(self) -> None:
+            return None
+
+    builder.app.register(ConflictingDetailController())
+
+    # Raises for the same exact view path
+    with pytest.raises(
+        ValueError, match="duplicate view paths under controller management"
+    ):
+        builder.validate_unique_paths()
+
+
+def test_validate_unique_paths_conflicting_layout(
+    builder: ClientBuilder,
+):
+    """
+    Layouts need to be placed in their own directory. Even if the literal paths
+    under management are different we still need to throw a validation error.
+
+    """
+
+    class ConflictingLayoutController(LayoutControllerBase):
+        view_path = "/detail/layout.tsx"
+
+        def render(self) -> None:
+            return None
+
+    builder.app.register(ConflictingLayoutController())
+
+    # Raises for the same exact view path
+    with pytest.raises(
+        ValueError, match="duplicate view paths under controller management"
+    ):
+        builder.validate_unique_paths()

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/test_app.py

@@ -12,6 +12,7 @@ from mountaineer.app import AppController
 from mountaineer.client_builder.openapi import OpenAPIDefinition
 from mountaineer.config import ConfigBase
 from mountaineer.controller import ControllerBase
+from mountaineer.controller_layout import LayoutControllerBase
 from mountaineer.exceptions import APIException
 
 
@@ -43,6 +44,26 @@ def test_requires_render_return_value():
     app.register(TestControllerWithRenderMarkup())
 
 
+def test_validates_layouts_exclude_urls():
+    """
+    The app controller should reject the registration of layouts that specify
+    a url.
+
+    """
+
+    class TestLayoutController(LayoutControllerBase):
+        # Not allowed, but might typehint correctly because the ControllerBase
+        # superclass supports it.
+        url = "/layout_url"
+
+        async def render(self) -> None:
+            pass
+
+    app_controller = AppController(view_root=Path(""))
+    with pytest.raises(ValueError, match="are not directly mountable to the router"):
+        app_controller.register(TestLayoutController())
+
+
 def test_generate_openapi():
     class ExampleSubModel(BaseModel):
         sub_value: str
@@ -72,6 +93,7 @@ def test_generate_openapi():
         "TestExceptionActionResponse",
         "ExampleException",
         "ExampleSubModel",
+        "TestExceptionActionResponseRaw",
     }
 
 
@@ -133,6 +155,7 @@ def test_handle_conflicting_exception_names():
 
     assert openapi_definition.components.schemas.keys() == {
         "TestExceptionActionResponse",
+        "TestExceptionActionResponseRaw",
         "mountaineer.__tests__.test_1.ExampleException",
         "mountaineer.__tests__.test_2.ExampleException",
     }
@@ -199,6 +222,9 @@ def test_inherit_parent_spec():
     assert parent_controller.definition
     assert child_controller.definition
 
+    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
 

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/test_cli.py

@@ -100,7 +100,7 @@ def test_dev_thrown_exception_on_get(env_process: IsolatedEnvProcess):
         response = test_client.get("/")
         assert response.status_code == 500
         assert (
-            '<div id="root">Passthrough: {"exception":"This is a test",'
+            '<div id="root">Passthrough: {"ExceptionController":{"exception":"This is a test",'
             in response.text
         )
 

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/test_controller.py

@@ -2,7 +2,7 @@ from pathlib import Path
 
 import pytest
 
-from mountaineer.controller import ControllerBase
+from mountaineer.controller import BuildMetadata, ControllerBase
 from mountaineer.render import (
     LinkAttribute,
     MetaAttribute,
@@ -196,6 +196,7 @@ def test_resolve_paths(tmp_path: Path):
     view_base = tmp_path / "views"
     ssr_base = view_base / "_ssr"
     static_base = view_base / "_static"
+    metadata_base = view_base / "_metadata"
 
     controller = StubController()
     assert not controller.resolve_paths(view_base)
@@ -212,12 +213,18 @@ def test_resolve_paths(tmp_path: Path):
     (ssr_base / "stub_controller.js.map").touch()
     assert not controller.resolve_paths(view_base)
 
-    # Finally, create the static script file
     # Our hash has to be exactly 32 digits to match the regex
     static_base.mkdir()
     random_hash = "b5ecd0c4405374100d6ef93088b86898"
     (static_base / f"stub_controller-{random_hash}.js").touch()
     (static_base / f"stub_controller-{random_hash}.js.map").touch()
+    assert not controller.resolve_paths(view_base)
+
+    # Finally, create the metadata file
+    metadata_base.mkdir()
+    (metadata_base / "stub_controller.json").write_text(
+        BuildMetadata(view_path=Path()).model_dump_json()
+    )
     assert controller.resolve_paths(view_base)
 
     # Now ensure that the paths are correctly set

mountaineer-0.5.0.dev1/mountaineer/__tests__/test_controller_layout.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+import pytest
+
+from mountaineer.app import AppController
+from mountaineer.controller_layout import LayoutControllerBase
+
+
+class ExampleLayoutController(LayoutControllerBase):
+    async def render(self) -> None:
+        pass
+
+
+@pytest.mark.asyncio
+async def test_disallows_direct_rendering():
+    """
+    Layouts can't be rendered directly. They're intended for use
+    only as pages wrappers.
+
+    """
+    layout_controller = ExampleLayoutController()
+
+    with pytest.raises(NotImplementedError):
+        await layout_controller._generate_html(global_metadata={})
+
+    with pytest.raises(NotImplementedError):
+        layout_controller._generate_ssr_html({})
+
+
+def test_layout_registration():
+    """
+    Layout controllers must register with the AppController for them
+    to be used by client render controllers.
+
+    """
+    app_controller = AppController(view_root=Path(""))
+    layout_controller = ExampleLayoutController()
+
+    app_controller.register(layout_controller)
+    assert len(app_controller.controllers) == 1
+
+    assert app_controller.controllers[0].controller == layout_controller

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/test_paths.py

@@ -143,6 +143,7 @@ def test_managed_view_paths_code_directories(tmpdir):
     assert root_path.get_managed_code_dir() == root_path / "_server"
     assert root_path.get_managed_static_dir() == root_path / "_static"
     assert root_path.get_managed_ssr_dir() == root_path / "_ssr"
+    assert root_path.get_managed_metadata_dir() == root_path / "_metadata"
 
     # Non-root paths should only yield the server directory
     non_root_path = root_path / "subdir"

{mountaineer-0.4.2.dev3 → mountaineer-0.5.0.dev1}/mountaineer/__tests__/test_ssr.py

@@ -26,7 +26,7 @@ def test_ssr_speed_baseline():
         start = monotonic_ns()
         render_ssr(
             js_contents,
-            FakeModel(random_id=uuid4()),
+            FakeModel(random_id=uuid4()).model_dump(mode="json"),
             hard_timeout=1,
         )
         all_measurements.append((monotonic_ns() - start) / 1e9)
@@ -54,7 +54,9 @@ def test_ssr_timeout():
     with pytest.raises(TimeoutError):
         render_ssr(
             script=js_contents,
-            render_data=FakeWaitDurationModel(delay_loops=5, random_id=uuid4()),
+            render_data=FakeWaitDurationModel(
+                delay_loops=5, random_id=uuid4()
+            ).model_dump(mode="json"),
             hard_timeout=0.5,
         )
     assert ((monotonic_ns() - start) / 1e9) < 1.0
@@ -84,7 +86,7 @@ def test_ssr_exception_context():
     try:
         render_ssr(
             script=js_contents,
-            render_data=FakeModel(random_id=uuid4()),
+            render_data=FakeModel(random_id=uuid4()).model_dump(mode="json"),
             hard_timeout=0,
         )
     except V8RuntimeError as e: