spiderweb/docs/quickstart.md
2024-08-26 01:56:56 -04:00

3.5 KiB

quickstart

Start by installing the package with your favorite package manager:

poetry add spiderweb-framework
pip install spiderweb-framework
pipenv install spiderweb-framework

Then, create a new file and drop this in it:

from spiderweb import SpiderwebRouter
from spiderweb.response import HttpResponse

app = SpiderwebRouter()

@app.route("/")
def index(request):
    return HttpResponse("HELLO, WORLD!")

if __name__ == "__main__":
    app.start()

Start the dev server by running python {yourfile.py} and navigating to http://localhost:8000/ in your browser. You should see HELLO, WORLD! displayed on the page. Press Ctrl+C to stop the server.

That's it! You've got a working web app. Let's take a look at what these few lines of code are doing:

from spiderweb import SpiderwebRouter

The SpiderwebRouter class is the main object that everything stems from in spiderweb. It's where you'll set your options, your routes, and more.

from spiderweb.response import HttpResponse

Rather than trying to infer what you want, spiderweb wants you to be specific about what you want it to do. Part of that is the One Response Rule:

Every view must return a Response, and each Response must be a specific type.

There are four different types of responses; if you want to skip ahead, hop over to the responses page to learn more. For this example, we'll focus on HttpResponse, which is the base response.

app = SpiderwebRouter()

This line creates a new instance of the SpiderwebRouter class and assigns it to the variable app. This is the object that will handle all of your requests and responses. If you need to pass any options into spiderweb, you'll do that here.

@app.route("/")
def index(request):
    return HttpResponse("HELLO, WORLD!")

This is an example view. There are a few things to note here:

  • The @app.route("/") decorator tells spiderweb that this view should be called when the user navigates to the root of the site.
  • The def index(request): function is the view itself. It takes a single argument, request, which is a Request object that contains all the information about the incoming request.
  • The return HttpResponse("HELLO, WORLD!") line is the response. In this case, it's a simple HttpResponse object that contains the string HELLO, WORLD!. This will be sent back to the user's browser.

Tip

Every view must accept a request object as its first argument. This object contains all the information about the incoming request, including headers, cookies, and more.

There's more that we can pass in, but for now, we'll keep it simple.

if __name__ == "__main__":
    app.start()

Once you finish setting up your app, it's time to start it! You can start the dev server by just calling app.start() (and its counterpart app.stop() to stop it). This will start a simple server on localhost:8000 that you can access in your browser. It's not a secure server; don't even think about using it in production. It's just good enough for development.

Now that your app is done, you can also run it with Gunicorn by running gunicorn --workers=2 {yourfile}:app in your terminal. This will start a Gunicorn server on localhost:8000 that you can access in your browser and is a little more robust than the dev server.