class aspen.http.mapping.Mapping

Base class for HTTP mappings.

Mappings in HTTP differ from Python dictionaries in that they may have one or more values. This dictionary subclass maintains a list of values for each key. However, access semantics are asymmetric: subscript assignment clobbers to list, while subscript access returns the last item. Think about it.


This isn’t thread-safe.


Called when a key is missing. Default implementation simply reraises.

pop(name, default=<object object>)

Given a name, return a value.

This removes the last value from the list for name and returns it. If there was only one value in the list then the key is removed from the mapping. If name is not present and default is given, that is returned instead. Otherwise, self.keyerror is called.


D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised


Given a name, return a list of values, possibly empty.

get(name, default=None)

Override to only return the last value.

add(name, value)

Given a name and value, clobber any existing values with the new one.


Given one or more names of keys, return a list of their values.

class aspen.http.request.PathPart

Represents a segment of a URL path.


extra data attached to this segment


This function implements parsing URL path parameters, per section 3.3 of RFC2396.

  • path should be raw so we don’t split or operate on a decoded character
  • output is decoded


>>> path = '/frisbee;color=red;size=small/logo;sponsor=w3c;color=black/image.jpg'
>>> extract_rfc2396_params(path) == [
...     PathPart('frisbee', params={'color': ['red'], 'size': ['small']}),
...     PathPart('logo', params={'sponsor': ['w3c'], 'color': ['black']}),
...     PathPart('image.jpg', params={})
... ]

This splits a path into parts on “/” only (no split on “;” or “,”).

class aspen.http.request.Path(raw, split_path=<function extract_rfc2396_params>)

Represent the path of a resource.


the unparsed form of the path - str


the decoded form of the path - str


the segments of the path - list of PathPart objects

class aspen.http.request.Querystring(raw, errors='replace')

Represent an HTTP querystring.


the unparsed form of the querystring - str


the decoded form of the querystring - str

aspen.http.resource.open_resource(request_processor, resource_path)

Open a resource in read-only binary mode, after checking for symlinks.

Raises:AttemptedBreakout – if the resource_path points to a file that isn’t inside any of the known resource_directories

This function doesn’t fully protect against attackers who have the ability to create and delete symlinks inside the resource directories whenever they want, but it makes the attack more difficult and detectable.

aspen.http.resource.check_resource_path(request_processor, resource_path)

Return the “real” path of a file (i.e. a path without symlinks).

Raises:AttemptedBreakout – if the resource_path points to a file that isn’t inside any of the known resource_directories
class aspen.http.resource.Static(request_processor, fspath)

Model a static HTTP resource.


Returns the file’s content as bytes.

If the store_static_files_in_ram configuration option was set to False (the default), then the file is read from the filesystem, otherwise its content is returned directly.

class aspen.http.resource.Dynamic

Model a dynamic HTTP resource.

render(context, dispatch_result, accept_header)

Render the resource.

Before rendering we need to determine what type of content we’re going to send back, by trying to find a match between the media types the client wants and the ones provided by the resource.

The two sources for what the client wants are the extension in the request URL (dispatch_result.extension), and the Accept header (accept_header). If the former fails to match we raise NotFound (404), if the latter fails we raise NegotiationFailure (406).

Note that we don’t always respect the Accept header (the spec says we can ignore it: <>).

  • context (dict) – the variables you want to pass to the resource
  • dispatch_result (DispatchResult) – the object returned by the dispatcher
  • accept_header (str) – the requested media types

Returns: an Output object.