Utils reference

Module summary

next.utils exposes two helpers that project code can import, resolve_base_dir and classify_dirs_entries, and the PageRoot value object. The rest of the module is framework machinery and is excluded from the listing below. It backs decorator registration, attributing a decorated object to the file where it was declared, naming it for diagnostics, and collecting the registrations that landed on another file. It also holds walk_page_tree, the depth-first page-tree walk the file router and the system checks both run, which lives here for the same reason PageRoot does.

resolve_base_dir returns settings.BASE_DIR coerced to pathlib.Path, or None when it is unset, for backends that resolve project-relative paths. classify_dirs_entries splits a backend DIRS list into existing directory roots and plain skip-name segments, the same split the file router applies. PageRoot pairs a page tree with the label a report names it by. It lives here rather than beside the router because the system checks build one too, and it is re-exported as next.urls.PageRoot for the router contract that produces it.

Public API

Path helpers, the page-tree value object, and declaration-site attribution.

Everything here sits below the subpackages that share it, so a value object two of them build travels through this module rather than closing an import cycle between them.

class next.utils.PageRoot(path: Path, label: str)

A page tree a router routes, with the label a report names it by.

path: Path

label: str

__init__(path: Path, label: str) → None

next.utils.page_roots_shape_error(source: str, roots: list[Any]) → str | None

Return why roots is no list of page trees, or None when it is one.

Both readers of page_roots dereference root.path, so the rule they refuse a third-party backend by lives here with the value object.

next.utils.resolve_base_dir() → Path | None

Return settings.BASE_DIR as a pathlib.Path, or None.

next.utils.classify_dirs_entries(entries: list[Any] | tuple[Any, ...] | None, base_dir: Path | None) → tuple[list[Path], frozenset[str]]

Split DIRS into directory roots and URL segment names (file router).

See also

See also

File router documents the DIRS semantics that classify_dirs_entries supports.