Add programmatic nav construction and callable factory support (#214)

Author: joshuadavidthomas

docs/reference.md

@@ -13,7 +13,7 @@ This page documents the runtime behaviors that aren't captured in the API docs.
 
 | Argument | Required | Description |
 |---|---|---|
-| `nav` | yes | A dotted import path string (e.g. `"config.nav.MainNav"`) or a `Nav` instance from the template context. |
+| `nav` | yes | A dotted import path string to a `Nav` class (e.g. `"config.nav.MainNav"`), a dotted path to a callable that accepts `request` and returns a `Nav` (e.g. `"config.nav.main_nav"`), or a `Nav` instance from the template context. See [Programmatic Navigation](usage.md#programmatic-navigation). |
 | `template_name` | no | Override the template used to render the navigation. |
 
 Expects `request` in the template context.

docs/usage.md

@@ -266,6 +266,50 @@ def example_view(request):
 </nav>
 ```
 
+## Programmatic Navigation
+
+Instead of subclassing `Nav`, you can construct one directly. This is useful when you want to build the items list with conditionals or loops:
+
+```python
+from django_simple_nav.nav import Nav, NavItem
+
+items = [NavItem(title="Home", url="/")]
+if show_dashboard:
+    items.append(NavItem(title="Dashboard", url="/dashboard/"))
+
+main_nav = Nav(template_name="main_nav.html", items=items)
+```
+
+### Factory functions
+
+For conditions that depend on the request (user authentication, permissions, session data), define a callable that accepts the request and returns a `Nav`:
+
+```python
+# config/nav.py
+from django.http import HttpRequest
+
+from django_simple_nav.nav import Nav, NavItem
+
+
+def main_nav(request: HttpRequest) -> Nav:
+    items = [NavItem(title="Home", url="/")]
+    if request.user.is_authenticated:
+        items.append(NavItem(title="Dashboard", url="/dashboard/"))
+    if request.user.is_staff:
+        items.append(NavItem(title="Admin", url="/admin/"))
+    return Nav(template_name="main_nav.html", items=items)
+```
+
+Use the dotted import path in the template tag, the same way you would with a `Nav` class:
+
+```htmldjango
+{% load django_simple_nav %}
+
+{% django_simple_nav "config.nav.main_nav" %}
+```
+
+The callable receives the current `request` and its return value is rendered as the navigation. This works in both Django templates and Jinja2.
+
 ## Self-Rendering Items
 
 Instead of writing the HTML for each item manually, you can use `{{ item }}` to let items render themselves:

src/django_simple_nav/jinja2.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import cast
+from collections.abc import Callable
 
 from django.utils.module_loading import import_string
 from jinja2 import TemplateRuntimeError
@@ -12,25 +12,52 @@
 
 @pass_context
 def django_simple_nav(
-    context: Context, nav: str | Nav, template_name: str | None = None
+    context: Context,
+    nav: str | Nav | Callable[..., Nav],
+    template_name: str | None = None,
 ) -> str:
     """Jinja binding for `django_simple_nav`"""
     if (loader := context.environment.loader) is None:
         raise TemplateRuntimeError("No template loader in Jinja2 environment")
 
-    if type(nav) is str:
+    request = context.get("request")
+    if request is None:
+        raise TemplateRuntimeError("`request` not found in Jinja2 context")
+
+    nav_instance: object
+    if isinstance(nav, Nav):
+        nav_instance = nav
+    elif isinstance(nav, str):
         try:
-            nav = import_string(nav)()
+            resolved: object = import_string(nav)
         except ImportError as err:
             raise TemplateRuntimeError(str(err)) from err
 
+        if isinstance(resolved, type):
+            nav_instance = resolved()
+        elif callable(resolved):
+            nav_instance = resolved(request)
+        else:
+            nav_instance = resolved
+    elif callable(nav):
+        nav_instance = nav(request)
+    else:
+        nav_instance = nav
+
+    if not isinstance(nav_instance, Nav):
+        raise TemplateRuntimeError(f"Not a valid `Nav` instance: {nav_instance}")
+
     try:
         if template_name is None:
-            template_name = cast(Nav, nav).template_name
+            template_name = nav_instance.template_name
         if template_name is None:
             raise TemplateRuntimeError("Navigation object has no template")
-        request = context["request"]
-        new_context = {"request": request, **cast(Nav, nav).get_context_data(request)}
+        new_context = {
+            "request": request,
+            **nav_instance.get_context_data(request),
+        }
+    except TemplateRuntimeError:
+        raise
     except Exception as err:
         raise TemplateRuntimeError(str(err)) from err
 

src/django_simple_nav/nav.py

@@ -91,6 +91,17 @@ class Nav:
     template_name: str | None = field(init=False, default=None)
     items: list[NavGroup | NavItem] | None = field(init=False, default=None)
 
+    def __init__(
+        self,
+        *,
+        template_name: str | None = None,
+        items: list[NavGroup | NavItem] | None = None,
+    ) -> None:
+        if template_name is not None:
+            object.__setattr__(self, "template_name", template_name)
+        if items is not None:
+            object.__setattr__(self, "items", items)
+
     def render(self, request: HttpRequest, template_name: str | None = None) -> str:
         context = self.get_context_data(request)
         template = self.get_template(template_name)

src/django_simple_nav/templatetags/django_simple_nav.py

@@ -37,27 +37,39 @@ def __init__(self, nav: str, template_name: str | None) -> None:
 
     @override
     def render(self, context: Context) -> str:
-        nav = self.get_nav(context)
-        template_name = self.get_template_name(context)
         request = self.get_request(context)
+        nav = self.get_nav(context, request)
+        template_name = self.get_template_name(context)
 
         return nav.render(request, template_name)
 
-    def get_nav(self, context: Context) -> Nav:
+    def get_nav(self, context: Context, request: HttpRequest) -> Nav:
         try:
             nav: str | Nav = self.nav.resolve(context)
         except template.VariableDoesNotExist as err:
             raise template.TemplateSyntaxError(
                 f"Variable does not exist: {err}"
             ) from err
 
+        if isinstance(nav, Nav):
+            return nav
+
         if isinstance(nav, str):
             try:
-                nav_instance: object = import_string(nav)()
+                imported: object = import_string(nav)
             except ImportError as err:
                 raise template.TemplateSyntaxError(
                     f"Failed to import from dotted string: {nav}"
                 ) from err
+
+            if isinstance(imported, type):
+                # Class (Nav subclass or otherwise) - instantiate with no args
+                nav_instance: object = imported()
+            elif callable(imported):
+                # Callable factory - call with request
+                nav_instance = imported(request)
+            else:
+                nav_instance = imported
         else:
             nav_instance = nav
 

tests/navs.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from django.http import HttpRequest
+
 from django_simple_nav.nav import Nav
 from django_simple_nav.nav import NavGroup
 from django_simple_nav.nav import NavItem
@@ -49,3 +51,16 @@ class DummyNav(Nav):
             items=[NavItem(title="Test Item", url="#")],
         ),
     ]
+
+
+def dynamic_nav(request: HttpRequest) -> Nav:
+    """A callable nav factory for testing."""
+    items = [NavItem(title="Home", url="/")]
+    if hasattr(request, "user") and getattr(request.user, "is_authenticated", False):
+        items.append(NavItem(title="Dashboard", url="/dashboard/"))
+    return Nav(template_name="tests/dummy_nav.html", items=items)
+
+
+def bad_callable(request: HttpRequest) -> str:
+    """Returns something that is not a Nav (for error testing)."""
+    return "not a Nav"

tests/test_jinja.py

@@ -140,3 +140,55 @@ class InvalidRequest: ...
 
     with pytest.raises(TemplateRuntimeError):
         template.render({"request": InvalidRequest()})
+
+
+def test_callable_dotted_string(req):
+    template = environment.from_string(
+        '{{ django_simple_nav("tests.navs.dynamic_nav") }}'
+    )
+    req.user = AnonymousUser()
+    rendered_template = template.render({"request": req})
+
+    assert "Home" in rendered_template
+    assert "Dashboard" not in rendered_template
+
+
+def test_callable_authenticated(req):
+    template = environment.from_string(
+        '{{ django_simple_nav("tests.navs.dynamic_nav") }}'
+    )
+    req.user = baker.make(get_user_model())
+    rendered_template = template.render({"request": req})
+
+    assert "Home" in rendered_template
+    assert "Dashboard" in rendered_template
+
+
+def test_callable_with_template_name(req):
+    template = environment.from_string(
+        "{{ django_simple_nav('tests.navs.dynamic_nav', 'tests/alternate.html') }}"
+    )
+    req.user = AnonymousUser()
+    rendered_template = template.render({"request": req})
+
+    assert "This is an alternate template." in rendered_template
+
+
+def test_callable_variable(req):
+    from tests.navs import dynamic_nav
+
+    template = environment.from_string("{{ django_simple_nav(nav_func) }}")
+    req.user = AnonymousUser()
+    rendered_template = template.render({"request": req, "nav_func": dynamic_nav})
+
+    assert "Home" in rendered_template
+
+
+def test_bad_callable(req):
+    template = environment.from_string(
+        '{{ django_simple_nav("tests.navs.bad_callable") }}'
+    )
+    req.user = AnonymousUser()
+
+    with pytest.raises(TemplateRuntimeError):
+        template.render({"request": req})

tests/test_nav.py

@@ -222,3 +222,65 @@ class GetTemplateNameNav(Nav):
 
     with pytest.raises(ImproperlyConfigured):
         GetTemplateNameNav().get_template_name()
+
+
+class TestNavConstructor:
+    """Tests for direct Nav() construction (programmatic usage)."""
+
+    def test_constructor_with_items_and_template_name(self, req):
+        nav = Nav(
+            template_name="tests/dummy_nav.html",
+            items=[NavItem(title="Home", url="/")],
+        )
+
+        rendered = nav.render(req)
+
+        assert "Home" in rendered
+        assert count_anchors(rendered) == 1
+
+    def test_constructor_no_args(self):
+        nav = Nav()
+
+        assert nav.template_name is None
+        assert nav.items is None
+
+    def test_constructor_items_only(self, req):
+        nav = Nav(items=[NavItem(title="Test", url="/test/")])
+
+        items = nav.get_items(req)
+
+        assert len(items) == 1
+
+    def test_constructor_template_name_only(self):
+        nav = Nav(template_name="tests/dummy_nav.html")
+
+        assert nav.get_template_name() == "tests/dummy_nav.html"
+
+    def test_constructor_frozen(self):
+        nav = Nav(
+            template_name="tests/dummy_nav.html",
+            items=[NavItem(title="Home", url="/")],
+        )
+
+        with pytest.raises(AttributeError):
+            nav.template_name = "other.html"
+
+    def test_constructor_keyword_only(self):
+        with pytest.raises(TypeError):
+            Nav("tests/dummy_nav.html", [])
+
+    def test_subclass_not_shadowed(self):
+        """Existing subclass pattern continues to work."""
+        nav = DummyNav()
+
+        assert nav.template_name == "tests/dummy_nav.html"
+        assert nav.items is not None
+        assert len(nav.items) > 0
+
+    def test_constructor_with_conditional_items(self, req):
+        items = [NavItem(title="Home", url="/")]
+        items.append(NavItem(title="About", url="/about/"))
+
+        nav = Nav(template_name="tests/dummy_nav.html", items=items)
+
+        assert len(nav.get_items(req)) == 2

tests/test_templatetags.py

@@ -165,3 +165,48 @@ class InvalidRequest: ...
 
     with pytest.raises(TemplateSyntaxError):
         template.render(Context({"request": InvalidRequest()}))
+
+
+def test_templatetag_with_callable(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.dynamic_nav' %}"
+    )
+    req.user = AnonymousUser()
+
+    rendered_template = template.render(Context({"request": req}))
+
+    assert "Home" in rendered_template
+    assert "Dashboard" not in rendered_template
+
+
+def test_templatetag_with_callable_authenticated(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.dynamic_nav' %}"
+    )
+    req.user = baker.make(get_user_model())
+
+    rendered_template = template.render(Context({"request": req}))
+
+    assert "Home" in rendered_template
+    assert "Dashboard" in rendered_template
+
+
+def test_templatetag_with_callable_and_template_name(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.dynamic_nav' 'tests/alternate.html' %}"
+    )
+    req.user = AnonymousUser()
+
+    rendered_template = template.render(Context({"request": req}))
+
+    assert "This is an alternate template." in rendered_template
+
+
+def test_templatetag_with_bad_callable(req):
+    template = Template(
+        "{% load django_simple_nav %} {% django_simple_nav 'tests.navs.bad_callable' %}"
+    )
+    req.user = AnonymousUser()
+
+    with pytest.raises(TemplateSyntaxError):
+        template.render(Context({"request": req}))