| t |
The Aspen Request object tries to consistently model the actual structure of -an HTTP Request message. Consequently, it is rather verbose. There are -shortcuts available, however.
- - -Where?
- -An instance of the aspen.http.request.Request class is made
-available to you in your simplates from the second
-page on.
Shortcuts
- -The most common parts of the HTTP Request message are given these shortcuts -inside of simplate:
- -| body | request.body |
| cookie | request.headers.cookie |
| headers | request.headers |
| path | request.line.uri.path |
| qs | request.line.uri.querystring |
For example, here’s how to pull a value out of the querystring:
- -foo = qs["foo"] -- -
There are also booleans for each of the standard HTTP - methods, so simplates in a REST - style will end up looking like this:
- -if GET: - pass # handle GET ) -elif POST: - pass # handle POST- -
There is no API that folds the querystring and body together. It’s -better to be explicit about where you’re expecting your values from.
- - -Full API
- -The following object model is used to comprehensively represent an HTTP -Request message. Where “raw” attributes are noted those give the -bytes as supposedly received on the wire. As an optimization, this attribute is -lazily computed for request.body.raw. The request, itself a subclass of -str, is also dealt with lazily.
- -| name | class | base type | notes |
|---|---|---|---|
| request | Request | str | |
| request.line | Line | str | |
| request.line.method | Method | unicode | |
| request.line.method.raw | str | ||
| request.line.uri | URI | unicode | |
| request.line.uri.scheme | UnicodeWithRaw | unicode | |
| request.line.uri.scheme.raw | str | ||
| request.line.uri.username | UnicodeWithRaw | unicode | |
| request.line.uri.username.raw | str | ||
| request.line.uri.password | UnicodeWithRaw | unicode | |
| request.line.uri.password.raw | str | ||
| request.line.uri.host | UnicodeWithRaw | unicode | |
| request.line.uri.host.raw | str | ||
| request.line.uri.port | IntWithRaw | int | 0 if absent |
| request.line.uri.port.raw | str | ||
| request.line.uri.path | Path | Mapping | |
| request.line.uri.path.raw | str | ||
| request.line.uri.path.decoded | unicode | ||
| request.line.uri.path.parts | List of PathParts | see below | |
| request.line.uri.querystring | Querystring | Mapping | |
| request.line.uri.querystring.raw | str | ||
| request.line.uri.querystring.decoded | unicode | ||
| request.line.uri.raw | str | ||
| request.line.version | Version | unicode | |
| request.line.version.info | tuple | ||
| request.line.version.major | int | ||
| request.line.version.minor | int | ||
| request.line.version.raw | str | ||
| request.line.raw | str | ||
| request.headers | Headers | ||
| request.headers.cookie | Cookie.SimpleCookie - | ||
| request.headers.host | unicode | X-Forwarded-For if it exists, Host - otherwise (no Host will raise Response(400)) | |
| request.headers.scheme | unicode | u"https" or u"http" | |
| request.headers.raw | str | ||
| request.body | Body | ||
| request.body.raw | str |
Here are the methods on the Request object:
- -request.allow(*methods): - """Given method strings, raise 405 if we don't meet the requirements. - - The method names are case insensitive (they are uppercased). If 405 - is raised then the Allow header is set to the methods given. - - """ - -request.is_xhr(): - """Check the value of X-Requested-With. - """ -- - -
Mapping Objects
- -The Body, Headers, Path, and
-Querystring objects all have the same API. They are asymetric
-dictionaries. With HTTP mappings you always need to deal with the “either
-list or value” problem. Using them as simple values is much more common
-then using them as lists of values, so the base dictionary access set/get
-operations are tuned for that, and then you get this API for working with them
-as lists of values:
obj.all(name, default=None): - """Given a name, return a list of values. - """ - -obj.add(name, value): - """Given a name and value, add another entry. - """- -
Putting those together, here’s what it looks like:
- ->>> headers['Content-Type'] = "text/html"
->>> headers['Content-Type'] = "text/plain" # changed my mind!
->>> headers['Content-Type']
-text/plain
->>> headers.all('Content-Type')
-['text/plain']
-
-Here’s another example:
- ->>> qs.add('likes', 'cheese!')
->>> qs.add('likes', 'grommit!')
->>> qs['likes']
-'grommit!'
->>> qs.all('likes')
-['cheese!', 'grommit!']
-
-They’re asymetric in that subscript access respects the underlying -list while subscript assignment clobbers it.
- - - -File Uploads
- -If a request is of Content-Type
-multipart/form-data, then request.body values that
-are file uploads will be instances of the standard library’s cgi.FieldStorage class.
-Each such object has filename, value, and
-type attributes with the name, bytes, and advertised Content-Type
-of the file that was uploaded.
Path Parts
- -Aspen Path objects have a parts attribute, which
-is a list of PathPart objects. So if you're in a simplate
-at /foo/bar/baz.html.spt, then path.parts[1] will be
-'bar' and path.parts[2] will be
-'baz.html'.
RFC2396 specifies a syntax
-for attaching parameters to each path part, and Aspen exposes these in a
-params attribute (which is a Mapping object) on each
-unicode in the path.parts list.
Say what?
- -If you have:
- -/foo/index.html.spt -- -
and you hit it with:
- -/foo;a=1;b;a=3/ -- -
then you can do:
- -if 'b' in path.parts[0].params: - a = path.parts[0].params['a'] -\[---] -%(a)s -- -and you'll get: - -{{ screenshot("path-part-params") }} - -{% end %} - diff --git a/doc/api/request/path-part-params.png b/doc/api/request/path-part-params.png deleted file mode 100644 index a091f0d56..000000000 Binary files a/doc/api/request/path-part-params.png and /dev/null differ diff --git a/doc/api/request/path-part-params.small.png b/doc/api/request/path-part-params.small.png deleted file mode 100644 index b0f432a70..000000000 Binary files a/doc/api/request/path-part-params.small.png and /dev/null differ diff --git a/doc/api/response/fishing.200.png b/doc/api/response/fishing.200.png deleted file mode 100644 index 2d10be191..000000000 Binary files a/doc/api/response/fishing.200.png and /dev/null differ diff --git a/doc/api/response/fishing.200.small.png b/doc/api/response/fishing.200.small.png deleted file mode 100644 index 9aaf1b1da..000000000 Binary files a/doc/api/response/fishing.200.small.png and /dev/null differ diff --git a/doc/api/response/fishing.404.png b/doc/api/response/fishing.404.png deleted file mode 100644 index c1033d899..000000000 Binary files a/doc/api/response/fishing.404.png and /dev/null differ diff --git a/doc/api/response/fishing.404.small.png b/doc/api/response/fishing.404.small.png deleted file mode 100644 index 84f294885..000000000 Binary files a/doc/api/response/fishing.404.small.png and /dev/null differ diff --git a/doc/api/response/index.html.spt b/doc/api/response/index.html.spt deleted file mode 100644 index 29bf99dee..000000000 --- a/doc/api/response/index.html.spt +++ /dev/null @@ -1,84 +0,0 @@ -doc_title = "Response" -doc_next = ('Virtual Paths', '/virtual-paths/') -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -
The aspen.Response class has this constructor:
def __init__(self, code=200, body='', headers=None): - """Takes an int, a string, and a dict (or list of tuples). - - - code an HTTP response code, e.g., 404 - - body the message body as a string - - headers a Headers instance - - Code is first because when you're raising your own Responses, they're - usually error conditions. Body is second because one more often wants - to specify a body without headers, than a header without a body. - - """- - -
The Default Response Object
- -A Response object is automatically instantiated for all
-requests. This object is automatically available in the second page of your simplates, where it is named response.
One common thing to do with the response object is to set a
-header. The response.headers attribute is the same as on Request objects, so here’s how you
-would set a header in a simplate:
response.headers['X-My-Header'] = 'Greetings, program!' -\[---] -Check your headers.- - -
Raising Responses
- -You can also raise Response instances, because
-Response is a subclass of Python's built-in Exception
-class.
Make a simplate named fishing.html.spt with this content:
from aspen import Response -\[---] -raise Response(200) -\[---] -Let's go fishing!- -{{ screenshot("fishing.200") }} - -
Did you expect to see “Let's go fishing!” instead? The reason
-you don’t is that when you raise Response() from a simplate,
-the template page of the simplate is skipped. This is because the feature is
-really designed for exceptions, things like 404, etc.
So change the HTTP code in fishing.html.spt:
from aspen import Response -\[---] -raise Response(404) -\[---] -Let's go fishing!- -
You will get this:
- -{{ screenshot("fishing.404") }} - - -Custom Response Objects
- -For advanced use cases, you can define your own Response class
-and instantiate it inside of your simplates. Whatever is named
-“response” at the end of page two of a simplate will be what Aspen
-uses to capture the template output and respond to the client. That is, the
-variable named “response” should be your Response
-instance. It will be used as a response, and—unless you raise
-it—its body attribute will be replaced with the output of the template
-page.
Aspen creates an instance of aspen.website.Website when it
-starts up. It holds all of the global configuration for your application. It is
-placed in the namespace of your simplates, where it
-is available from the first page onwards. The following attributes are defined
-based on configuration in the environment (ASPEN_NAME) and keyword
-arguments to Website:
| attribute | default |
| base_url | '' |
| changes_reload | False |
| charset_dynamic | UTF-8 |
| charset_static | None |
| indices | ['index', 'index.html', 'index.json', - 'index.html.spt', 'index.json.spt'] |
| list_directories | False |
| logging_threshold | 0 (most verbose) |
| media_type_default | text/plain |
| media_type_json | application/json |
| project_root | None |
| renderer_default | stdlib_percent |
| show_tracebacks | False |
| colorize_tracebacks | False |
| www_root | None |
| unavailable | 0 |
Computations
- -The following computations are performed after environment and keyword -argument configuration is processed.
- --
-
-
- If www_root isn’t set, then it’s set to the current - working directory If that is unavailable then aspen exits with a - ConfigurationError. If the current working directory differs from www_root, - it is changed to match www_root. - -
- If project_root is set, then the directory it points to is used
- to resolve
{% extends %}and {% include %} templates tags; any mime.types file in there will be loaded; and it will be - placed at the front of sys.path, so you can import Python modules from - there
-
- - Two dictionaries associated with resolving renderers are instantiated - and populated: renderer_factories and - default_renderers_by_media_type. - -
After your configuration scripts are run, Aspen looks at the value for -unavailable, and if it’s greater than zero it installs a handler that -returns 503 - Service Unavailable for all requests. The value of unavailable is -interpreted as the number of minutes of downtime you expect, and the -Retry-After header is set accordingly. You can access the header as a -datetime.datetime object at website.retry_after.
- - -Methods
- -Here are the methods on the Website object:
- -def redirect(self, location, code=None, permanent=False, base_url=None, response=None): - """Raise a redirect Response. - - If code is None then it will be set to 301 (Moved Permanently) if - permanent is True and 302 (Found) if it is False. If url doesn't start - with base_url (defaulting to self.base_url), then we prefix it with - base_url before redirecting. This is a protection against open - redirects. If you provide your own response we will set .code and - .headers['Location'] on it. - - """ --{% end %} diff --git a/doc/configuration/index.html.spt b/doc/configuration/index.html.spt deleted file mode 100644 index 2d0464b49..000000000 --- a/doc/configuration/index.html.spt +++ /dev/null @@ -1,32 +0,0 @@ -doc_title = "Configuration" -doc_next = "" -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -
Aspen websites can be configured consistently from the environment and
-keyword arguments. For each of the following there is an environment variable
-like ASPEN_NAME and a keyword argument to `aspen.website.Website`.
-Here is an example configuration:
| name | example value |
| base_url | http://www.example.com |
| changes_reload | yes |
| charset_dynamic | ISO-8859-1 |
| charset_static | windows-1252 |
| indices | index.html, README |
| list_directories | False |
| logging_threshold | 1 |
| media_type_default | text/plain |
| media_type_json | application/json |
| project_root | /usr/local/mysite |
| show_tracebacks | True |
| colorize_tracebacks | True |
| www_root | /usr/local/mysite/www |
| unavailable | 0 |
Please refer to the website page for -defaults.
-{% end %} diff --git a/doc/core-algorithms/index.html.spt b/doc/core-algorithms/index.html.spt deleted file mode 100644 index 29797b2fa..000000000 --- a/doc/core-algorithms/index.html.spt +++ /dev/null @@ -1,36 +0,0 @@ -doc_title = "Core Algorithms" -doc_next = ("Unicode", "/unicode/") - -from aspen.algorithms import website - -website_funcs = [] -srcfile = website.__file__ -if srcfile.endswith(b'c'): srcfile = srcfile[:-1] # turn .pyc into .py - -for line in open(srcfile): - if line.startswith(b'def '): - website_funcs.append(line[4:].strip().strip(b':')) - -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -Aspen's request-processing algorithm is implemented
-with a module called algorithm. If you
-want to modify
-
-Aspen's behavior
-you should read up on the algorithm module
-and refer to the algorithm definitions below and in the Aspen source code.
Website Algorithm
- -This is available at website.algorithm. Here are the signatures
-of the functions in the stock request-processing algorithm:
{{ b'\n\n'.join(website_funcs) }}
-
-{% end %}
diff --git a/doc/deployment/index.html.spt b/doc/deployment/index.html.spt
deleted file mode 100644
index 7dde43b2b..000000000
--- a/doc/deployment/index.html.spt
+++ /dev/null
@@ -1,78 +0,0 @@
-doc_title="Deployment"
-doc_next = ''
-[----------------------------------------]
-{% extends doc.html %}
-{% block doc %}
-
-Aspen is a WSGI application, located at
-aspen.wsgi.website. That’s an instance of
-aspen.website.Website, configured only from the environment. If
-you need more control, you can instantiate that class yourself. In any case,
-here are some ways to get it on the network.
Gunicorn
- -Gunicorn is a preforking server ported -from Ruby.
- --$ cd /path/to/my/website -$ gunicorn aspen.wsgi:website -2011-05-17 17:07:53 [40170] [INFO] Starting gunicorn 0.12.1 -2011-05-17 17:07:53 [40170] [INFO] Listening at: http://127.0.0.1:8000 (40170) -2011-05-17 17:07:53 [40170] [INFO] Using worker: sync -2011-05-17 17:07:53 [40171] [INFO] Booting worker with pid: 40171 -- - -
Spawning
- -Spawning is a preforking -and/or prethreading server that supports graceful code reloading.
- --$ cd /path/to/my/website -$ spawning aspen.wsgi.website -(40266) *** Controller starting at Tue May 17 17:27:34 2011 -Should start 4 new children -(40270) wsgi starting up on http://0.0.0.0:8080/ -(40267) wsgi starting up on http://0.0.0.0:8080/ -(40268) wsgi starting up on http://0.0.0.0:8080/ -(40269) wsgi starting up on http://0.0.0.0:8080/ -- -
Apache mod_fastcgi
- -To get this to work you'll need: - - -An .htaccess file (or other appropriate apache config file) that includes: - --<Files myfcgi> - SetHandler fastcgi-script -</Files> -- -and then myfcgi is a script that looks like: - -
-#!/bin/bash -INSTDIR=/path/to/my/aspen/project -export ASPEN_PROJECT_ROOT=$INSTDIR/src -export ASPEN_WWW_ROOT=$INSTDIR/www - -source $INSTDIR/bin/activate -$INSTDIR/bin/fcgi_aspen "$@" -- -Notes: -
-
-
- fcgi_aspen requires that you have the flup package installed in your virtualenv. -
- The ASPEN_PROJECT_ROOT and ASPEN_WWW_ROOT dirs are of course relatively arbitrarily named - I just picked obvious ones. -
- There's a bit of an issue if someone hits the node without a trailing slash: in this case aspen gets the full path from root to the script, instead of just the extra path supplied 'under' the script. Dealing with this is up to the reader. -
Downloads
- -- - aspen-{{ version }}.tar.bz2, - tar.gz, - zip, - PyPI, - GitHub -
- - -Continuous Integration
- - - - -
Support
- - - - -Impressions
- -- {{ random.choice(impressions) }}
Showcase - Something to add? -
- --
-
-
- Gratipay, weekly payments, - motivated by gratitude - -
- Keystone, - a web framework inspired by Aspen - -
- Burned Media, a personal - homepage - -
- Approximatrix, Solutions - for Numerical Computing - -
- Mongs, a web-based data - browser for MongoDB - -
- Gheat, heatmaps for - Google Maps - -
- Source - code for http://aspen.io/ itself - -
Demos - Something to add? -
- - - - -
Documentation for Developers
- --
-
- Quick - Start - -
- Simplates - -
- API - - -
- Core Algorithms -
- JSON -
- Testing -
- Unicode -
- Virtual Paths -
Documentation for Sysadmins
- --
-
- Configuration -
- Deployment -
- Configuration Files
-
-
-
mime.types
- project_root
-
-
Your Page - -
Aspen maps your URLs directly to the filesystem. - It’s way simpler than regular expression routing or - object traversal. Capture path parts with virtual paths.
- -
Your Simplate - -
On the filesystem you have a simplate. This is one file with - three pages: import, request, and template.
- -
Your Library - -
Mature projects keep functionality in object-oriented, - tested, documented libraries. Of course, you have the full - power and depth of Python as well.
- -
-
-
- Want more? Here’s a - 50-minute video from PyOhio 2011.
- -Aspen ships with a json_dump renderer that will
-Python-eval the contents of the template section and then call
-json.dumps on it.
Example
- -Make a greetings.json.spt file with this content:
import random
-n = random.choice(range(10))
-extra_excitement = "!" * n
-\[---] via json_dumps
-{'Greetings': 'program!' + extra_excitement}
-
-
-Now hit this in your -browser:
- -{{ screenshot("json") }} - - - -The aspen.json Library
-
-Aspen’s json_dump renderer does not use the standard
-library's json module. Rather, it uses an extended version of it
-from aspen.json. The purpose of this extension is twofold:
-
-
- to delegate to
simplejsonif available
- - to provide nicer encoder configuration -
Supported Implementations
- -Aspen's aspen.json library will prefer simplejson if
-it is available, falling back to the standard library’s json module,
-which was added in Python 2.6. The latter is a more or less out-of-date version
-of the former. It also doesn’t have any C speedups. If Aspen can’t
-find either, then attempts to use the json_dump renderer will
-raise an ImportError.
Default Encoders
- -Aspen's aspen.json will serialize instances of the following
-types. Instances of any other type will raise TypeError, so be
-sure to pre-process your output if it contains anything else.
-
-
bool
- complex(serialized to two floats, [real, imaginary])
- datetime.datetime(serialized to ISO 8601)
- float
- int
- long
- None
- str
- unicode
-
Custom Encoders
- -It’s fairly common to want to add encoders for custom classes or
-classes otherwise unknown to one or another version of simplejson.
-To this end, Aspen provides an API to manage a registry of encoders. These
-functions can be imported from aspen.json:
-def register_encoder(cls, encode): - """Register the encode function for cls. - - An encoder should take an instance of cls and return something - basically serializable (strings, lists, dictionaries). - - """ - -def unregister_encoder(cls): - """Given a class, remove any encoder that has been registered for it. - """ -- -
These functions don’t affect the underlying simplejson
-library, only the Aspen abstraction layer. So if for example you have a
-simplejson that knows about Decimal objects (support for which was
- added in version 2.1 of the library), then if you register a custom
-encoder for Decimals, Aspen will use that where appropriate, and if you
-unregister it, the underlying implementation will be used again. Furthermore,
-if you use the simplejson library directly, the encoders
-registered with aspen.json won’t be used at all.
Aspen automatically sets the Content-Type response header based
-on the file extension of the simplate file being served (you can override this
-behavior by setting the header manually in your simplates). Aspen instructs the
-mimetypes
-module in the Python standard library to use the following mappings to
-determine which Content-Type to use for which file extension.
-
-
- The default
type_mapin your Python installation's -mimetypesmodule
- - a
mime.typesfile bundled with Aspen
- ${website.project_root}/mime.types
-
Later definitions override earlier ones.
- -Example
- -Let’s say that you want to use the .smpl file extension
-to denote simplates on your filesystem. You might want to do this because
-it’s easier to configure your text editor based on a unique
-extension.
Create a file named greetings.smpl with this content:
<h1>Greetings, program!</h1>- -
Now hit it with your -browser:
- -{{ screenshot("text.plain") }} - -You get atext/plain response, because the .smpl
-extension is unknown to Aspen, and text/plain is Aspen’s
-default.
-
-Now put the following line in a file named mime.types in your
-site’s project_root directory
-(note the lack of a period before smpl).
text/html smpl- -
Restart aspen to pick up the new mime.types file,
-and then hit foo.smpl again. You should now have a rendered HTML
-file:
Aspen supports the following networking libraries via plugins. Cheroot is the default -and is packaged with Aspen. They vary -slightly in their implementation of the WSGI spec. This document describes the -differences.
- --
-
- CherryPy(via aspen-cherrypy) -
- Cheroot -
- Diesel(via aspen-diesel) -
- Eventlet<(via aspen-eventlet)/li> -
- Gevent<(via aspen-gevent)/li> -
- Pants<(via aspen-pants)/li> -
- Rocket(via aspen-rocket) -
- Tornado(via aspen-tornado) -
- Twisted(via aspen-twisted) -
Cheroot
- - -{% end %} diff --git a/doc/nice-errors/index.html.spt b/doc/nice-errors/index.html.spt deleted file mode 100644 index 5b75b1412..000000000 --- a/doc/nice-errors/index.html.spt +++ /dev/null @@ -1,23 +0,0 @@ -doc_title = "Nice Errors and Indexes" -doc_next = ("Unicode", "/unicode/") -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -Aspen comes with default pages for errors (404, 500, etc) and -directory indexes ( if --list-directories is enabled ). You may, -however, wish to override or replace them. If so, Aspen will look for: - -
-
-
- project_root/errorcode.html -
- project_root/error.html -
Similarly, Aspen will look in project_root -for a file 'autoindex.html' if a raw directory is named and there's no index -file in that directory to respond with. -
- -{% end %} diff --git a/doc/power-of-python.png b/doc/power-of-python.png deleted file mode 100644 index ee990ab6c..000000000 Binary files a/doc/power-of-python.png and /dev/null differ diff --git a/doc/project_root/index.html.spt b/doc/project_root/index.html.spt deleted file mode 100644 index 91deb63e5..000000000 --- a/doc/project_root/index.html.spt +++ /dev/null @@ -1,58 +0,0 @@ -doc_title = "project_root" -doc_next = [] -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -Aspen can be configured with a project_root directory, a catchall for files -that don’t belong in your actual URL hierarchy. Think of it as your -site’s junk drawer.
- -Previous versions of Aspen hard-wired this to a directory named
-.aspen inside ${website.www_root}, but that was inflexible and
-people struggled with hidden directories on Mac OS. Even earlier versions used
-a cleverly-named __ directory as a virtualenv with a UNIX-y userland layout. So
-conf files were under etc/, modules under
-lib/python/, and templates under etc/templates/. For
-reasons of versioning and deployment (most of which were first put into my head
-by Jim
- Fulton), it turns out to be better for project_root to be
-flat.
configuration files
- -Aspen will read the mime.types file
-from project_root.
Python modules
- -The project_root directory is placed on sys.path
-during startup, so you can place Python modules directly inside of this
-directory and they will be available to your simplates.
This means that the project_root directory is a lightweight sandbox.
-It is sufficient as such if Aspen itself is globally installed, and your site
-doesn’t need more than pure-Python modules. If you don’t want to
-install Aspen globally (and I don’t blame you), or you have other Python
-dependencies that have C extension modules, console scripts, or other things
-that need to be run through distutils before being made accessible to you, then
-you should use a full virtualenv. In this case
-I’ve had success using project_root itself as a virtualenv, though
-you could also locate your virtualenv outside of your site tree.
Template bases and includes
- -The template page of simplates will look in
-project_root for base templates for
-{% extends %} and file snippets for {%
- include %}. You can specify relative paths there, so if you would
-like to add a little structure to project_root here you can.
Given: POSIX -and virtualenv - -
Step 1: Make a -sandbox:
- -$ virtualenv foo -$ cd foo -$ . bin/activate- -
Step 2: Install aspen from - PyPI:
- -(foo)$ pip install aspen -blah -blah -blah- -
Step 3: Create a website root:
- -(foo)$ mkdir www -(foo)$ cd www- -
Step 4: Create a web page:
- -(foo)$ echo Greetings, program! > index.html.spt- -
Step 5: Start a dev server:
- -(foo)$ python -m aspen -[...] Greetings, program! Welcome to port 8080.- -
Step 6: Check localhost for -your new page!
- -{{ screenshot("greetings-program") }} - -{% end %} diff --git a/doc/request/index.html.spt b/doc/request/index.html.spt deleted file mode 100644 index 782643602..000000000 --- a/doc/request/index.html.spt +++ /dev/null @@ -1,2 +0,0 @@ -website.redirect("/api/request/") -[----------------------------------------] diff --git a/doc/response/index.html.spt b/doc/response/index.html.spt deleted file mode 100644 index a02d11cc4..000000000 --- a/doc/response/index.html.spt +++ /dev/null @@ -1,2 +0,0 @@ -website.redirect("/api/response/") -[----------------------------------------] diff --git a/doc/security.txt b/doc/security.txt deleted file mode 100644 index f40099ee7..000000000 --- a/doc/security.txt +++ /dev/null @@ -1,19 +0,0 @@ - - - -UPDATE: Aspen's security program is now at https://hackerone.com/aspen - - - -Old Acknowledgements -==================== - -Black2Fan https://twitter.com/Black2Fan -https://github.com/gratipay/security-qf35us/issues/1 - -dstufft -https://github.com/gratipay/gratipay.com/issues/800#issuecomment-15493967 -https://twitter.com/dstufft/status/319607503061131266 - -Berkay Aydin -https://twitter.com/Brkay_Aydin/status/377611459942817792 diff --git a/doc/security/index.html b/doc/security/index.html deleted file mode 100644 index 83d3b8855..000000000 --- a/doc/security/index.html +++ /dev/null @@ -1,23 +0,0 @@ -doc_title = "Security" -doc_next = "" -^L -{% extends doc.html %} -{% block doc %} - -This page collects security matters that developers should be aware of when -creating applications with Aspen. If you have security bugs to disclose, you -can use the email and PGP key listed here.
- -The biggest thing to be aware of when deploying Aspen applications is to be -careful of what ends up in your web publishing root. If an attacker is able to -write files into your web publishing root, then the attacker can execute -arbitrary Python code with the permissions of the user that the Aspen process -is running as.
- -In particular, watch out for:
- --
-
- File uploads. Never write user-uploaded files
-
-
-{% end %}
diff --git a/doc/simplates/extra-excitement.png b/doc/simplates/extra-excitement.png
deleted file mode 100644
index aa9789528..000000000
Binary files a/doc/simplates/extra-excitement.png and /dev/null differ
diff --git a/doc/simplates/extra-excitement.small.png b/doc/simplates/extra-excitement.small.png
deleted file mode 100644
index 1cf02bf99..000000000
Binary files a/doc/simplates/extra-excitement.small.png and /dev/null differ
diff --git a/doc/simplates/index.html.spt b/doc/simplates/index.html.spt
deleted file mode 100644
index 61eb07fd9..000000000
--- a/doc/simplates/index.html.spt
+++ /dev/null
@@ -1,237 +0,0 @@
-doc_title = "Simplates"
-doc_next = ('Request', '/request/')
-[---]
-[---]
-{% extends doc.html %}
-{% block doc %}
-
-
Simplates are the file format Aspen uses -to represent HTTP resources. They are Aspen’s main attraction. -Here’s what a simplate looks like:
- -"""This is my simplate. -""" -import random - -\[---] -n = random.choice(range(10)) -extra_excitement = "!" * n - -\[---] -Greetings, program!%(extra_excitement)s -
- -Simplates are a single file with one or more sections. The section separator -is
- - -[---].Tutorial
- -Assuming you’ve gone through the Quick -Start, edit index.html.spt with the above content, then refresh.
- -{{ screenshot("extra-excitement") }} - -You’re off and running!
- -Give it a shot: Anything you define in the first two (Python) sections is -available in the third (template) section.
- -Can you guess what the difference is between the first two Python sections? -The first one is run once, the first time the section is hit (not on -startup), and again any time the simplate is changed. It’s designed for -imports and constants. The second is run once for each request.
- - -Reference
- -A simplate is a file that contains multiple sections of varying syntax, -separated by
- -[---].If the simplate only has one section, it's a template.
- -If there's more than one section, the first section is always Python, -and the last section is always a template.
- -If there's more than two sections, the second section is Python -unless it has a specline, which makes it a template.
- -The first Python section is the 'once' section. It is -
- -exec'd once, the first time the resource represented by the -simplate is served, and it has these variables as builtins:__file__ the absolute path to the simplate file (symlinks preserved) - -website an instance of a Website object that gives you access to - configuration
- - -The second Python section is the 'every' section. It is -
- -exec'd once per request. Its context cascades from the -'once' section (if it exists), and adds:request a request object - -response a response object
- -The third page uses the templating language of your choosing—we call -this the “renderer.” The default renderer is the basic templating - language that Python uses to render strings: %(varname)s is replaced by the - variable 'varname' as a string. More details are available in the Python - docs. Other built-in templating languages are stdlib_format - (using - Python string formatting), stdlib_template (using Python - template strings), and json. There are - modules available with support for Tornado - (aspen-tornado), Jinja2 - (aspen-jinja2) and Pystache - (aspen-pystache). - -
The way to specify a renderer is with a so-called “specline” at -the start of the content page:
- -program = "program" -\[---] via pystache -Greetings, {{ program }}!- -You can set the default renderer for a given media type (presuming it is -installed) like so:
- -website.default_renderers_by_media_type['text/html'] = 'pystache'
- -Here’s how to directly set the default renderer for all media types:
- -website.default_renderers_by_media_type.default_factory = lambda: 'pystache'
- -This can also be phrased as:
- -website.renderer_default = 'pystache'
- -You can also set the default renderer globally using the renderer_default -keyword argument to Website, or the ASPEN_RENDERER_DEFAULT environment -variable.
- - -Bound Simplates
- -If a simplate file has a penultimate file extension -(
- - -foo.html.sptas opposed tofoo.spt), then it is -considered to be a “bound simplate”: it is bound to a particular -media type. In this case the first and second sections (the Python sections) -are optional.Unbound Simplates
- -If a simplate file has no penultimate file extension (
foo.spt-as opposed tofoo.html.spt), then it is considered to be an “unbound simplate”: it is not bound to any particular media type. - -Instead, unbound simplates can have multiple so-called “content” -sections, and the order they appear in will determine their priority in HTTP content - negotiation. If negotiation fails you’ll get a 406 - Not Acceptable response, with a prioritized list of available media - types. Joe Gregorio’s content - negotiation module is vendored in to do the heavy lifting. The format -of the file is like this:
- -import foo, json - -\[---] -data = foo.bar(request) - -\[---] text/plain via pystache -{{ data }} - -\[---] application/json -{{ json.dumps(data) }}- -The first two sections of the file are logic sections as described above. -Both are required for an unbound simplate. After that may appear an unlimited -number of content sections. The first line of each content section is the -so-called “specline,” where you must specify the media type of that -content section. You may optionally specify a renderer on the specline as -well.
- -If a file does have a file extension, then it is a “bound -simplate” with a media type computed from the file extension. It is a -
- - -SyntaxErrorfor a file to have both a penultimate extension and -multiple content sections.Indirect Negotiation
- -The canonical way to perform HTTP media type negotiation is with the Accept -request header. That’s much more cumbersome than changing the file -extension in the URL, however, so Aspen supports both. If a request comes in -for
- - -/foo.htmland there’s nofoo.html.spton -the filesystem but there is afoo.sptfile, then Aspen will -serve the request with that. If you requestfoo.txtbut -foo.sptdoesn’t include a text/plain page then you’ll -get a 404, whereas with direct negotiation as above you would get a 406 with a -list of available media types.Encoding
- -By default, simplate files are presumed to be ASCII; if non-ASCII characters -(utf8, for example) are to be included in the file, an encoding must be specifed as per -PEP 263, which means -putting the phrase 'encoding: utf8' somewhere on the first two lines of the file. - - -
Caching
- -All simplate pages are cached in a compiled state. This cache is invalidated -whenever the underlying file changes, so simplate changes are always -immediately available. When you change Python libraries or configuration files, -aspen can restart automatically. But even this extra second or so is a drag -during development. When you change a simplate, the changes are always -available immediately, without restarting the server.
- - - -Ack! Mixing logic and presentation?!?!?
- -Well, I like to think that simplates bring code and presentation as close -together as possible without mixing them. There are no arbitrary Python -blocks inside of the template page, à la PHP/ASP.
- -Simplates are more like MVC, but with controllers, views, and templates -together in the same file instead of in separate files. Your models live in a -Python library, use an ORM, etc. And URL routing is done via the -filesystem. There’s all around less boilerplate.
- -Simplates make it easy to kick off development of an app or feature of an -app. Simplates are, in fact, downright slippery. You won’t be able to -stop innovating. You just open a single file and start writing Python, -JavaScript, CSS, HTML, SQL—whatever. It takes zero wiring to get it on -the network for the first time. And as apps/features mature, you will very -naturally move code out of your single simplate into separate Python libraries, -template files, JSON endpoint simplates, JavaScript libraries, CSS files, -etc.
- -Don’t be scared! This isn’t PHP! It’s MVC with less -crap.
- - - -History
- -My friend Steve came up with the original idea for simplates in the early -aughts, when we were running a web design shop together. We were heavily into -Zope and Plone at the time. This was in the Zope 2 days. The original idea was -something like, “What if you could put a Script (Python) and a ZPT in THE -SAME FILE!?” Steve has since switched careers to philosophy. I debuted -simplates in Aspen 0.8, which came out in December of 2007. I made simplates -the main attraction in Aspen 0.9.
- -{% end %} diff --git a/doc/simplates/sorry-program.png b/doc/simplates/sorry-program.png deleted file mode 100644 index 9c9c671bd..000000000 Binary files a/doc/simplates/sorry-program.png and /dev/null differ diff --git a/doc/simplates/sorry-program.small.png b/doc/simplates/sorry-program.small.png deleted file mode 100644 index b0d1f1006..000000000 Binary files a/doc/simplates/sorry-program.small.png and /dev/null differ diff --git a/doc/success/approximatrix.html.spt b/doc/success/approximatrix.html.spt deleted file mode 100644 index 519c620fb..000000000 --- a/doc/success/approximatrix.html.spt +++ /dev/null @@ -1,34 +0,0 @@ -doc_title = "Success Story: Approximatrix" -doc_next = () -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -
- -
“I saw your talk - at PyOhio this past summer. After the conference, I decided to give -Aspen a try firsthand, and I found it a pleasure to work with. I have since -converted my small business’s website from a cluttered, obsolete Plone -installation to a very clean Aspen implementation. The site is at http://approximatrix.com.
- -“The site is almost entirely static with the exception of the News. -The goal was to show News from the site itself and also from a product’s -site, which was available through an RSS feed. I was able to build an RSS feed -using Aspen pretty easily. Next, to get the news stories from two sites to -appear on the front page, I simply used the feedparser module to request the -news feed from the product’s site and the site’s own rss feed and -assemble the page, all via Aspen. Not particularly complicated, but it did -simplify creating and maintaining a simple small business home page.
- -“Anyway, I just wanted to share and thank you for the hard work on -Aspen. The whole framework was easy to use, especially for someone with -minimal web development experience like myself. I look forward to seeing and -hearing more about it!”
- -—Jeffrey Armstrong, October 25, 2011
- -{% end %} - diff --git a/doc/success/approximatrix.png b/doc/success/approximatrix.png deleted file mode 100644 index 55cee927a..000000000 Binary files a/doc/success/approximatrix.png and /dev/null differ diff --git a/doc/testing/index.html.spt b/doc/testing/index.html.spt deleted file mode 100644 index 8f7dac1d6..000000000 --- a/doc/testing/index.html.spt +++ /dev/null @@ -1,39 +0,0 @@ -doc_title = "Testing" -doc_next = '' - -[---] -{% extends doc.html %} -{% block doc %} - -Aspen includes a test client to help you test your website.
- -Here's a basic test script using pytest:
- --from pytest import yield_fixture -from aspen.testing.client import Client - -@yield_fixture -def client(): - yield Client(www_root='www') - -def test_my_page_greetings_programs(client): - response = client.GET('/my/page.html') - assert response.body == "Greetings, program!" -- -The client provides both GET and POST methods. The first argument is an URL -path (not a file path). If a given URL is expected to raise a response, you can -capture it using the
- -xvariants:-def test_changing_thing_breaks(client): - response = client.PxST('/change-thing.html', data={b'foo': b'bar'}) - assert response.code == 400 -- -Each client instance instantiates a separate website instance. It does this -lazily, when you actually perform a request using GET or POST. You can call -
- -{% end %} diff --git a/doc/unicode/index.html.spt b/doc/unicode/index.html.spt deleted file mode 100644 index 26573fac4..000000000 --- a/doc/unicode/index.html.spt +++ /dev/null @@ -1,192 +0,0 @@ -# -*- coding: utf-8 -*- -doc_title = "Unicode" -doc_next = ('Virtual Paths', '/virtual-paths/') - -""" - -ERRATA IN #36 -Canonical_Represenation -in the string "G/Y" - -""" - -response.charset = "UTF-8" -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - - - -hydrate_websiteto trigger this directly.According - to Guido, Python “has excellent support for Unicode, and will -keep getting better.” The same is true of ... oh no! Snowman -is being attacked by Comet! -But, look! Linear - Buck, hero from beyond the Basic - Multilingual Plane, is coming to his rescue! Hooray for Linear -Buck!
- -- ☄
- -
-
- ☃ - ð‚‚ -In designing Aspen’s Unicode handling, the following priorities have -been in view:
- --
-
-
- Aspen should handle Unicode securely. - -
- Aspen should observe standards. - -
- Aspen should interoperate with consumer-grade web browsers (Internet - Explorer, etc.) where they diverge from standards. - -
- Aspen should enable access to raw bytestrings for advanced use - cases. - -
This document describes Aspen’s approach to Unicode security, and then -describes Aspen’s algorithms for decoding Requests and encoding -Responses, with reference to the de jure standards, de facto browser -behavior, and advanced use cases.
- - -Security
- -The canonical reference for security issues related to Unicode is this -Technical Report from the Unicode Consortium:
- - - -Most of the discussion revolves around spoofing websites by registering -visually confusing domain names such as
- -paypаl.com, where -the second ‘a’ is actually from the - Cyrillic and not the Latin alphabet. That’s a problem for browser -vendors to solve, and for you to take advantage of, if you’re a Bad Guy -like Comet (just watch out for Linear Buck!).What Snowman has to worry about are the “Non-Visual Security -Issues.” The basic idea is that any algorithm that mutates character data -is a chance for Comet to game that algorithm. If Comet can sneak in an extra -path separator or remove a quotation mark, then she may be able to traverse -Snowman’s filesystem or inject some extra SQL. What is Snowman to do?
- -Validate late!
- -After validating your inputs, make sure that you don’t transcode the -data again before using it. Here’s a simple illustration:
- --
-
-
- Comet sends a request for
/..%2Fetc%2Fpassword.
-
- - Snowman conscientiously checks the request for path separators - (“/”). - -
- Snowman doesn’t find any path separators and let’s the - request through. - -
- Later on in his program, Snowman decodes the percent-encoding in this - value. Guess what %2F decodes to. - -
- Finally, Snowman runs
open("/../etc/password").read()and - returns the result to Comet.
-
-
Obviously this is a contrived example but it makes the point. TR36 mentions -seven algorithms in Unicode and goes into the details of how to game them:
- --
-
- normalization—e.g., folding multiple accent combinations - together -
- fallbacks—substituting
eor -ⓔ for â“”
- - non-shortest-form—conflating \xC1\x9C with \5C to both - mean backslash -
- ill-formed sequences—replacing or deleting bad bytes -
- text comparison—sorting, searching, matching -
- buffer overruns—falsely assuming data will fit in a - certain amount of memory -
- deletion—removing non-character data (different than - removing bad bytes) -
The good news is that Python handles almost all of these for us, and Aspen -handles the rest. If Aspen is given an HTTP Request that doesn’t decode -cleanly according to the algorithm below, then it returns a 400 Bad -Request.
- - - -Decoding Requests
- -Here are the parts of the Request with notes on how -Aspen decodes them:
- --request - line - method subset of ASCII, per spec - uri - path subset of ASCII, per spec (but WSGI servers do - things) - querystring subset of ASCII, per spec (but IE sends raw - UTF-8) - version - headers ??? - body ??? -
- -If a browser or other program sends anything else to Aspen, it’ll get -400 Bad Request.
- - - -Encoding Responses
- -The Aspen Response object takes body as a -bytestring or iterable of bytestrings. If you set response.charset in a -template resource then that will be added to Content-Type if your mimetype is -of major type 'text'. There is no default charset for static resources, which -means HTTP-conformant clients will try ISO-8859-1, but most will probably try -to guess based on how the bytes smell.
- -{% end %} diff --git a/doc/unicode/linear-b.eot b/doc/unicode/linear-b.eot deleted file mode 100644 index 9bf7f1f10..000000000 Binary files a/doc/unicode/linear-b.eot and /dev/null differ diff --git a/doc/unicode/linear-b.svg b/doc/unicode/linear-b.svg deleted file mode 100644 index c29af09a7..000000000 --- a/doc/unicode/linear-b.svg +++ /dev/null @@ -1,401 +0,0 @@ - - - \ No newline at end of file diff --git a/doc/unicode/linear-b.ttf b/doc/unicode/linear-b.ttf deleted file mode 100644 index e350cc993..000000000 Binary files a/doc/unicode/linear-b.ttf and /dev/null differ diff --git a/doc/unicode/linear-b.woff b/doc/unicode/linear-b.woff deleted file mode 100644 index 322cfef13..000000000 Binary files a/doc/unicode/linear-b.woff and /dev/null differ diff --git "a/doc/unicode/\342\230\203.html.spt" "b/doc/unicode/\342\230\203.html.spt" deleted file mode 100644 index 66bea3aae..000000000 --- "a/doc/unicode/\342\230\203.html.spt" +++ /dev/null @@ -1 +0,0 @@ -Greetings, program! diff --git "a/doc/unicode/\342\230\204.html" "b/doc/unicode/\342\230\204.html" deleted file mode 100644 index 66bea3aae..000000000 --- "a/doc/unicode/\342\230\204.html" +++ /dev/null @@ -1 +0,0 @@ -Greetings, program! diff --git a/doc/virtual-paths/1999.png b/doc/virtual-paths/1999.png deleted file mode 100644 index ea181d3b8..000000000 Binary files a/doc/virtual-paths/1999.png and /dev/null differ diff --git a/doc/virtual-paths/1999.small.png b/doc/virtual-paths/1999.small.png deleted file mode 100644 index 9606e5cc4..000000000 Binary files a/doc/virtual-paths/1999.small.png and /dev/null differ diff --git a/doc/virtual-paths/aspen.png b/doc/virtual-paths/aspen.png deleted file mode 100644 index f184d474f..000000000 Binary files a/doc/virtual-paths/aspen.png and /dev/null differ diff --git a/doc/virtual-paths/aspen.small.png b/doc/virtual-paths/aspen.small.png deleted file mode 100644 index 7cc9e2d88..000000000 Binary files a/doc/virtual-paths/aspen.small.png and /dev/null differ diff --git a/doc/virtual-paths/cheese.png b/doc/virtual-paths/cheese.png deleted file mode 100644 index 4507112f1..000000000 Binary files a/doc/virtual-paths/cheese.png and /dev/null differ diff --git a/doc/virtual-paths/cheese.small.png b/doc/virtual-paths/cheese.small.png deleted file mode 100644 index df86af61f..000000000 Binary files a/doc/virtual-paths/cheese.small.png and /dev/null differ diff --git a/doc/virtual-paths/index.html.spt b/doc/virtual-paths/index.html.spt deleted file mode 100644 index 0207fcc03..000000000 --- a/doc/virtual-paths/index.html.spt +++ /dev/null @@ -1,117 +0,0 @@ -doc_title = "Virtual Paths" -doc_next = '' -[----------------------------------------] -{% extends doc.html %} -{% block doc %} - -Aspen supports dynamic URLs using virtual paths, which are specially-named -directories and files on your filesystem.
- - -Directories
- -Make a directory on your filesystem called
- -%name.$ mkdir %name
- -Then make an
- -index.html.sptsimplate -in there with this content:[---] -Greetings, {{ path['name'] }}!- -Now hit http://localhost:8080/aspen/. You -should see this:
- -{{ screenshot("aspen") }} - -Now hit http://localhost:8080/python/. You -should see:
- -{{ screenshot("python") }} - -Get it?
- - -Files
- -Aspen will also match files that start with a percent sign (
- -%). -Make a simplate in%namenamed%cheese.txt, with this -content:[---] -{{ path['name'].title() }} likes {{ path['cheese'] }} cheese. -- -Now test it out:
- -{{ screenshot("cheese") }} - -Virtual path files only work for the last URL path part, so if you hit /chad/cheddar.txt/ (with -a trailing slash), you’ll get a 404:
- -{{ screenshot("no-cheese") }} - -Virtual path files (only! not directories!) are greedy, however. -so if you hit -/chad/swiss/gruyere.txt then since it ends in .txt and there's no real -
-swissdirectory to take precedence, the%cheese.txt-file will be used, withcheeseequal toswiss/gruyere-.The general philosophy of aspen's matching with virtual paths and greedy -virtual filenames is Most specific wins, so if there's a real -directory named
swisswith a file namedgruyere.txt-in it, then that real file will be preferred over the virtual one. - -Typecasting
- -By default, path parts are decoded to Python unicode objects using ASCII, -and are then unquoted (per urllib.unquote). -You can also typecast path parts to arbitrary objects, by registering -typecasters in the
- -website.typecastersdictionary. A typecaster -is a function that takes two positional arguments, the path part as a -unicodeand thestatedictionary from the current algorithm run, and returns an -object. Typecasters forintandfloatare included -out of the box.Make a directory called
- -%year.int-(for files, put the cast before the file extension, like -%year.int.html.spt).$ mkdir "%year.int"
- -Then put an
index.html.sptin there with this content: - -[---] -Tonight we're going to party like it's {{ path['year'] }}!- -Now hit http://localhost:8080/1999/. What -do you get?
- -{{ screenshot("oops") }} - -Wait ... where's the party?
- - -Gotcha!
- -You can only have one variable directory per level. If you have more than -one, the case-insensitive alphabetically first is used. Get it?
- -Remove the
- -%namedirectory:$ rm -rf %name
- -Now refresh, and you should see:
- -{{ screenshot("1999") }} - -That’s better. Yay filesystem!
- -{% end %} diff --git a/doc/virtual-paths/no-cheese.png b/doc/virtual-paths/no-cheese.png deleted file mode 100644 index 8dbd1c386..000000000 Binary files a/doc/virtual-paths/no-cheese.png and /dev/null differ diff --git a/doc/virtual-paths/no-cheese.small.png b/doc/virtual-paths/no-cheese.small.png deleted file mode 100644 index 506e2e2e4..000000000 Binary files a/doc/virtual-paths/no-cheese.small.png and /dev/null differ diff --git a/doc/virtual-paths/oops.png b/doc/virtual-paths/oops.png deleted file mode 100644 index 98a868365..000000000 Binary files a/doc/virtual-paths/oops.png and /dev/null differ diff --git a/doc/virtual-paths/oops.small.png b/doc/virtual-paths/oops.small.png deleted file mode 100644 index bd1113cf7..000000000 Binary files a/doc/virtual-paths/oops.small.png and /dev/null differ diff --git a/doc/virtual-paths/python.png b/doc/virtual-paths/python.png deleted file mode 100644 index 6daf8b45a..000000000 Binary files a/doc/virtual-paths/python.png and /dev/null differ diff --git a/doc/virtual-paths/python.small.png b/doc/virtual-paths/python.small.png deleted file mode 100644 index 4592ac658..000000000 Binary files a/doc/virtual-paths/python.small.png and /dev/null differ