aspen.request_processor.dispatcher

This module implements finding the file that matches a request path.

aspen.request_processor.dispatcher.strip_matching_ext(a, b)

Given two names, strip a trailing extension iff they both have them.

class aspen.request_processor.dispatcher.DispatchStatus

The attributes of this class are constants that represent dispatch statuses.

okay = okay

Found a matching file.

missing = missing

No match found.

unindexed = unindexed

Found a matching node, but it’s a directory without an index.

class aspen.request_processor.dispatcher.DispatchResult(status, match, wildcards, extension, canonical)

The result of a dispatch operation.

status

A DispatchStatus constant encoding the overall result.

match

The matching filesystem path (if status != ‘missing’).

wildcards

A dict whose keys are wildcard names, and values are as supplied by the path.

extension

A file extension, e.g. json when foo.spt is matched to foo.json.

canonical

The canonical path of the resource, e.g. / for /index.html.

class aspen.request_processor.dispatcher.FileNode(fspath, type, wildcard, extension)

Represents a file in a dispatch tree.

fspath

The absolute filesystem path of this node.

type

‘dynamic’ or ‘static’.

Type:The node’s type

wildcard

The name of the path variable if the node is a wildcard.

extension

The sub-extension of a dynamic file, e.g. json for foo.json.spt.

class aspen.request_processor.dispatcher.DirectoryNode(fspath, wildcard, children)

Represents a directory in a dispatch tree.

fspath

The absolute filesystem path of this node.

wildcard

The name of the path variable if the node is a wildcard.

children

The node’s children as a dict (keys are names and values are nodes).

class aspen.request_processor.dispatcher.LiveDirectoryNode(fspath, wildcard, children, mtime, dispatcher)

Dynamically represents a directory in a dispatch tree.

fspath

The absolute filesystem path of this node.

wildcard

The name of the path variable if the node is a wildcard.

mtime

The last modification time of the directory, in nanoseconds.

dispatcher

Points to the Dispatcher object that created this node.

aspen.request_processor.dispatcher.legacy_collision_handler(slug, node1, node2)

Ignores all collisions, like SystemDispatcher does.

aspen.request_processor.dispatcher.strict_collision_handler(*args)

A sane collision handler, it doesn’t allow any.

aspen.request_processor.dispatcher.hybrid_collision_handler(slug, node1, node2)

This collision handler allows a static file to shadow a dynamic resource.

Example: /file.js will be preferred over /file.js.spt.

aspen.request_processor.dispatcher.skip_hidden_files(name, dirpath)

Skip all names starting with a dot, except .well-known.

aspen.request_processor.dispatcher.skip_nothing(name, dirpath)

Always returns False.

class aspen.request_processor.dispatcher.Dispatcher(www_root, is_dynamic, indices, typecasters, file_skipper=<function skip_hidden_files>, collision_handler=<function hybrid_collision_handler>)

The abstract base class of dispatchers.

Parameters:

• www_root – the path to a filesystem directory
• is_dynamic – a function that takes a file name and returns a boolean
• indices – a list of filenames that should be treated as directory indexes
• typecasters – a dict of typecasters, keys are strings and values are functions
• file_skipper – a function that takes a file name and a directory path and returns a boolean
• collision_handler – a function that takes 3 arguments (slug, node1, node2) and returns a string

build_dispatch_tree()

Called to build the dispatch tree.

Subclasses must implement this method.

dispatch(path, path_segments)

Dispatch a request.

Parameters:

• path (str) – the request path, e.g. '/'
• path_segments (list) – the path split into segments, e.g. ['']

Subclasses must implement this method.

find_index(dirpath)

Looks for an index file in a directory.

Returns:the full path of the first index file, or None if no index was found

split_wildcard(wildcard, is_dir)

Splits a wildcard into its components.

Parameters:

• wildcard (str) – the string to split, e.g. 'year.int'
• is_dir (bool) – True if the wildcard is from a directory name

Returns:

a 3-tuple (varname, vartype, extension)

class aspen.request_processor.dispatcher.SystemDispatcher(www_root, is_dynamic, indices, typecasters, file_skipper=<function skip_hidden_files>, collision_handler=<function hybrid_collision_handler>)

Aspen’s original dispatcher, it’s very inefficient.

class aspen.request_processor.dispatcher.UserlandDispatcher(www_root, is_dynamic, indices, typecasters, file_skipper=<function skip_hidden_files>, collision_handler=<function hybrid_collision_handler>)

A dispatcher optimized for production use.

This dispatcher builds a complete and static tree when it is first created. It then uses this dispatch tree to route requests without making any system call, thus avoiding FFI and context switching costs.

This is the default dispatcher (when the changes_reload configuration option is False).

class aspen.request_processor.dispatcher.HybridDispatcher(www_root, is_dynamic, indices, typecasters, file_skipper=<function skip_hidden_files>, collision_handler=<function hybrid_collision_handler>)

A dispatcher optimized for development environments.

This dispatcher is almost identical to UserlandDispatcher, except that it does make some system calls to check that the matched filesystem directories haven’t been modified. If changes are detected, then the dispacth tree is updated accordingly.

This is the default dispatcher when the changes_reload configuration option is set to True.

class aspen.request_processor.dispatcher.TestDispatcher(*args, **kw)

This pseudo-dispatcher calls all the other dispatchers and checks that their results are identical. It’s only meant to be used in Aspen’s own tests.