diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..51648dd --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,35 @@ + +API Documentation +================= + + +Web Service (API) Class +----------------------- +.. module:: responder + +.. autoclass:: API + :inherited-members: + +Requests & Responses +-------------------- + + +.. autoclass:: Request + :inherited-members: + +.. autoclass:: Response + :inherited-members: + + +Utility Functions +----------------- + +.. autofunction:: responder.API.status_codes.is_100 + +.. autofunction:: responder.API.status_codes.is_200 + +.. autofunction:: responder.API.status_codes.is_300 + +.. autofunction:: responder.API.status_codes.is_400 + +.. autofunction:: responder.API.status_codes.is_500 diff --git a/docs/source/index.rst b/docs/source/index.rst index 3d9b5f6..fab236b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -79,80 +79,14 @@ Testimonials .. _Two Scoops of Django: .. _on Tom Christie joining the project: https://twitter.com/pabloteleco/status/1050841098321620992?s=20 -More Examples -------------- +User Guides +----------- -Class-based views (and setting some headers and stuff):: +.. toctree:: + :maxdepth: 2 - @api.route("/{greeting}") - class GreetingResource: - def on_request(req, resp, *, greeting): # or on_get... - resp.text = f"{greeting}, world!" - resp.headers.update({'X-Life': '42'}) - resp.status_code = api.status_codes.HTTP_416 - - -Render a template, with arguments:: - - - @api.route("/{greeting}") - def greet_world(req, resp, *, greeting): - resp.content = api.template("index.html", greeting=greeting) - - -The ``api`` instance is available as an object during template rendering. - -Here, you can spawn off a background thread to run any function, out-of-request:: - - @api.route("/") - def hello(req, resp): - - @api.background.task - def sleep(s=10): - time.sleep(s) - print("slept!") - - sleep() - resp.content = "processing" - - -Serve a GraphQL API:: - - import graphene - - class Query(graphene.ObjectType): - hello = graphene.String(name=graphene.String(default_value="stranger")) - - def resolve_hello(self, info, name): - return "Hello " + name - - api.add_route("/graph", graphene.Schema(query=Query)) - - -We can then send a query to our service:: - - >>> requests = api.session() - >>> r = requests.get("http://;/graph", params={"query": "{ hello }"}) - >>> r.json() - {'data': {'hello': 'Hello stranger'}} - - -Or, request YAML back:: - - >>> r = requests.get("http://;/graph", params={"query": "{ hello(name:\"john\") }"}, headers={"Accept": "application/x-yaml"}) - >>> print(r.text) - data: {hello: Hello john} - - - -Want HSTS? - -:: - - api = responder.API(enable_hsts=True) - - -Boom. + tour + api Installing Responder @@ -244,40 +178,6 @@ Future Ideas - If frontend websites are supported, provide an official way to run webpack. -API Documentation -================= - - -Web Service (API) Class ------------------------ -.. module:: responder - -.. autoclass:: API - :inherited-members: - -Requests & Responses --------------------- - - -.. autoclass:: Request - :inherited-members: - -.. autoclass:: Response - :inherited-members: - - -Utility Functions ------------------ - -.. autofunction:: responder.API.status_codes.is_100 - -.. autofunction:: responder.API.status_codes.is_200 - -.. autofunction:: responder.API.status_codes.is_300 - -.. autofunction:: responder.API.status_codes.is_400 - -.. autofunction:: responder.API.status_codes.is_500 Indices and tables ================== diff --git a/docs/source/tour.rst b/docs/source/tour.rst new file mode 100644 index 0000000..42bccc6 --- /dev/null +++ b/docs/source/tour.rst @@ -0,0 +1,90 @@ +Feature Tour +============ + + +Class-Based Views +----------------- + +Class-based views (and setting some headers and stuff):: + + @api.route("/{greeting}") + class GreetingResource: + def on_request(req, resp, *, greeting): # or on_get... + resp.text = f"{greeting}, world!" + resp.headers.update({'X-Life': '42'}) + resp.status_code = api.status_codes.HTTP_416 + +Templare Rendering +------------------ +Render a template, with arguments:: + + + @api.route("/{greeting}") + def greet_world(req, resp, *, greeting): + resp.content = api.template("index.html", greeting=greeting) + + +The ``api`` instance is available as an object during template rendering. + +Background Tasks +---------------- + +Here, you can spawn off a background thread to run any function, out-of-request:: + + @api.route("/") + def hello(req, resp): + + @api.background.task + def sleep(s=10): + time.sleep(s) + print("slept!") + + sleep() + resp.content = "processing" + + +GraphQL +------- + +Serve a GraphQL API:: + + import graphene + + class Query(graphene.ObjectType): + hello = graphene.String(name=graphene.String(default_value="stranger")) + + def resolve_hello(self, info, name): + return "Hello " + name + + api.add_route("/graph", graphene.Schema(query=Query)) + + +Built-in Testing Client (Requests) +---------------------------------- + +We can then send a query to our service:: + + >>> requests = api.session() + >>> r = requests.get("http://;/graph", params={"query": "{ hello }"}) + >>> r.json() + {'data': {'hello': 'Hello stranger'}} + + +Or, request YAML back:: + + >>> r = requests.get("http://;/graph", params={"query": "{ hello(name:\"john\") }"}, headers={"Accept": "application/x-yaml"}) + >>> print(r.text) + data: {hello: Hello john} + + +HSTS (Redirect to HTTPS) +------------------------ + +Want HSTS? + +:: + + api = responder.API(enable_hsts=True) + + +Boom.