In this tutorial, we’ll go through how to write your first Kyoukai app.
Strap in with your favourite IDE, and create your first new project.
Name it something silly, for example my-first-kyokai-project
. The
name doesn’t matter, as you probably won’t be using it for long.
Kyoukai projects have a very simple layout.
$ ls --tree
├── app.py
├── static
└── templates
There are three components here:
app.py
app
for simplicity’s
sake.templates
static
Open up app.py
and add your starting line.
from kyoukai import Kyoukai
This imports the Kyoukai application class from the library, allowing you to create a new object inside your code.
The central object in your file is the Kyoukai
object. This object is core for handling
requests from clients, including routing and handling errors.
app = Kyoukai("my_app")
The name passed into the constructor is the application name - right now, this is irrelevant. However, it is a required param, so you should pass something like your application’s name.
Routes in Kyoukai are very simple, and if you have ever used Flask, are similar in style to Flask routes.
Routes are made up of three parts:
The path
The allowed methods
GET
) is not
in the list, the route cannot handle it, and a HTTP 405 error will
automatically be passed to the client.The route itself
HTTPRequestContext
, containing the request data
and other context specific data.async def some_route(ctx: HTTPRequestContext): ...
We are going to write a very simple route that returns a
Hello, world!
file.
Routes in Kyoukai are created very similarly to Flask routes: with a decorator.
@app.route("/path", methods=["GET", "POST"])
Note
As explained above, the route decorator takes a path and a method. This route decorator returns a Route class, but this isn’t important right now.
The router decorator can be found on one of two objects:
- Your
Kyoukai
application object (which internally reroutes it toKyoukai.root
)- A
Blueprint
application object.
Your route function must be a coroutine. As Kyoukai is async, your code must also be async.
@app.route("/")
async def index(ctx): ...
Inside our route, we are going to return a string containing the rendered text from our template.
Templates are stored in templates/
, obviously. They are partial HTML
code, which can have parts in it replaced using code inside the template
itself, or your view.
For now, we will put normal HTML in our file.
Open up templates/index.html
and add the following code to it:
It's current year, and you're still using blocking code? Not <em>me!</em>
Warning
Do not replace current year with the actual current year.
Save and close the template.
Since the template is a very simple HTML document, no additional rendering is needed; you can
simply use as_html()
to render the document.
@app.route("/")
async def index(ctx):
with open("templates/index.html") as f:
return as_html(f.read())
as_html()
requires an extra import, from kyoukai.util import as_html
to use. For more
information about these helper functions, see Requests and Responses.
Note, how in the previous coroutine, we simply returned a str
in our
route. This is not similar to aiohttp
and the likes who force you to
return a Response
. You can return a response object in Kyoukai as
normal, but for convenience sake, you can also return simply a string or
a tuple.
These are transparently converted behind the scenes:
r = Response(code=route_result[1] or 200, body=route_result[0], headers=route_result[2] or {})
That is, the first item is converted to your response body, the second item (or 200 by default) is used as the response code, and the third code is used as the headers.
Note
All return params except the first is optional, if you do not return a Response object.
The ideal way of running a Kyoukai project is through the Asphalt framework. See Asphalt usage for more information on how to use this.
However, Kyoukai includes a built-in way of running the app from blocking code.
app.run(ip="127.0.0.1", port=4444)
Note
The args passed in here are just the default values; they are optional.
There’s no special procedure for deploying your app. The inbuilt webserver is production ready, and you can run your application in a production environment in the same way as you would develop it.
You have completed your first Kyoukai project. For maximum effectiveness, you must now publish it to GitHub.
$ git init
$ git remote add origin git@github.com:YourName/my-first-kyoukai-project.git
$ git add .
$ git commit -a -m "Initial commit, look how cool I am!"
$ git push -u origin master