API Documentation¶
ice module¶
Ice - WSGI on the rocks.
Ice is a simple and tiny WSGI microframework meant for developing small Python web applications.
-
exception
ice.
Error
¶ Bases:
Exception
Base class for exceptions.
-
class
ice.
Ice
¶ Bases:
object
A single WSGI application.
Each instance of this class is a single, distinct callable object that functions as WSGI application.
-
download
(content, filename=None, media_type=None, charset='UTF-8')¶ Send content as attachment (downloadable file).
The content is sent after setting Content-Disposition header such that the client prompts the user to save the content locally as a file. An HTTP response status code may be specified as content. If the status code is not
200
, then this method does nothing and returns the status code.The filename used for the download is determined according to the following rules. The rules are followed in the specified order.
- If filename is specified, then the base name from this
argument, i.e.
os.path.basename(filename)
, is used as the filename for the download. - If filename is not specified or specified as
None
(the default), then the base name from the file path specified to a previousstatic()
call made while handling the current request is used. - If filename is not specified and there was no
static()
call made previously for the current request, then the base name from the current HTTP request path is used. - As a result of the above steps, if the resultant filename
turns out to be empty, then
ice.LogicError
is raised.
The media_type and charset arguments are used in the same manner as they are used in
static()
.Parameters: - content (str, bytes or int) – Content to be sent as download or HTTP status code of the response to be returned.
- filename (str) – Filename to use for saving the content
- media_type (str, optional) – Media type of file.
- charset (str, optional) – Character set of file.
Returns: content, i.e. the first argument passed to this method.
Raises: LogicError
– When filename cannot be determined.- If filename is specified, then the base name from this
argument, i.e.
-
error
(status=None)¶ Decorator to add a callback that generates error page.
The status parameter specifies the HTTP response status code for which the decorated callback should be invoked. If the status argument is not specified, then the decorated callable is considered to be a fallback callback.
A fallback callback, when defined, is invoked to generate the error page for any HTTP response representing an error when there is no error handler defined explicitly for the response code of the HTTP response.
Parameters: status (int, optional) – HTTP response status code. Returns: Decorator function to add error handler. Return type: function
-
exit
()¶ Stop the simple WSGI server running the appliation.
-
get
(pattern)¶ Decorator to add route for an HTTP GET request.
Parameters: pattern (str) – Routing pattern the path must match. Returns: Decorator to add route for HTTP GET request. Return type: function
-
post
(pattern)¶ Decorator to add route for an HTTP POST request.
Parameters: pattern (str) – Routing pattern the path must match. Returns: Decorator to add route for HTTP POST request. Return type: function
-
route
(method, pattern)¶ Decorator to add route for a request with any HTTP method.
Parameters: - method (str) – HTTP method name, e.g. GET, POST, etc.
- pattern (str) – Routing pattern the path must match.
Returns: Decorator function to add route.
Return type: function
-
run
(host='127.0.0.1', port=8080)¶ Run the application using a simple WSGI server.
Parameters: - host (str, optional) – Host on which to listen.
- port (int, optional) – Port number on which to listen.
-
running
()¶ Return
True
iff simple WSGI server is running.Returns: True
if simple WSGI server associated with this application is running,False
otherwise.Return type: bool
-
static
(root, path, media_type=None, charset='UTF-8')¶ Send content of a static file as response.
The path to the document root directory should be specified as the root argument. This is very important to prevent directory traversal attack. This method guarantees that only files within the document root directory are served and no files outside this directory can be accessed by a client.
The path to the actual file to be returned should be specified as the path argument. This path must be relative to the document directory.
The media_type and charset arguments are used to set the Content-Type header of the HTTP response. If media_type is not specified or specified as
None
(the default), then it is guessed from the filename of the file to be returned.Parameters: - root (str) – Path to document root directory.
- path (str) – Path to file relative to document root directory.
- media_type (str, optional) – Media type of file.
- charset (str, optional) – Character set of file.
Returns: Content of file to be returned in the HTTP response.
Return type: bytes
-
-
class
ice.
MultiDict
(*args, **kwargs)¶ Bases:
collections.UserDict
Dictionary with multiple values for a key.
Setting an existing key to a new value merely adds the value to the list of values for the key. Getting the value of an existing key returns the newest value set for the key.
-
getall
(key, default=[])¶ Return the list of all values for the specified key.
Parameters: - key (object) – Key
- default (list) – Default value to return if the key does not
exist, defaults to
[]
, i.e. an empty list.
Returns: List of all values for the specified key if the key exists,
default
otherwise.Return type: list
-
-
class
ice.
RegexRoute
(pattern, callback)¶ Bases:
object
A regular expression pattern.
-
static
like
(pattern)¶ Determine if a pattern looks like a regular expression.
Parameters: pattern (str) – Any route pattern. Returns: True
if the specified pattern looks like a regex,False
otherwise.
-
match
(path)¶ Return route handler with arguments if path matches this route.
Parameters: path (str) – Request path Returns: A tuple of three items: - Route handler (callable)
- Positional arguments (list)
- Keyword arguments (dict)
None
if the route does not match the path.Return type: tuple or None
-
static
-
class
ice.
Request
(environ)¶ Bases:
object
Current request.
-
environ
¶ dict – Dictionary of request environment variables.
-
method
¶ str – Request method.
-
path
¶ str – Request path.
-
query
¶ MultiDict – Key-value pairs from query string.
-
form
¶ MultiDict – Key-value pairs from form data in POST request.
MultiDict – Key-value pairs from cookie string.
-
-
class
ice.
Response
(start_response_callable)¶ Bases:
object
Current response.
-
start
¶ callable – Callable that starts response.
-
status
¶ int – HTTP response status code, defaults to 200.
-
media_type
¶ str – Media type of HTTP response, defaults to ‘text/html’. This together with
charset
determines the Content-Type response header.
-
charset
¶ str – Character set of HTTP response, defaults to ‘UTF-8’. This together with
media_type
determines the Content-Type response header.
-
body
¶ str or bytes – HTTP response body.
-
add_header
(name, value)¶ Add an HTTP header to response object.
Parameters: - name (str) – HTTP header field name
- value (str) – HTTP header field value
-
content_type
¶ Return the value of Content-Type header field.
The value for the Content-Type header field is determined from the
media_type
andcharset
data attributes.Returns: Value of Content-Type header field Return type: str
-
response
()¶ Return the HTTP response body.
Returns: HTTP response body as a sequence of bytes Return type: bytes
Add a Set-Cookie header to response object.
For a description about cookie attribute values, see https://docs.python.org/3/library/http.cookies.html#http.cookies.Morsel.
Parameters: - name (str) – Name of the cookie
- value (str) – Value of the cookie
- attrs (dict) – Dicitionary with cookie attribute keys and values.
-
status_detail
¶ Return a description of the current HTTP response status.
Returns: Response status description Return type: str
-
-
class
ice.
Router
¶ Bases:
object
Route management and resolution.
-
add
(method, pattern, callback)¶ Add a route.
Parameters: - method (str) – HTTP method, e.g. GET, POST, etc.
- pattern (str) – Pattern that request paths must match.
- callback (str) – Route handler that is invoked when a request path matches the pattern.
-
contains_method
(method)¶ Check if there is at least one handler for method.
Parameters: method (str) – HTTP method name, e.g. GET, POST, etc. Returns: True
if there is at least one route defined for method,False
otherwise
-
resolve
(method, path)¶ Resolve a request to a route handler.
Parameters: - method (str) – HTTP method, e.g. GET, POST, etc. (type: str)
- path (str) – Request path
Returns: A tuple of three items:
- Route handler (callable)
- Positional arguments (list)
- Keyword arguments (dict)
None
if no route matches the request.Return type: tuple or None
-
-
class
ice.
Wildcard
(spec)¶ Bases:
object
A single wildcard definition in a wildcard route pattern.
-
regex
()¶ Convert the wildcard to a regular expression.
Returns: A regular expression that matches strings that the wildcard is meant to match. Return type: str
-
value
(value)¶ Convert specified value to a value of wildcard type.
This method does not check if the value matches the wildcard type. The caller of this method must ensure that the value passed to this method was obtained from a match by regular expression returned by the regex method of this class. Ensuring this guarantees that the value passed to the method matches the wildcard type.
Parameters: value (str) – Value to convert. Returns: Converted value. Return type: str or int
-
-
class
ice.
WildcardRoute
(pattern, callback)¶ Bases:
object
Route containing wildcards to match request path.
-
static
like
(pattern)¶ Determine if a pattern looks like a wildcard pattern.
Parameters: pattern (str) – Any route pattern. Returns: True
if the specified pattern looks like a wildcard pattern,False
otherwise.
-
match
(path)¶ Return route handler with arguments if path matches this route.
Parameters: path (str) – Request path Returns: A tuple of three items: - Route handler (callable)
- Positional arguments (list)
- Keyword arguments (dict)
None
if the route does not match the path.Return type: tuple or None
-
static
tokens
(pattern)¶ Return tokens in a pattern.
-
static
-
ice.
cube
()¶ Return an Ice application with a default home page.
Create
Ice
object, add a route to return the default page when a client requests the server root, i.e. /, using HTTP GET method, add an error handler to return HTTP error pages when an error occurs and return this object. The returned object can be used as a WSGI application.Returns: WSGI application. Return type: Ice