Routing

Loaders

Routing is a big part of any web library, and there are many ways to do it. View does it's best to support as many methods as possible to give you a well-rounded approach to routing. In view, your choice of routing is called the loader/loader strategy, and there are four of them:

• manual
• simple
• filesystem
• patterns

Manually Routing

If you're used to Python libraries like Flask or FastAPI, then you're probably already familiar with manual routing. Manual routing is considered to be letting the user do all of the loading themself, and not do any automatic import or load mechanics. There are two ways to do manual routing, directly calling on your App being the most robust. Here's an example:

from view import new_app

app = new_app()

@app.get("/")
def index():
    return "Hello, view.py!"

app.run()

This type of function is called a direct router, and is what's recommended for small view.py projects. However, if you're more accustomed to JavaScript libraries, using the standard routers may be a good fit. When using manual routing, a standard router must be registered via a call to App.load.

Load the app. This is automatically called most of the time and should only be called manually during manual loading.

Parameters:

Name	Type	Description	Default
routes	list[Route] | None	Routes to load into the app.	None

Source code in src/view/app.py

def load(self, routes: list[Route] | None = None) -> None:
    """Load the app. This is automatically called most of the time and should only be called manually during manual loading.

    Args:
        routes: Routes to load into the app.
    """
    if self.loaded:
        if routes:
            finalize(routes, self)
        Internal.warning("load called twice")
        return

    if routes and (self.config.app.loader != "manual"):
        warnings.warn(_ROUTES_WARN_MSG)

    if self.config.app.loader == "filesystem":
        load_fs(self, self.config.app.loader_path)
    elif self.config.app.loader == "simple":
        load_simple(self, self.config.app.loader_path)
    elif self.config.app.loader == "patterns":
        load_patterns(self, self.config.app.loader_path)
    else:
        finalize([*(routes or ()), *self._manual_routes], self)

    self.loaded = True

    for r in self.loaded_routes:
        if not r.path:
            continue

        body = {}
        query = {}

        for i in r.inputs:
            target = body if i.is_body else query
            target[i.name] = InputDoc(
                i.doc or "No description provided.", i.tp, i.default
            )

        self._docs[(r.method.name, r.path)] = RouteDoc(
            r.doc or "No description provided.", body, query
        )

Standard and Direct Routers

Standard routers and direct routers have the exact same API (i.e. they are called the same way). The only difference is that direct routers automatically register a route onto the app, while standard routes do not. Direct routers tend to be used in small projects under manual loading, but standard routers are used in larger applications with one of the other loaders.

Here are all the routers (standard on left, direct on right):

• view.get and App.get
• view.post and App.post
• view.put and App.put
• view.patch and App.patch
• view.delete and App.delete
• view.options and App.options

from view import new_app, get

app = new_app()

@get("/")
def index():
    return "Hello, view.py!"

app.load([get])
app.run()

This method may be a bit more versatile if you plan on writing a larger project using manual routing, as you can import your routes from other files, but if that's the case it's recommended that you use one of the other loaders.

Source code in src/view/routing.py

def get(
    path_or_route: str | None | RouteOrCallable[P, T] = None,
    doc: str | None = None,
) -> Path[P, T]:
    return _method_wrapper(path_or_route, doc, Method.GET)

Source code in src/view/routing.py

def post(
    path_or_route: str | None | RouteOrCallable = None,
    doc: str | None = None,
):
    return _method_wrapper(path_or_route, doc, Method.POST)

Source code in src/view/routing.py

def put(
    path_or_route: str | None | RouteOrCallable = None,
    doc: str | None = None,
):
    return _method_wrapper(path_or_route, doc, Method.PUT)

Source code in src/view/routing.py

def patch(
    path_or_route: str | None | RouteOrCallable = None,
    doc: str | None = None,
):
    return _method_wrapper(path_or_route, doc, Method.PATCH)

Source code in src/view/routing.py

def delete(
    path_or_route: str | None | RouteOrCallable = None,
    doc: str | None = None,
):
    return _method_wrapper(path_or_route, doc, Method.DELETE)

Source code in src/view/routing.py

def options(
    path_or_route: str | None | RouteOrCallable = None,
    doc: str | None = None,
):
    return _method_wrapper(path_or_route, doc, Method.OPTIONS)

Simple Routing

Simple routing is similar to manual routing, but you tend to not use direct routers and don't have any call to load(). In your routes directory (routes/ by default, loader_path setting), your routes will be held in any number of files. Simple loading is recursive, so you may also use folders. View will automatically extract any route objects created in these files.

# routes/foo.py
from view import get

@get("/foo")
def index():
    return "foo"

@get("/bar")
def bar():
    return "bar"

/foo and /bar will be loaded properly, no extra call to App.load is required. In fact, you don't even have to import these in your app file. This is the recommended loader for larger view.py projects.

URL Pattern Routing

If you have ever used Django, you already know how URL pattern routing works. Instead of defining your routes all over the place, all routes are defined and imported into one central file. Traditionally, this file is called urls.py, but you can play around with the name via the loader_path configuration option.

Source code in src/view/patterns.py

def path(
    target: str,
    path_or_function: str | ViewRoute | Route,
    method: Method | StrMethod = "GET",
    *inputs: RouteInput,
) -> Route:
    if isinstance(path_or_function, str):
        mod = run_path(path_or_function)
        route: Route | ViewRoute | None = None

        for v in mod.values():
            if isinstance(v, Route) or callable(v):
                if route:
                    raise DuplicateRouteError(
                        f"multiple routes found in {path_or_function}"
                    )

                route = v

        if not route:
            raise InvalidRouteError(f"no route in {path_or_function}")
    else:
        route = path_or_function

    if isinstance(method, str):
        method = method.lower()  # type: ignore

    if method in _STR_MAPPINGS:
        method_enum: Method = _STR_MAPPINGS[method]
    else:
        method_enum: Method = method  # type: ignore

    func = _FUNC_MAPPINGS[method_enum]

    if isinstance(route, Route):
        if route.method != method_enum:
            method_enum = route.method

        func = _FUNC_MAPPINGS[method_enum]
        route_obj = func(target)(route)
    else:
        route_obj = func(target)(route)

    for i in inputs:
        i(route_obj)

    return route_obj

Pattern loading looks like this in view.py:

# something.py

def my_route(hello: str):
    return f"{hello}, world!"

from view import path, query
from something import my_route

patterns = (
    path("/", my_route, query("hello")),  # this is a route input, you'll learn about this later
    path("/another/thing", "/this/can/be/a/path/to/file.py")
)

In the above example, we defined two routes via exporting a tuple of Route objects (generated by path). The name patterns was used as the variable name, but it may be any of the following:

• PATTERNS
• patterns
• URLPATTERNS
• URL_PATTERNS
• urlpatterns
• url_patterns

Filesystem Routing

Finally, if you're familiar with JavaScript frameworks like NextJS, you're likely already familiar with filesystem routing. If that's the case, this may be the proper loader for you. The filesystem loader works by recursively searching your loader_path (again, routes/ by default) and assigning each found file to a route. You do not have to pass an argument for the path when using filesystem routing.

Filesystem routing comes with a few quirks.

• There should only be one route per file.
• The upper directory structure is ignored, so /home/user/app/routes/foo.py, the assigned route would be /foo.
• If a file is named index.py, the route is not named index, but instead the parent (e.g. foo/hello/index.py would be assigned to foo/hello).
• If a file is prefixed with _ (e.g. _hello.py), then it will be skipped entirely and not loaded. Files like this should be used for utilities and such.

Here's an example of this in action:

# routes/_util.py

def do_something():
    ...

# routes/index.py
from view import get
from _util import do_something

@get()
def index():
    do_something()
    return "Hello, view.py!"

Review

In view, a loader is defined as the method of routing used. There are three loaders in view.py: manual, simple, and filesystem.

• manual is good for small projects that are similar to Python libraries like Flask or FastAPI.
• simple routing is the recommended loader for full-scale view.py applications
• filesystem routing is similar to how JavaScript frameworks like NextJS handle routing.