Merge pull request #6 from volfpeter/feat/private-packages

Add support for private packages

Author: volfpeter

README.md

@@ -86,6 +86,16 @@ At the moment, the library **does not** provide security features like automatic
 
 Also, do not forget about **XSS prevention**, when rendering untrusted data with custom components!
 
+## AI assistance
+
+The library and all its dependencies are registered at [Context7](https://context7.com/volfpeter).
+
+To get good AI assistance, all you need to do is register the Context7 MCP server in your coding tool and tell the agent to use it.
+
+If you are starting a new project, you can additionally point the agent at one of the example applications in the [repository](https://github.com/volfpeter/holm). With all this context and detailed instructions of the project you want to build, it will get you started quickly.
+
+Because of the similarity with Next.js and React, and the standard use of FastAPI and other dependencies, you can expect good results, both for vibe coding or inline completion.
+
 ## Development
 
 Development setup:

docs/application-components.md

@@ -60,7 +60,15 @@ Both formats are converted to FastAPI path parameters. For example:
 - File path `user/_id_/profile` becomes URL `/user/{id}/profile`.
 - File path `user/{user_id}/settings` becomes URL `/user/{user_id}/settings`.
 
-Any layout or page within these packages can access the parameter as a FastAPI dependency by adding it to their function signature (e.g., `id: int` or `userId: str`).
+Any layout or page within these packages can access the parameter as a FastAPI dependency by adding it to their function signature (e.g., `id: int` or `user_id: str`).
+
+## Private packages
+
+You can prefix package names with one or more underscores to opt the entire package (including its subpackages) out of the automatic application component discovery.
+
+For example, if you have a package named `_private` somewhere in your application folder, you can freely place valid page, layout, or API files within it or its subpackages. These modules will not be processed and included in the application.
+
+Reminder: if the package name also ends with an underscore, it will be treated as a path parameter, as described [above](#path-parameters-as-package-names).
 
 ## Error handling
 

docs/index.md

@@ -77,6 +77,16 @@ At the moment, the library **does not** provide security features like automatic
 
 Also, do not forget about **XSS prevention**, when rendering untrusted data with custom components!
 
+## AI assistance
+
+The library and all its dependencies are registered at [Context7](https://context7.com/volfpeter).
+
+To get good AI assistance, all you need to do is register the Context7 MCP server in your coding tool and tell the agent to use it.
+
+If you are starting a new project, you can additionally point the agent at one of the example applications in the [repository](https://github.com/volfpeter/holm). With all this context and detailed instructions of the project you want to build, it will get you started quickly.
+
+Because of the similarity with Next.js and React, and the standard use of FastAPI and other dependencies, you can expect good results, both for vibe coding or inline completion.
+
 ## Development
 
 Development setup:

holm/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from .app import App as App
 from .fastapi import FastAPIDependency as FastAPIDependency

holm/app.py

@@ -1,5 +1,7 @@
 import inspect
 from collections.abc import Awaitable, Iterable
+from functools import lru_cache
+from pathlib import Path
 from typing import cast
 
 from fastapi import APIRouter, Depends, FastAPI
@@ -131,10 +133,22 @@ def _discover_app_packages(config: AppConfig) -> set[PackageInfo]:
     """
     Discovers all packages that are part of the application and returns them as a set.
     """
+
+    @lru_cache()
+    def is_excluded(path: Path) -> bool:
+        """Returns whether the given file or package path should be excluded from the application."""
+        rel_path = path.relative_to(config.root_dir)
+        return any(
+            # Exclude if a path segment starts with an underscore but does not end with one.
+            # Path segments that both start and end with an underscore represent path parameters!
+            p.startswith("_") and not p.endswith("_")
+            for p in rel_path.parts
+        )
+
     return {
         PackageInfo.from_marker_file(f, config=config)
         for f in config.app_dir.rglob("*.py")
-        if f.stem in module_names
+        if f.stem in module_names and not is_excluded(f.parent)  # Pass the parent to make use of caching
     }
 
 

test_app/_not_in_app/__init__.py

@@ -0,0 +1,6 @@
+def page() -> str:
+    return (
+        "This must not be included in the app because it's in an excluded package: "
+        "there's a parent package whose name starts with an _ and does not end with _ "
+        "(so no path parameter)."
+    )

test_app/_not_in_app/inner/__init__.py

@@ -0,0 +1,6 @@
+def page() -> str:
+    return (
+        "This must not be included in the app because it's in an excluded package: "
+        "there's a parent package whose name starts with an _ and does not end with _ "
+        "(so no path parameter)."
+    )

test_app/_not_in_app/inner/page.py

@@ -0,0 +1,14 @@
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.mark.parametrize(
+    ("path",),
+    (
+        ("/_not_in_app",),
+        ("/_not_in_app/inner",),
+    ),
+)
+def test_page(client: TestClient, path: str) -> None:
+    response = client.get(path)
+    assert response.status_code == 404