Skip to content

Latest commit

 

History

History
296 lines (232 loc) · 8.82 KB

uWeb.md

File metadata and controls

296 lines (232 loc) · 8.82 KB

uWeb DOCUMENTATION

This is the documentation for uWeb. Click here if you're looking for the docs for uWeb-uasyncio

Table of Contents

Objects

uWeb.uWeb(address, port)

Description

Initialize a uWeb object by configuring socket to bind and listen to specified address and port.

Parameters
  • address - (str) address to listen on
  • port - (int) port to listen on

Attributes

  • uWeb.version - (str) uWeb version
  • uWeb.address - address that is bound to
  • uWeb.port - (int) port that is bound to
  • uWeb.routes_dict - (dict) all routes
  • uWeb.request_command - (str) HTTP method of request(ie: POST, GET, PUT, etc)
  • uWeb.request_path - (str) requested path
  • uWeb.request_http_ver - (str) HTTP version of request
  • uWeb.request_body - (str) body of current request
  • uWeb.request_headers - (dict) headers of current request
  • uWeb.client_socket - (socket) socket object of active socket
  • uWeb.client_address - address of client

Methods

uWeb.routes(routes={})

Description

Use this method to specify routes for the app.

Parameters

  • routes - (dict) dictionary containing routes in format:

    {
    (HTTP_METHOD, PATH): ACTION,
    (HTTP_METHOD, PATH): ACTION
}
    • HTTP_METHOD - method to listen for(see Constants)
    • PATH - URL to listen for
    • ACTION - function to be run when route matches

    Example:

      {
      (uWeb.GET, "/"): home,
      (uWeb.POST, "/post"): post,
      (uWeb.GET, "/json"): jsonn,
      (uWeb.GET, "/header"): header
  }

uWeb.start(log=True)

Description

Start the server.

Parameters
  • log - (bool) default: True; toggle logging of client information and requests to console

uWeb.render(html_file, layout='layout.html', variables=False, status=OK)

Description

Send HTML file to client's browser

Parameters

  • html_file - (str) file name of html file to render

  • layout - (str) layout to render html_file with(see Layout Rendering)

  • variables - (dict) dictionary of variables to render html with(see Template Rendering).

    Example:

    {
  "variable_name_in_html": "replace_with_this",
  "another_one", (1 + 1)
}

  • status - (str) HTTP status to send to client. Default: uWeb.OK(see Constants)

uWeb.sendJSON(dict_to_send={})

Description

Send JSON body to client.

Parameters
  • dict_to_send - (dict) dictionary with JSON data

uWeb.sendFile(filename)

Description
  • Send file to client along with its appropriate Content-Type header. This is automatically called depending on the path of the HTTP request. EX: if a .js is requested, uWeb will look for it and send it if it exists.
  • Add MIME types by appending to the MIME_TYPES dictionary
Parameters
  • filename - (str) name of file to send

uWeb.sendStatus(status_code)

Description

Send HTTP response header to client with specified status

Parameters
  • status_code - (str) HTTP status code(see Constants)

uWeb.sendHeaders(headers_dict={})

Description

Send HTTP headers to client.

Parameters
  • headers_dict - (dict) dictionary containing header and values to be sent to client. Example:
{
      'header1': 'one',
      'header2': 'two',
      'header3': 'three',
}

uWeb.sendBody(body_content)

Description

Send response body content to client

Parameters
  • body_content - (bytestring) body content to send

uWeb.setSupportedFileTypes(file_types = ['js', 'css'])

Description
  • Specify the file extensions to be allowed to be sent to the client if it is requested. Use to protect your backend of your Microcontroller.
  • When allowing additional files, don't forget to include 'js' and 'css' in the list as well
  • This only applies to GET requests. You can still manually send files of any extension with sendFile()
  • NOTE: Be careful when allowing file types such as .py because the client can request /boot.py and may exposed sensitive info such as your wi-fi password if you have it set there.
Parameters
  • file_types - (list) file extensions to whitelist. Default: .js and .css

Helpers

uWeb.router()

Description

Handles requests and run actions when a route matches

uWeb.readFile(file)

Description

Read and encode a file. Depending on your hardware, this method may raise a memory allocation error if the file is larger than the available memory.

Parameters
  • file - (str) filename of file to be read and encoded
Returns
  • (bytestring) encoded file

uWeb.send(content)

Description

Basic method to send bytestring to client

Parameters
  • content - (bytestring) content to send

uWeb.processRequest()

Description

Process request from client by extracting headers to request_headers and extract body to request_body if it is a POST request.

uWeb.resolveRequestLine()

Description

Parse request line from client. Sets: request_command, request_path, and request_http_ver

Returns
  • (bool) True: if a valid request_line; False: if request_line empty

loadJSON(string)

Description

Not part of uWeb class. Easy way to convert a request_body containing a JSON string to a dict

Parameters

  • string - (str) JSON string to convert to dictionary

    Returns

  • (dict) dictionary with converted JSON

Constants

HTTP Methods
  • uWeb.GET = 'GET'
  • uWeb.POST = 'POST'
  • uWeb.PUT = 'PUT'
  • uWeb.DELETE = 'DELETE'
HTTP Status Codes
  • uWeb.OK = b"200 OK"
  • uWeb.NOT_FOUND = b"404 Not Found"
  • uWeb.FOUND = b"302 Found"
  • uWeb.FORBIDDEN = b"403 Forbidden"
  • uWeb.BAD_REQUEST = b"400 Bad Request"
  • uWeb.ERROR = b"500 Internal Server Error"
MIME types
  • 'css': 'text/css'
  • 'html': 'text/html'
  • 'jpeg': 'image/jpeg'
  • 'jpg': 'image/jpeg'
  • 'js': 'text/javascript'
  • 'json': 'application/json'
  • 'rtf': 'application/rtf'
  • 'svg': 'image/svg+xml'