From 5a7447e975d48039467f41ee1a35f23ab381218d Mon Sep 17 00:00:00 2001 From: Channel Cat Date: Fri, 14 Oct 2016 04:51:08 -0700 Subject: [PATCH] Basic documentation --- README.md | 6 +++++- docs/contributing.md | 10 +++------ docs/exceptions.md | 28 +++++++++++++++++++++++++ docs/getting_started.md | 23 ++++++++++++++++++++ docs/middleware.md | 25 ++++++++++++++++++++++ docs/request_data.md | 43 ++++++++++++++++++++++++++++++++++++++ docs/routing.md | 32 ++++++++++++++++++++++++++++ examples/try_everything.py | 2 +- setup.py | 2 +- 9 files changed, 161 insertions(+), 10 deletions(-) create mode 100644 docs/middleware.md diff --git a/README.md b/README.md index b58b2fb2..091c796d 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ All tests were run on a AWS medium instance running ubuntu, using 1 process. Ea ## Hello World -``` +```python from sanic import Sanic from sanic.response import json @@ -49,6 +49,10 @@ app.run(host="0.0.0.0", port=8000) * RESTful router * Blueprints? +## Limitations: + * No wheels for uvloop and httptools on Windows :( + * Can only run on 1 cpu per worker + ## Final Thoughts: ▄▄▄▄▄ diff --git a/docs/contributing.md b/docs/contributing.md index d95f4d8d..e39a7247 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,14 +1,10 @@ -========================== -How to contribute to Sanic -========================== +# How to contribute to Sanic Thank you for your interest! -Running tests ---------------------- +## Running tests * `python -m pip install pytest` * `python -m pytest tests` -Caution -======= +## Warning One of the main goals of Sanic is speed. Code that lowers the performance of Sanic without significant gains in usability, security, or features may not be merged. \ No newline at end of file diff --git a/docs/exceptions.md b/docs/exceptions.md index e69de29b..92634bab 100644 --- a/docs/exceptions.md +++ b/docs/exceptions.md @@ -0,0 +1,28 @@ +# Exceptions + +Check sanic.exceptions for a list of exceptions + +## Throwing an exception + +```python +from sanic import Sanic +from sanic.exceptions import ServerError + +@app.route('/killme') +def i_am_ready_to_die(request): + raise ServerError("Something bad happened") +``` + +## Handling Exceptions + +Just use the @exception decorator. The decorator expects a list of exceptions to handle as arguments. You can pass SanicException to catch them all! The exception handler must expect a request and exception object as arguments. + +```python +from sanic import Sanic +from sanic.response import text +from sanic.exceptions import NotFound + +@app.exception(NotFound) +def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting_started.md index e69de29b..54882cda 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -0,0 +1,23 @@ +# Getting Started + +Make sure you have pip and python 3.5 before starting + +## Benchmarks + * Install Sanic + * `python3 -m pip install git+https://github.com/channelcat/sanic/` + * Edit main.py + * ```python3 +from sanic import Sanic +from sanic.response import json + +app = Sanic(__name__) + +@app.route("/") +async def test(request): + return json({ "hello": "world" }) + +app.run(host="0.0.0.0", port=8000, debug=True) +``` + * Run `python3 main.py` + +You now have a working sanic server! To build more features, continue on in the documentation \ No newline at end of file diff --git a/docs/middleware.md b/docs/middleware.md new file mode 100644 index 00000000..3e257b84 --- /dev/null +++ b/docs/middleware.md @@ -0,0 +1,25 @@ +# Middleware + +Middleware can be executed before or after requests. It is executed in the order it was registered. If middleware return a reponse object, the request will stop processing and a response will be returned. + +Middleware is registered via the middleware decorator, and can either be added as 'request' or 'response' middleware, based on the argument provided in the decorator. Response middleware receives both the request and the response as arguments. + +## Examples + +```python +app = Sanic('__name__') + +@app.middleware +async def halt_request(request): + return text('I halted the request') + +@app.middleware('response') +async def halt_response(request, response): + return text('I halted the response') + +@app.route('/') +async def handler(request): + return text('I would like to speak now please') + +app.run(host="0.0.0.0", port=8000) +``` \ No newline at end of file diff --git a/docs/request_data.md b/docs/request_data.md index e69de29b..b006c08c 100644 --- a/docs/request_data.md +++ b/docs/request_data.md @@ -0,0 +1,43 @@ +# Request Data + +## Properties + +The following request variables are accessible as properties: + +request.files (dictionary of File objects) - List of files that have a name, body, and type +request.json (any) - JSON body +request.args (dict) - Query String variables. Use getlist to get multiple of the same name +request.form (dict) - Posted form variables. Use getlist to get multiple of the same name + +See request.py for more information + +## Examples + +```python +from sanic import Sanic +from sanic.response import json + +@app.route("/json") +def post_json(request): + return json({ "received": True, "message": request.json }) + +@app.route("/form") +def post_json(request): + return json({ "received": True, "form_data": request.form, "test": request.form.get('test') }) + +@app.route("/files") +def post_json(request): + test_file = request.files.get('test') + + file_parameters = { + 'body': test_file.body, + 'name': test_file.name, + 'type': test_file.type, + } + + return json({ "received": True, "file_names": request.files.keys(), "test_file_parameters": file_parameters }) + +@app.route("/query_string") +def query_string(request): + return json({ "parsed": True, "args": request.args, "url": request.url, "query_string": request.query_string }) +``` \ No newline at end of file diff --git a/docs/routing.md b/docs/routing.md index e69de29b..ed252036 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -0,0 +1,32 @@ +# Routing + +Sanic comes with a basic router that supports request parameters. To specify a parameter, surround it with carrots like so: . Request parameters will be passed to the request handler functions as keyword arguments. To specify a type, add a :type after the parameter name, in the carrots. If the parameter does not match the type supplied, Sanic will throw a NotFound exception, resulting in a 404 page not found error. + + +## Examples + +```python +from sanic import Sanic +from sanic.response import json + +@app.route('/tag/') +async def person_handler(request, tag): + return text('Tag - {}'.format(tag)) + +@app.route('/number/') +async def person_handler(request, integer_arg): + return text('Integer - {}'.format(integer_arg)) + +@app.route('/number/') +async def person_handler(request, number_arg): + return text('Number - {}'.format(number)) + +@app.route('/person/') +async def person_handler(request, person_id): + return text('Person - {}'.format(folder_id)) + +@app.route('/folder/') +async def folder_handler(request, folder_id): + return text('Folder - {}'.format(folder_id)) + +``` \ No newline at end of file diff --git a/examples/try_everything.py b/examples/try_everything.py index 936a53ae..5d3b022e 100644 --- a/examples/try_everything.py +++ b/examples/try_everything.py @@ -39,7 +39,7 @@ def post_json(request): @app.route("/form") def post_json(request): - return json({ "received": True, "form_data": request.form, "penos": request.form.get('penos') }) + return json({ "received": True, "form_data": request.form, "test": request.form.get('test') }) @app.route("/query_string") def query_string(request): diff --git a/setup.py b/setup.py index a5c369e2..6e0ed72b 100644 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ from setuptools import setup setup( name='Sanic', - version="0.0.2", + version="0.1.0", url='http://github.com/channelcat/sanic/', license='BSD', author='Channel Cat',