holm 0.1.0__tar.gz

holm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Volf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

holm-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.1
+Name: holm
+Version: 0.1.0
+Summary: Web development framework that brings the Next.js developer experience to Python, built on FastAPI, htmy, and FastHX.
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: fasthx>=2.3.3
+Requires-Dist: htmy[lxml]>=0.8.2
+Description-Content-Type: text/markdown
+
+![Tests](https://github.com/volfpeter/holm/actions/workflows/tests.yml/badge.svg)
+![Linters](https://github.com/volfpeter/holm/actions/workflows/linters.yml/badge.svg)
+![Documentation](https://github.com/volfpeter/holm/actions/workflows/build-docs.yml/badge.svg)
+![PyPI package](https://img.shields.io/pypi/v/holm?color=%2334D058&label=PyPI%20Package)
+
+**Source code**: [https://github.com/volfpeter/holm](https://github.com/volfpeter/holm)
+
+**Documentation and examples**: [https://volfpeter.github.io/holm](https://volfpeter.github.io/holm/)
+
+# holm
+
+Web development framework that brings the Next.js developer experience to Python, built on FastAPI, `htmy`, and FastHX.
+
+## Key features
+
+- **Next.js**-like **developer experience** with **file-system based routing** and page composition.
+- **Standard FastAPI** everywhere, so you can leverage the entire FastAPI ecosystem.
+- **No JavaScript** dependencies
+- **No build steps**, just server side rendering with **fully typed Python**.
+- **Async** support everywhere, from APIs and dependencies all the way to UI components, thanks to `htmy`.
+- Support for both **JSON** and **HTML** (server side rendering) APIs.
+- First class `HTMX` support thanks to `FastHX`.
+- **Stability** by building only on the core feature set of dependent libraries.
+- **Unopinionated**: use any CSS framework for styling and any JavaScript framework for UI interactivity.
+
+## Pre-requisite knowledge
+
+To get started, all you need is a basic understanding of:
+
+- [FastAPI](https://fastapi.tiangolo.com/tutorial/): the underlying web framework.
+- [htmy](https://volfpeter.github.io/htmy/): the used component / templating and rendering library.
+- HTML and CSS fundamentals.
+
+Familiarity with [FastHX](https://volfpeter.github.io/fasthx/) (the rendering layer between `htmy` and `FastAPI`), and especially its `htmy` integration is useful, but not necessary, unless you are building an HTMX application.
+
+It is recommended to use [HTMX](https://htmx.org/), if for nothing else, then to avoid hard page loads on navigation. [hx-boost](https://htmx.org/attributes/hx-boost/) (or navigation with `hx-get`) offers the same benefits as the `Link` component in Next.js.
+
+## Installation
+
+The package is available on PyPI and can be installed with:
+
+```bash
+pip install holm
+```
+
+Supported operating systems:
+
+- Linux
+- macOS
+- Windows: WSL only (native support may arrive in the future)
+
+## Support
+
+Consider supporting the development and maintenance of the project through [sponsoring](https://buymeacoffee.com/volfpeter), or reach out for [consulting](https://www.volfp.com/contact?subject=Consulting%20-%20holm) so you can get the most out of the library.
+
+## Application structure
+
+Similarly to Next.js, `holm` is built around the concept of file-system based routing. This essentially means that your code structure is automatically mapped to a matching API:
+
+- You do not need to manually define routes, every [application component](https://volfpeter.github.io/holm/application-components) is automatically discovered and registered in the application.
+- You do not need to manually wrap pages in their layouts, it is automatically done based on your application's code structure.
+
+You can find all the necessary details on the [Application component](https://volfpeter.github.io/holm/application-components) page, and the [Quick start guide](https://volfpeter.github.io/holm/quick-start-guide) can walk you through the process of creating your first application. The two are complementary documents, reading both is strongly recommended.
+
+HTML rendering is also fully automated, in the vast majority of cases you do not need to concern yourself with that (the only exceptions are HTML APIs, more on that below).
+
+All you need to do is follow these simple rules:
+
+- You must initialize your application instance using `holm.App()`. It optionally accepts a base `FastAPI` application and a `fasthx.htmy.HTMY` instance that handles HTML rendering.
+- `holm.App()` must be called directly within a module in your root application package to make automatic application discovery work.
+
+## Examples
+
+If you prefer to learn through examples, the [Quick start guide](https://volfpeter.github.io/holm/quick-start-guide) is the best place to start. The entire source code of the quick start guide application can be found in the [examples/quick-start-guide](https://github.com/volfpeter/holm/tree/main/examples/quick-start-guide) directory of the repository.
+
+You can discover even more features by exploring the [test application](https://github.com/volfpeter/holm/tree/main/test_app) of the project.
+
+If you are looking for the simplest possible application you can create, then can find it in the [examples/minimal](https://github.com/volfpeter/holm/tree/main/examples/minimal) directory of the repository.
+
+## Security
+
+At the moment, the library **does not** provide security features like automatic **CSRF prevention** out of the box. A custom form component and a corresponding middleware may be added to the library later, but of course 3rd party implementations are very welcome! Alternative solutions include JavaScript, but the library aims to remain unopinionated, especially on the client front. If you use HTMX, you should check out their [CSRF prevention](https://htmx.org/docs/#csrf-prevention) recommendation, just keep in mind that the `<body>` tag is not swapped for boosted requests.
+
+Also, do not forget about **XSS prevention**, when rendering untrusted data with custom components!
+
+## Development
+
+Development setup:
+
+- `uv` for project and dependency management.
+- `poethepoet` for running tasks. Run `uv run poe` to see all available tasks.
+- `mypy` for static code analysis.
+- `ruff` is used for formatting and linting.
+- `pytest` for testing.
+- `mkdocs-material` and `mkdocstrings` for documentation.
+
+Tests are located in the `tests` directory and they use the application defined in the `test_app` package (through a `TestClient`). This setup makes it possible to run `test_app` outside of tests, which is useful for debugging.
+
+You can run all tests with `uv run poe test`. You can separately start the test application with `uv run poe test-app`.
+
+## Contributing
+
+We welcome contributions from the community to help improve the project! Whether you're an experienced developer or just starting out, there are many ways you can contribute:
+
+- **Discuss**: Join our [Discussion Board](https://github.com/volfpeter/holm/discussions) to ask questions, share ideas, provide feedback, and engage with the community.
+- **Document**: Help improve the documentation by fixing typos, adding examples, and updating guides to make it easier for others to use the project.
+- **Develop**: Prototype requested features or pick up issues from the issue tracker.
+- **Test**: Write tests to improve coverage and reliability.
+
+## Comparison with other frameworks
+
+### Frameworks with JavaScript dependencies
+
+The most prominent frameworks in this category are Reflex and NiceGUI. They both provide a Python-first web development experience while using complex JavaScript frameworks under the hood for constructing user interfaces (namely React and Vue.js). They take care of state management and synchronization (using WebSockets), seamlessly connecting the JavaScript frontend and the Python backend. In exchange for this convenience comes complexity and heavy reliance on the ever-changing JavaScript ecosystem.
+
+`holm` comes with no JavaScript dependencies, but that doesn't mean you can't use JavaScript to add frontend interactivity. In fact, it comes with first class [HTMX](https://htmx.org/) support and naturally works with frameworks like [Alpine.js](https://alpinejs.dev/). Web component frameworks like [lit](https://lit.dev/), and even [React](https://react.dev/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page) application segments can also be integrated, just like into any server rendered page.
+
+### Pure server-side rendering frameworks
+
+This category includes frameworks like FastHTML or Ludic, and this is where `holm` belongs as well, but it has some key differentiators.
+
+First, `holm` brings the Next.js developer experience to Python with file-system based routing, automatic layout composition, and dynamic page metadata creation, and more. Thanks to `htmy`, it supports async code throughout the stack, even in components, and it also solves the prop drilling problem. While being built with `htmy`, it is easy to integrate with other templating libraries, like `Jinja` or `htpy`. And it provides all these features using standard, simple FastAPI patterns.
+
+## License
+
+The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).

holm-0.1.0/README.md

@@ -0,0 +1,126 @@
+![Tests](https://github.com/volfpeter/holm/actions/workflows/tests.yml/badge.svg)
+![Linters](https://github.com/volfpeter/holm/actions/workflows/linters.yml/badge.svg)
+![Documentation](https://github.com/volfpeter/holm/actions/workflows/build-docs.yml/badge.svg)
+![PyPI package](https://img.shields.io/pypi/v/holm?color=%2334D058&label=PyPI%20Package)
+
+**Source code**: [https://github.com/volfpeter/holm](https://github.com/volfpeter/holm)
+
+**Documentation and examples**: [https://volfpeter.github.io/holm](https://volfpeter.github.io/holm/)
+
+# holm
+
+Web development framework that brings the Next.js developer experience to Python, built on FastAPI, `htmy`, and FastHX.
+
+## Key features
+
+- **Next.js**-like **developer experience** with **file-system based routing** and page composition.
+- **Standard FastAPI** everywhere, so you can leverage the entire FastAPI ecosystem.
+- **No JavaScript** dependencies
+- **No build steps**, just server side rendering with **fully typed Python**.
+- **Async** support everywhere, from APIs and dependencies all the way to UI components, thanks to `htmy`.
+- Support for both **JSON** and **HTML** (server side rendering) APIs.
+- First class `HTMX` support thanks to `FastHX`.
+- **Stability** by building only on the core feature set of dependent libraries.
+- **Unopinionated**: use any CSS framework for styling and any JavaScript framework for UI interactivity.
+
+## Pre-requisite knowledge
+
+To get started, all you need is a basic understanding of:
+
+- [FastAPI](https://fastapi.tiangolo.com/tutorial/): the underlying web framework.
+- [htmy](https://volfpeter.github.io/htmy/): the used component / templating and rendering library.
+- HTML and CSS fundamentals.
+
+Familiarity with [FastHX](https://volfpeter.github.io/fasthx/) (the rendering layer between `htmy` and `FastAPI`), and especially its `htmy` integration is useful, but not necessary, unless you are building an HTMX application.
+
+It is recommended to use [HTMX](https://htmx.org/), if for nothing else, then to avoid hard page loads on navigation. [hx-boost](https://htmx.org/attributes/hx-boost/) (or navigation with `hx-get`) offers the same benefits as the `Link` component in Next.js.
+
+## Installation
+
+The package is available on PyPI and can be installed with:
+
+```bash
+pip install holm
+```
+
+Supported operating systems:
+
+- Linux
+- macOS
+- Windows: WSL only (native support may arrive in the future)
+
+## Support
+
+Consider supporting the development and maintenance of the project through [sponsoring](https://buymeacoffee.com/volfpeter), or reach out for [consulting](https://www.volfp.com/contact?subject=Consulting%20-%20holm) so you can get the most out of the library.
+
+## Application structure
+
+Similarly to Next.js, `holm` is built around the concept of file-system based routing. This essentially means that your code structure is automatically mapped to a matching API:
+
+- You do not need to manually define routes, every [application component](https://volfpeter.github.io/holm/application-components) is automatically discovered and registered in the application.
+- You do not need to manually wrap pages in their layouts, it is automatically done based on your application's code structure.
+
+You can find all the necessary details on the [Application component](https://volfpeter.github.io/holm/application-components) page, and the [Quick start guide](https://volfpeter.github.io/holm/quick-start-guide) can walk you through the process of creating your first application. The two are complementary documents, reading both is strongly recommended.
+
+HTML rendering is also fully automated, in the vast majority of cases you do not need to concern yourself with that (the only exceptions are HTML APIs, more on that below).
+
+All you need to do is follow these simple rules:
+
+- You must initialize your application instance using `holm.App()`. It optionally accepts a base `FastAPI` application and a `fasthx.htmy.HTMY` instance that handles HTML rendering.
+- `holm.App()` must be called directly within a module in your root application package to make automatic application discovery work.
+
+## Examples
+
+If you prefer to learn through examples, the [Quick start guide](https://volfpeter.github.io/holm/quick-start-guide) is the best place to start. The entire source code of the quick start guide application can be found in the [examples/quick-start-guide](https://github.com/volfpeter/holm/tree/main/examples/quick-start-guide) directory of the repository.
+
+You can discover even more features by exploring the [test application](https://github.com/volfpeter/holm/tree/main/test_app) of the project.
+
+If you are looking for the simplest possible application you can create, then can find it in the [examples/minimal](https://github.com/volfpeter/holm/tree/main/examples/minimal) directory of the repository.
+
+## Security
+
+At the moment, the library **does not** provide security features like automatic **CSRF prevention** out of the box. A custom form component and a corresponding middleware may be added to the library later, but of course 3rd party implementations are very welcome! Alternative solutions include JavaScript, but the library aims to remain unopinionated, especially on the client front. If you use HTMX, you should check out their [CSRF prevention](https://htmx.org/docs/#csrf-prevention) recommendation, just keep in mind that the `<body>` tag is not swapped for boosted requests.
+
+Also, do not forget about **XSS prevention**, when rendering untrusted data with custom components!
+
+## Development
+
+Development setup:
+
+- `uv` for project and dependency management.
+- `poethepoet` for running tasks. Run `uv run poe` to see all available tasks.
+- `mypy` for static code analysis.
+- `ruff` is used for formatting and linting.
+- `pytest` for testing.
+- `mkdocs-material` and `mkdocstrings` for documentation.
+
+Tests are located in the `tests` directory and they use the application defined in the `test_app` package (through a `TestClient`). This setup makes it possible to run `test_app` outside of tests, which is useful for debugging.
+
+You can run all tests with `uv run poe test`. You can separately start the test application with `uv run poe test-app`.
+
+## Contributing
+
+We welcome contributions from the community to help improve the project! Whether you're an experienced developer or just starting out, there are many ways you can contribute:
+
+- **Discuss**: Join our [Discussion Board](https://github.com/volfpeter/holm/discussions) to ask questions, share ideas, provide feedback, and engage with the community.
+- **Document**: Help improve the documentation by fixing typos, adding examples, and updating guides to make it easier for others to use the project.
+- **Develop**: Prototype requested features or pick up issues from the issue tracker.
+- **Test**: Write tests to improve coverage and reliability.
+
+## Comparison with other frameworks
+
+### Frameworks with JavaScript dependencies
+
+The most prominent frameworks in this category are Reflex and NiceGUI. They both provide a Python-first web development experience while using complex JavaScript frameworks under the hood for constructing user interfaces (namely React and Vue.js). They take care of state management and synchronization (using WebSockets), seamlessly connecting the JavaScript frontend and the Python backend. In exchange for this convenience comes complexity and heavy reliance on the ever-changing JavaScript ecosystem.
+
+`holm` comes with no JavaScript dependencies, but that doesn't mean you can't use JavaScript to add frontend interactivity. In fact, it comes with first class [HTMX](https://htmx.org/) support and naturally works with frameworks like [Alpine.js](https://alpinejs.dev/). Web component frameworks like [lit](https://lit.dev/), and even [React](https://react.dev/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page) application segments can also be integrated, just like into any server rendered page.
+
+### Pure server-side rendering frameworks
+
+This category includes frameworks like FastHTML or Ludic, and this is where `holm` belongs as well, but it has some key differentiators.
+
+First, `holm` brings the Next.js developer experience to Python with file-system based routing, automatic layout composition, and dynamic page metadata creation, and more. Thanks to `htmy`, it supports async code throughout the stack, even in components, and it also solves the prop drilling problem. While being built with `htmy`, it is easy to integrate with other templating libraries, like `Jinja` or `htpy`. And it provides all these features using standard, simple FastAPI patterns.
+
+## License
+
+The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).

holm-0.1.0/holm/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.1.0"
+
+from .app import App as App
+from .fastapi import FastAPIDependency as FastAPIDependency
+from .fastapi import FastAPIErrorHandler as FastAPIErrorHandler
+from .modules._error import ErrorHandlerMapping as ErrorHandlerMapping
+from .modules._metadata import Metadata as Metadata

holm-0.1.0/holm/_model.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib import import_module
+from pathlib import Path
+from typing import Any, TypeGuard, TypeVar
+
+from .typing import ModuleName, URLSegment
+
+_TModule = TypeVar("_TModule")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class AppConfig:
+    """
+    Stores basic configuration Information about the application.
+    """
+
+    root_dir: Path
+    """The root directory (as in Python import root)."""
+
+    app_dir_name: str
+    """The name of the application directory/package."""
+
+    app_url_prefix_length: int
+    """The length of the application URL prefix to remove (`len(app_dir_name) + 1`)."""
+
+    app_dir: Path
+    """Path to the application directory."""
+
+    # Overriding __init__ and calculating inferred values automatically would serve the
+    # default case well, but it would complicate things if we ever need to support
+    # different application structures (for example an app in tests). So we use
+    # alternative initializers instead.
+
+    @classmethod
+    def default(cls) -> AppConfig:
+        """
+        Creates a default instance for the standard application configuration.
+
+        Raises:
+            ValueError: If the application package cannot be determined.
+        """
+        root_dir = Path.cwd()
+        app_dir_name = cls._find_app_package_name()
+        len_app_dir_name = len(app_dir_name)
+
+        return cls(
+            root_dir=root_dir,
+            app_dir_name=app_dir_name,
+            # Support applications that are not wrapped in a Python package.
+            # In that case app_dir_name is "".
+            app_url_prefix_length=len_app_dir_name + 1 if len_app_dir_name > 0 else 0,
+            app_dir=root_dir / app_dir_name,
+        )
+
+    @classmethod
+    def _find_app_package_name(cls) -> str:
+        """
+        Attempts to find and return the application package name.
+
+        The method uses the assumption that the application package is the one from which
+        the call stack directly led to this library.
+
+        Raises:
+            ValueError: If the application package cannot be determined.
+        """
+        # We assume the app package is the one from which the call stack led to this library.
+        lib_root = __name__.split(".")[0]
+        stack = inspect.stack()
+        for i in range(1, len(stack)):
+            caller_frame = stack[i]
+            caller_module = inspect.getmodule(caller_frame.frame)
+            caller_package = caller_module.__package__ if caller_module else None
+            if caller_package is None:
+                break  # Couldn't find app package.
+
+            if not caller_package.startswith(lib_root):
+                # The call stack is no longer in this library, so we've found the app package.
+                return caller_package
+
+        raise ValueError("Could not determine the application package.")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PackageInfo:
+    """
+    Information about a single package.
+
+    This class most importantly describes how a package can be imported and
+    what should be the web URL of its contents.
+    """
+
+    package_dir: Path
+    """
+    Relative path to the package directory.
+
+    It is basically the path matching the package name / import path.
+    """
+
+    package_name: str
+    """
+    The import name (path) of the package.
+    """
+
+    url: str
+    """
+    The web URL for the contents of the package.
+    """
+
+    def __hash__(self) -> int:
+        return hash((PackageInfo, self.package_name))
+
+    def import_module(
+        self, name: ModuleName, validate: Callable[[Any], TypeGuard[_TModule]]
+    ) -> _TModule | None:
+        """
+        Imports the module with the given name from the package.
+
+        Arguments:
+            name: The name of the module to import.
+            validate: A function that validates the imported module.
+
+        Returns:
+            The imported module or `None` if the module does not exist.
+
+        Raises:
+            ValueError: If the module is invalid.
+        """
+        # Check if the module exists. Trying to import it and catching the exception would hide possible
+        # import error that occur in within the module, which is undesired because it would be hard for
+        # users to find why an API is not registered.
+        if not (self.package_dir / f"{name}.py").is_file():
+            return None
+
+        # Support applications that are not wrapped in a Python package.
+        # In that case `self.package_name` is ".".
+        module = import_module(name if self.package_name == "." else f"{self.package_name}.{name}")
+
+        if not validate(module):
+            raise ValueError(f"Invalid module: {name}")
+
+        return module
+
+    @classmethod
+    def from_marker_file(cls, file_path: Path, *, config: AppConfig) -> PackageInfo:
+        """
+        Creates a `PackageInfo` instance from a so called "marker" that is located in the package.
+        """
+        package_dir = file_path.relative_to(config.root_dir).parent
+        package_dir_str = str(package_dir)
+        package_name = package_dir_str.replace("/", ".")
+        # Create the base version of the URL
+        url = "/" if package_dir_str == "." else f"/{package_dir_str[config.app_url_prefix_length :]}"
+        # Technically there can be packages/directories with names like `{name}`. They can be
+        # directly used as URL segments and they could even be imported with `import_module()`,
+        # but they are invalid package names and static code analysis tools rightly complain
+        # about them, so we need an alternative option.
+        # That option is to use the `_name_` pattern instead and convert such package/directory
+        # names to the `{name}` format here and use that as the URL segment.
+        url = "/".join(
+            (f"{{{p[1:-1]}}}" if len(p) > 2 and p[0] == p[-1] == "_" else p for p in url.split("/"))
+        )
+        return cls(package_dir=package_dir, package_name=package_name, url=url)
+
+    def __lt__(self, other: PackageInfo) -> bool:
+        return self.package_name < other.package_name
+
+
+@dataclass(frozen=True, slots=True)
+class AppNode:
+    """
+    The description of an application tree.
+    """
+
+    url: str
+    """The full URL of this node."""
+
+    subtree: dict[URLSegment, AppNode] = field(default_factory=dict)
+    """
+    Maps sub-URLs to child nodes.
+    """
+
+    _package: PackageInfo | None = None
+    """The package that belongs to this node."""
+
+    @property
+    def last_url_segment(self) -> URLSegment:
+        """The last URL segment of this node."""
+        return f"/{self.url.rsplit('/', 1)[1]}"
+
+    @property
+    def package(self) -> PackageInfo | None:
+        """The package that belongs to this node."""
+        return self._package
+
+    def add(self, item: PackageInfo) -> None:
+        """
+        Adds the given package to this node.
+
+        If the package belongs in the subtree and not directly to this node, then the
+        entire subtree is created automatically.
+        """
+        self_url = self.url
+        if not item.url.startswith(self_url):
+            raise ValueError(f"{item.url} must start with {self_url}")
+
+        if item.url == self_url:
+            if self._package is not None:
+                raise ValueError(
+                    (
+                        f"Package already set for {self_url}: "
+                        f"current is {self._package.package_name} "
+                        f"new is {item.package_name}"
+                    )
+                )
+
+            # Class is frozen so this is only way to set _package.
+            object.__setattr__(self, "_package", item)
+            return
+
+        if self_url == "/":  # Root node
+            sub_url = item.url
+            url_prefix = ""
+        else:
+            sub_url = item.url.removeprefix(self_url)
+            url_prefix = self_url
+
+        first_segment: URLSegment = f"/{sub_url.split('/', 2)[1]}"  # First segment after leading slash
+        child = self.subtree.get(first_segment)
+        if child is None:
+            # The URL for this node must be constructed this way to not skip intermediate nodes
+            # that may not have a discovered package.
+            child = AppNode(f"{url_prefix}{first_segment}")
+            self.subtree[first_segment] = child
+
+        child.add(item)

holm-0.1.0/holm/app.py

@@ -0,0 +1,166 @@
+import inspect
+from collections.abc import Awaitable, Iterable
+from typing import cast
+
+from fastapi import APIRouter, Depends, FastAPI
+from fastapi.responses import HTMLResponse
+from fasthx.htmy import HTMY
+from htmy import Component, as_component_type
+
+from ._model import AppConfig, AppNode, PackageInfo
+from .fastapi import FastAPIDependency
+from .modules._api import PlainAPIFactory, RenderingAPIFactory, is_api_definition
+from .modules._error import is_error_handler_owner, register_error_handlers
+from .modules._layout import (
+    LayoutFactory,
+    combine_layouts_to_dependency,
+    empty_layout_dependency,
+    is_layout_definition,
+)
+from .modules._metadata import MetadataMapping, components_with_metadata, get_metadata_dependency
+from .modules._page import is_page_definition
+from .typing import module_names
+
+
+def App(*, app: FastAPI | None = None, htmy: HTMY | None = None) -> FastAPI:
+    """
+    Creates a FastAPI application with all the routes that are defined in the application package.
+
+    Arguments:
+        app: Optional FastAPI application to use. If `None`, a new instance will be created.
+        htmy: Optional `fasthx.htmy.HTMY` instance to use for server-side rendering. If `None`,
+            a default instance will be created.
+    """
+    if app is None:
+        app = FastAPI()
+
+    if htmy is None:
+        htmy = HTMY()
+
+    config = AppConfig.default()
+    packages = _discover_app_packages(config)
+    root_node = _build_app_tree(packages)
+
+    # Register error handlers
+    if pkg := root_node.package:
+        register_error_handlers(app, pkg.import_module("error", is_error_handler_owner), htmy=htmy)
+
+    # Build the API
+    app.include_router(_build_api(root_node, htmy=htmy))
+
+    return app
+
+
+def _build_api(
+    node: AppNode,
+    *,
+    base_layout_dep: FastAPIDependency[LayoutFactory] = empty_layout_dependency,
+    htmy: HTMY,
+) -> APIRouter:
+    """
+    Recursively builds an `APIRouter` based on the application defined by `node`.
+
+    Arguments:
+        node: Application definition.
+        base_layout: The base layout dependency to use for the API.
+        htmy: The `fasthx.htmy.HTMY` instance to use for server-side rendering.
+    """
+    layout_dep = base_layout_dep  # In case there is no package or it has no layout module.
+    pkg = node.package
+    api = _make_api_router_for_package(pkg, htmy)
+    if pkg is not None:
+        layout_module = pkg.import_module("layout", is_layout_definition)
+        page_module = pkg.import_module("page", is_page_definition)
+
+        layout_dep = combine_layouts_to_dependency(
+            base_layout_dep, None if layout_module is None else layout_module.layout
+        )
+        page_dep = None if page_module is None else page_module.page
+
+        if page_dep is not None:
+            metadata_dep = get_metadata_dependency(page_module)
+
+            async def path_operation(
+                layout: LayoutFactory = Depends(layout_dep),  # noqa: B008
+                metadata: MetadataMapping | None = Depends(metadata_dep),  # noqa: B008
+                page: Component = Depends(page_dep),  # noqa: B008
+            ) -> tuple[Component, MetadataMapping | None]:
+                result = layout(as_component_type(page))
+                # We must await here if result is an Awaitable, otherwise we would pass an
+                # awaitable to htmy.page() and rendering that would fail.
+                if isinstance(result, Awaitable):
+                    result = await result
+
+                return result, metadata
+
+            # Register the route with rendering.
+            api.get(
+                "/",
+                response_class=HTMLResponse,
+                response_model=None,
+                name="page",
+                description=page_dep.__doc__,
+                tags=["Page"],
+            )(htmy.page(components_with_metadata)(path_operation))
+
+    for sub_url, child_node in node.subtree.items():
+        api.include_router(
+            _build_api(child_node, base_layout_dep=layout_dep, htmy=htmy),
+            prefix=sub_url,
+        )
+
+    return api
+
+
+def _build_app_tree(packages: Iterable[PackageInfo]) -> AppNode:
+    """
+    Returns an `AppNode` that represents the entire package tree of the application.
+
+    Arguments:
+        packages: The packages to include in the tree.
+    """
+    root = AppNode("/")
+
+    for p in packages:
+        root.add(p)
+
+    return root
+
+
+def _discover_app_packages(config: AppConfig) -> set[PackageInfo]:
+    """
+    Discovers all packages that are part of the application and returns them as a set.
+    """
+    return {
+        PackageInfo.from_marker_file(f, config=config)
+        for f in config.app_dir.rglob("*.py")
+        if f.stem in module_names
+    }
+
+
+def _make_api_router_for_package(pkg: PackageInfo | None, htmy: HTMY) -> APIRouter:
+    """
+    Creates an `APIRouter` for the given package.
+    """
+    api_module = None if pkg is None else pkg.import_module("api", is_api_definition)
+    if api_module is None:
+        return APIRouter()
+
+    # api is either an APIRouter or a callable (is_api_definition validates that).
+    api = api_module.api
+    if isinstance(api, APIRouter):
+        return api
+
+    # Inspect the api callable instead of catching errors. Using a try-except with
+    # a TypeError handler would hide many potential issues that would then be
+    # hard to figure out without the exception trace.
+    num_params = len(inspect.signature(api).parameters)
+    if num_params == 0:
+        api = cast(PlainAPIFactory, api)()
+    elif num_params == 1:
+        api = cast(RenderingAPIFactory, api)(htmy)
+
+    if isinstance(api, APIRouter):
+        return api
+
+    raise ValueError(f"The api function of {cast(PackageInfo, pkg).package_name} must return an APIRouter.")

holm-0.1.0/holm/fastapi.py

@@ -0,0 +1,15 @@
+from collections.abc import Callable, Coroutine
+from typing import Any, TypeAlias, TypeVar
+
+from fastapi import Request
+
+_T = TypeVar("_T")
+
+SyncFastAPIDependency: TypeAlias = Callable[..., _T]
+AsyncFastAPIDependency: TypeAlias = Callable[..., Coroutine[None, None, _T]]
+
+FastAPIDependency: TypeAlias = SyncFastAPIDependency[_T] | AsyncFastAPIDependency[_T]
+"""FastAPI dependency typing."""
+
+FastAPIErrorHandler: TypeAlias = Callable[[Request, Exception], Coroutine[None, None, Any]]
+"""Generic FastAPI error handler typing."""

holm-0.1.0/holm/modules/_api.py

@@ -0,0 +1,34 @@
+from collections.abc import Callable
+from typing import Any, Protocol, TypeAlias, TypeGuard
+
+from fastapi import APIRouter
+from fasthx.htmy import HTMY
+
+PlainAPIFactory: TypeAlias = Callable[[], APIRouter]
+RenderingAPIFactory: TypeAlias = Callable[[HTMY], APIRouter]
+
+APIFactory: TypeAlias = PlainAPIFactory | RenderingAPIFactory
+"""
+`APIRouter` factory definition.
+
+It is a callable that optionally accepts an `HTMY` instance as an argument to make sure
+the same renderer is used throughout the application if the API does HTML rendering.
+Otherwise the argument can be omitted.
+"""
+
+
+class APIDefinition(Protocol):
+    """Protocol definition for objects (usually modules) that define an API."""
+
+    @property
+    def api(self) -> APIFactory | APIRouter:
+        """
+        The property may be an `APIFactory` or a plain `APIRouter` instance."""
+        ...
+
+
+def is_api_definition(obj: Any) -> TypeGuard[APIDefinition]:
+    """Type guard for `APIDefinition`."""
+    api = getattr(obj, "api", None)
+    # Check APIRouter first, because that's also callable.
+    return isinstance(api, APIRouter) or callable(api)

holm-0.1.0/holm/modules/_error.py

@@ -0,0 +1,68 @@
+from collections.abc import Callable, Mapping
+from typing import Any, Protocol, TypeAlias, TypeGuard
+
+from fastapi import FastAPI, Request, Response
+from fastapi.responses import HTMLResponse
+from fasthx.htmy import HTMY
+
+from holm.fastapi import FastAPIErrorHandler
+
+ErrorHandlerMapping: TypeAlias = Mapping[type[Exception] | int, FastAPIErrorHandler]
+"""
+Mapping whose keys are exception types or HTTP status codes, and the corresponding
+values are FastAPI error handlers.
+"""
+
+
+class ErrorHandlerOwner(Protocol):
+    """
+    Protocol definition for objects (usually modules) that define FastAPI exception handlers.
+    """
+
+    @property
+    def handlers(self) -> ErrorHandlerMapping | Callable[[HTMY], ErrorHandlerMapping]: ...
+
+
+def is_error_handler_owner(obj: Any) -> TypeGuard[ErrorHandlerOwner]:
+    """Type guard for `ErrorHandlerOwner`."""
+    handlers = getattr(obj, "handlers", None)
+    return handlers is not None and (isinstance(handlers, Mapping) or callable(handlers))
+
+
+def register_error_handlers(app: FastAPI, owner: ErrorHandlerOwner | None, *, htmy: HTMY) -> None:
+    """
+    Registers the error handlers defined by the given owner on the application.
+
+    Arguments:
+        app: The FastAPI application instance.
+        owner: The error handler owner, if any.
+        htmy: The HTMY instance.
+    """
+    if owner is None:
+        return
+
+    handlers = owner.handlers
+    handler_mapping: ErrorHandlerMapping = handlers(htmy) if callable(handlers) else handlers
+    for key, handler in handler_mapping.items():
+        app.exception_handler(key)(wrap_error_handler(handler, htmy))
+
+
+def wrap_error_handler(error_handler: FastAPIErrorHandler, htmy: HTMY) -> FastAPIErrorHandler:
+    """
+    Wraps the given error handler in a function that automatically renders `htmy` `Component` return values.
+    """
+
+    async def rendering_error_handler_wrapper(request: Request, error: Exception) -> Response:
+        result = await error_handler(request, error)
+        if isinstance(result, Response):
+            return result
+
+        try:
+            return HTMLResponse(await htmy.render_component(result, request))
+        except Exception as e:
+            raise ValueError(
+                "HTML rendering failed. Make sure your error handler returns "
+                "either a FastAPI.Response or an htmy.Component!"
+            ) from e
+
+    return rendering_error_handler_wrapper

holm-0.1.0/holm/modules/_layout.py

@@ -0,0 +1,141 @@
+import inspect
+from asyncio import iscoroutinefunction
+from collections.abc import Awaitable, Callable, Coroutine
+from typing import Any, Protocol, TypeAlias, TypeGuard
+
+from fastapi import Depends
+from htmy import as_component_type
+
+from holm.fastapi import FastAPIDependency
+
+
+class SyncLayout(Protocol):
+    """
+    Sync layout protocol definition.
+    """
+
+    def __call__(self, __props: Any, /, **dependencies: Any) -> Any: ...
+
+
+class AsyncLayout(Protocol):
+    """
+    Async layout protocol definition.
+    """
+
+    async def __call__(self, __props: Any, /, **dependencies: Any) -> Any: ...
+
+
+Layout: TypeAlias = SyncLayout | AsyncLayout
+"""
+Layout type definition.
+
+A layout is a callable that expects a single positional argument the component or data returned
+by the wrapped layout or page, and returns the properties for its wrapper layout. The root layout
+must always return a `Component`.
+"""
+
+LayoutFactory: TypeAlias = Callable[[Any], Any | Coroutine[None, None, Any]]
+"""
+A layout factory is a sync or asynccallable that expects a single argument (the layout's properties)
+and returns the properties for its wrapper layout.
+
+The root layout factory must always return an `htmy` `Component`.
+"""
+
+
+class LayoutDefinition(Protocol):
+    """Protocol definition for objects (usually modules) that define a layout."""
+
+    @property
+    def layout(self) -> Layout: ...
+
+
+def is_layout_definition(obj: Any) -> TypeGuard[LayoutDefinition]:
+    """Type guard for `LayoutDefinition`."""
+    layout = getattr(obj, "layout", None)
+    return callable(layout)
+
+
+def combine_layouts_to_dependency(
+    outer_dep: FastAPIDependency[LayoutFactory], inner: Layout | None
+) -> FastAPIDependency[LayoutFactory]:
+    """
+    Creates a layout factory dependency that wraps the inner layout inside the outer layout.
+
+    Arguments:
+        outer: The outer layout factory.
+        inner: The inner layout factory.
+    """
+    if inner is None:
+        return outer_dep
+
+    inner_dep = layout_to_dependency(inner)
+
+    async def combined_layout_dep(
+        outer: LayoutFactory = Depends(outer_dep),  # noqa: B008
+        inner: LayoutFactory = Depends(inner_dep),  # noqa: B008
+    ) -> LayoutFactory:
+        async def layout_factory(props: Any) -> Any:
+            inner_result = inner(props)
+            if isinstance(inner_result, Awaitable):
+                inner_result = await inner_result
+
+            result = outer(as_component_type(inner_result))
+            if isinstance(result, Awaitable):
+                result = await result
+
+            return result
+
+        return layout_factory
+
+    return combined_layout_dep
+
+
+def empty_layout(props: Any) -> Any:
+    """`LayoutFactory` that simply returns the received props."""
+    return props
+
+
+def empty_layout_dependency() -> FastAPIDependency[LayoutFactory]:
+    """
+    FastAPI dependency that returns `empty_layout`.
+    """
+    return empty_layout
+
+
+def layout_to_dependency(layout: Layout) -> FastAPIDependency[LayoutFactory]:
+    """
+    Converts a layout to a FastAPI dependency that returns a layout factory.
+    """
+    # eval_str=True is necessary in case future __annotations__ is used
+    # where the layout is function is defined.
+    params = tuple(inspect.signature(layout, eval_str=True).parameters.values())
+    props_index = next((i for i, p in enumerate(params) if p.name != "self"), -1)
+    if props_index == -1:
+        raise ValueError("Layout factory must at least one argument.")
+
+    result: FastAPIDependency[LayoutFactory]
+    if iscoroutinefunction(layout):
+
+        async def async_layout_factory_dep(**kwargs: Any) -> LayoutFactory:
+            async def layout_factory(props: Any) -> Any:
+                return await layout(props, **kwargs)
+
+            return layout_factory
+
+        result = async_layout_factory_dep
+    else:
+
+        def sync_layout_factory_dep(**kwargs: Any) -> LayoutFactory:
+            def layout_factory(props: Any) -> Any:
+                return layout(props, **kwargs)
+
+            return layout_factory
+
+        result = sync_layout_factory_dep
+
+    # Copy the dependencies part of the signature from the original function, so
+    # FastAPI can resolve those arguments. The props argument must be excluded.
+    result.__signature__ = inspect.Signature(params[props_index + 1 :])  # type: ignore[union-attr]
+
+    return result

holm-0.1.0/holm/modules/_metadata.py

@@ -0,0 +1,123 @@
+from collections.abc import ItemsView, Iterator, KeysView, Mapping, ValuesView
+from typing import Any, Protocol, TypeAlias, overload
+
+from htmy import Component, ContextAware, as_component_sequence
+
+from holm.fastapi import FastAPIDependency
+
+MetadataMapping: TypeAlias = Mapping[Any, Any]
+"""
+A mapping representation of information to be placed in the `<head>` element of an HTML document.
+
+It is usually a dictionary with string keys and values, but it is not enforced in runtime,
+so the typing is more lenient.
+"""
+
+
+class MetadataOwner(Protocol):
+    """
+    Protocol definition for objects (usually modules) that define page metadata.
+    """
+
+    @property
+    def metadata(self) -> MetadataMapping | FastAPIDependency[MetadataMapping | None]: ...
+
+
+def get_metadata_dependency(obj: Any) -> FastAPIDependency[MetadataMapping | None]:
+    """
+    Loads and returns the FastAPI `MetadataMapping` dependency based on the metadata definition
+    in the given object.
+
+    If the object is not a `MetadataOwner`, the dependency will simply return `None`.
+    """
+    metadata = getattr(obj, "metadata", None)
+    if metadata is None or isinstance(metadata, Mapping):
+        return lambda: metadata
+
+    if callable(metadata):
+        return metadata  # type: ignore[no-any-return]
+
+    raise ValueError(f"Invalid metadata object: {metadata}")
+
+
+class Metadata(ContextAware):
+    """
+    Context-aware metadata provider.
+
+    The class implements the `Mapping` protocol as a means of giving convenient access to
+    the metadata it contains.
+    """
+
+    __slots__ = ("_metadata",)
+
+    def __init__(self, metadata: MetadataMapping) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            metadata: The actual metadata mapping.
+        """
+        self._metadata = metadata
+        """The metadata mapping."""
+
+    @overload
+    def get(self, key: Any, default: None = None) -> Any | None: ...
+
+    @overload
+    def get(self, key: Any, default: Any) -> Any: ...
+
+    def get(self, key: Any, default: Any | None = None) -> Any | None:
+        """Implements `Mapping.get()`."""
+        return self._metadata.get(key, default)
+
+    def __contains__(self, key: Any) -> bool:
+        """Implements the `Container` protocol."""
+        return key in self._metadata
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, Metadata) and self._metadata == other._metadata
+
+    def __getitem__(self, key: Any) -> Any:
+        """Implements the `Sequence` protocol."""
+        return self._metadata[key]
+
+    def __iter__(self) -> Iterator[Any]:
+        """Implements the `Iterable` protocol."""
+        return iter(self._metadata)
+
+    def __len__(self) -> int:
+        """Implements the `Sized` protocol."""
+        return len(self._metadata)
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
+
+    def items(self) -> ItemsView[Any, Any]:
+        """Implements `Mapping.items()`."""
+        return self._metadata.items()
+
+    def keys(self) -> KeysView[Any]:
+        """Implements `Mapping.keys()`."""
+        return self._metadata.keys()
+
+    def values(self) -> ValuesView[Any]:
+        """Implements `Mapping.values()`."""
+        return self._metadata.values()
+
+
+def components_with_metadata(data: tuple[Component, MetadataMapping | None]) -> Component:
+    """
+    Function that converts a `Component` and optional `MetadataMapping` tuple into a `Component`
+    in which the received component is wrapped in a `MetadataContext`, making the given metadata
+    available in all wrapped components using `Metadata.from_context()`.
+    """
+    components, metadata = data
+    # Wrap the rendered components in Metadata context provider component.
+    # This allows `Metadata.from_context()` to be used in all wrapped components.
+    # The received components object is usually a ComponentSequence (doctype and html components),
+    # so converting to a component sequence seems a tiny bit more efficient.
+    return (
+        components
+        if metadata is None
+        else Metadata(metadata).in_context(*as_component_sequence(components))
+    )

holm-0.1.0/holm/modules/_page.py

@@ -0,0 +1,23 @@
+from typing import Any, Protocol, TypeAlias, TypeGuard
+
+from holm.fastapi import FastAPIDependency
+
+Page: TypeAlias = FastAPIDependency[Any]
+"""FastAPI dependency that returns the properties for the layout that wraps it
+(for example a `Component`).
+
+If the page is not wrapped by a layout, then it must return a `Component`
+"""
+
+
+class PageDefinition(Protocol):
+    """Protocol definition for objects (usually modules) that define a page."""
+
+    @property
+    def page(self) -> Page: ...
+
+
+def is_page_definition(obj: Any) -> TypeGuard[PageDefinition]:
+    """Type guard for `PageDefinition`."""
+    page = getattr(obj, "page", None)
+    return callable(page)

holm-0.1.0/holm/typing.py

@@ -0,0 +1,24 @@
+from typing import Literal, TypeAlias, get_args
+
+PackageModuleName: TypeAlias = Literal["api", "layout", "page"]
+"""Recognized module names."""
+
+RootOnlyModuleName: TypeAlias = Literal["error"]
+"""Modules names that are only supported at the root level."""
+
+ModuleName: TypeAlias = PackageModuleName | RootOnlyModuleName
+"""All recognized module names, including ones that are only supported at the root level."""
+
+# get_args() doesn't return the correct tuple for the ModuleName union type.
+module_names: set[ModuleName] = {*get_args(PackageModuleName), *get_args(RootOnlyModuleName)}
+"""Set of all recognized module names."""
+
+URLSegment: TypeAlias = str
+"""
+A URL that consists of a leading slash followed by a non-empty URL part
+that includes no more slashes.
+
+Valid examples: "/about".
+
+Invalid examples: "/", "/about/us".
+"""

holm-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "holm"
+dynamic = []
+description = "Web development framework that brings the Next.js developer experience to Python, built on FastAPI, htmy, and FastHX."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.115.12",
+    "fasthx>=2.3.3",
+    "htmy[lxml]>=0.8.2",
+]
+version = "0.1.0"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "mkdocs-material>=9.6.20",
+    "mkdocstrings[python]>=0.30.1",
+    "mypy>=1.15.0",
+    "poethepoet>=0.35.0",
+    "pytest>=8.3.5",
+    "pytest-random-order>=1.1.1",
+    "ruff>=0.12.0",
+    "uvicorn>=0.34.1",
+    "watchfiles>=1.1.0",
+]
+
+[tool.mypy]
+strict = true
+explicit_package_bases = true
+show_error_codes = true
+
+[tool.pdm.build]
+excludes = [
+    "tests/",
+    "test_app/",
+]
+
+[tool.pdm.version]
+source = "file"
+path = "holm/__init__.py"
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+addopts = "--random-order"
+
+[tool.ruff]
+line-length = 108
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "dist",
+    "docs",
+]
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C",
+    "E",
+    "F",
+    "I",
+    "S",
+    "W",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = [
+    "S101",
+]
+
+[tool.poe.tasks]
+format = "ruff format . --check"
+format-fix = "ruff format ."
+lint = "ruff check ."
+lint-fix = "ruff check . --fix"
+mypy = "mypy ."
+serve-docs = "mkdocs serve"
+
+[tool.poe.tasks.test-app]
+cmd = "uvicorn test_app.main:app --reload"
+
+[tool.poe.tasks.check]
+sequence = [
+    "format",
+    "lint",
+    "mypy",
+]
+ignore_fail = "return_non_zero"
+
+[tool.poe.tasks.test]
+cmd = "python -m pytest tests"
+
+[tool.poe.tasks.test.env]
+APP_ENV = "test"