Skip to content
Browse files

update readme, specs and license

  • Loading branch information...
1 parent 154769a commit cccd4ad686b6e11a6586aab47947e990402f7084 Adeel Ahmad Khan committed Jul 26, 2011
Showing with 165 additions and 65 deletions.
  1. +20 −0 LICENSE
  2. +0 −65 README
  3. +86 −0 README.md
  4. +59 −0 SPEC.md
View
20 LICENSE
@@ -0,0 +1,20 @@
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
View
65 README
@@ -1,65 +0,0 @@
-Pump is a low-level library for developing web applications in Python. It
-is meant to improve on WSGI by providing a clean, developer-friendly API.
-Heavily inspired by Clojure's Ring and Ruby's Rack.
-
-Pump apps are easily converted to WSGI apps. WSGI middleware can also be
-converted to Pump middleware.
-
-EXAMPLE.
-
- # test.py
-
- import pump
-
- def app(req):
- return {"status": 200, "headers": {"content_type": "text/plain"},
- "body": "Hello, world!"}
-
- pump.adapters.serve_with_paste(app, {"port": 3000})
-
-This requires the Paste WSGI server <http://pythonpaste.org> to run.
-
-DESCRIPTION.
-
--- A Pump app is a function that takes a Pump request and returns a Pump
-response.
-
--- A Pump request is a dict with the following keys.
-
- -- server_port
- Corresponds to SERVER_PORT in WSGI's environ.
- -- server_name
- Corresponds to SERVER_NAME in WSGI's environ.
- -- remote_addr
- Corresponds to REMOTE_ADDR in WSGI's environ (not required by specs).
- -- uri
- Corresponds to RAW_URI in WSGI's environ, or PATH_INFO if it is not
- given.
- -- query_string
- The portion of the request URL that follows the "?". Corresponds to
- QUERY_STRING in WSGI's environ.
- -- scheme
- "http" or "https". Corresponds to wsgi.url_scheme in WSGI's environ.
- -- method
- "GET", "POST", etc. Corresponds to REQUEST_METHOD in WSGI's environ.
- -- headers
- A dict containing the request headers. Each key-value pair corresponds
- to a key in WSGI's environ starting with "HTTP_". If there are multiple
- headers for a single key, headers[key] will be the list of values.
- -- content_type
- Corresponds to CONTENT_TYPE in WSGI's environ.
- -- content_length
- Corresponds to CONTENT_LENGTH in WSGI's environ.
- -- body
- The HTTP request body as a stream. Corresponds to wsgi.input in WSGI's
- environ.
-
--- A Pump response is a dict with the following keys.
-
- -- status
- An integer, e.g. 200, 404.
- -- headers
- A dict containing the response headers, e.g.
- {'content_type': 'text/html'}.
- -- body
- A string containing the body of the response.
View
86 README.md
@@ -0,0 +1,86 @@
+# Pump User Manual
+
+**Pump** is a dead simple abstraction of HTTP for Python.
+
+## Summary
+
+The Pump specification consists of headers, requests, responses, apps, and middleware. Below are examples of each.
+
+**Pump requests**.
+
+ {"server_port": "80",
+ "server_name": "127.0.0.1",
+ "remote_addr": "127.0.0.1",
+ "uri": "/",
+ "scheme": "http",
+ "method": "get",
+ "headers":
+ {"accept_charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
+ "connection": "keep-alive",
+ "host": "localhost:8000",
+ ...}}
+
+**Pump responses**.
+
+ {"status": 200,
+ "headers": {"content_type": "text/plain"},
+ "body": "Hello!"}
+
+**Pump apps**.
+
+ def app(req):
+ if req["uri"] == "/favicon.ico":
+ return {"status": 404, headers: {}, body: "Not Found"}
+ return {"status": 200,
+ "headers": {"content_type": "text/html"},
+ "body": "<h1>Hello!</h1>"}
+
+**Pump middleware**.
+
+ def wrap_with_logger(app):
+ def wrapped(req):
+ response = app(req)
+ print "%s %s\n => %s" % (req["method"],
+ req["uri"],
+ response)
+ return response
+ return wrapped
+
+For the detailed specification, see `SPEC.md`.
+
+## Getting started
+
+### Installation
+
+To install, type
+
+ $ pip install pump
+
+or grab the code from [Github](https://github.com/adeel/pump):
+
+ $ git clone git://github.com/adeel/pump.git
+ $ cd pump
+ $ python setup.py install
+
+### Running your app
+
+Pump comes with an adapter for the [Paste WSGI server](http://pythonpaste.org/modules/httpserver.html). If you don't have that installed, do
+
+ $ pip install Paste
+
+and then to run your app:
+
+ import pump
+ pump.adapters.serve_with_paste(app, {"port": 3000})
+
+Soon, Pump will come with adapters for other popular WSGI servers.
+
+## Thanks
+
+Pump was heavily inspired by Clojure's [Ring](https://github.com/mmcgrana/ring). Thanks, Mark McGranaghan!
+
+## License
+
+Copyright (c) 2011 Adeel Ahmad Khan <adeel@adeel.ru>.
+
+MIT license.
View
59 SPEC.md
@@ -0,0 +1,59 @@
+# Pump specification
+
+The Pump specification consists of headers, requests, responses, apps, and middleware.
+
+## Pump headers
+
+**Pump headers** are closely related to HTTP headers.
+
+A Pump header is represented as a key-value pair. An HTTP header name and value can be transformed into a Pump header by stripping "HTTP_" from the beginning of the name and downcasing; the value stays the same. A Pump header is transformed into an HTTP header by exactly the reverse operation.
+
+## Pump requests
+
+**Pump requests** are an abstraction of HTTP requests.
+
+A pump request is a dictionary with the following keys.
+
+**server_port** (str, required). The port on which the request is being handled.
+
+**server_name** (str, required). The resolved server name, or the server IP address.
+
+**remote_addr** (str, required). The IP address of the client or the last proxy that sent the request.
+
+**uri** (str, required). The request URI. Starts with '/'.
+
+**query_string** (str, optional). The portion of the request URI that follows the '?'.
+
+**scheme** (str, required). The transport protocol: "http" or "https".
+
+**method** (str, required). The HTTP request method: "get", "head", "options", "put", "post", or "delete".
+
+**content_type** (str, optional). The MIME type of the request body, if known.
+
+**content_length** (int, optional). The number of bytes in the request body, if known.
+
+**character_encoding** (str, optional). The character encoding used in the request body, if known.
+
+**headers** (dict, required). A dict of Pump headers in the request. In case two headers have the same key, they are merged into one header whose value is a list containing both of their values.
+
+**body** (input stream, optional). A file-like object containing the request body, if present.
+
+## Pump responses
+
+**Pump responses** are an abstraction of HTTP responses.
+
+A Pump response is a dictionary with the following keys.
+
+**status** (int, required). The HTTP status code (e.g. 200 or 404).
+
+**headers** (dict, required). A dict containing the Pump headers in the response (e.g. {"content_type": "text/html"}). In case the value of some header is a list, the corresponding HTTP response will have multiple headers for each value in the list.
+
+**body** (str or list or file, optional). The response body. If it is a string, it will be sent as is. If it is a list, each element will be sent as a string. If it is a file, its contents are sent.
+
+## Pump apps
+
+A **Pump app** is a function that takes a Pump request and returns a Pump response.
+
+## Pump middleware
+
+A **Pump middleware** is a higher-order function that takes a Pump app and returns a Pump app.

0 comments on commit cccd4ad

Please sign in to comment.
Something went wrong with that request. Please try again.