HTTPS/HTTP Fetch

Ren'Py supports fetching information over HTTP and HTTPS using the renpy.fetch function. This function:

• Supports GET, POST, and PUT requests.

• Support POSTing or PUTing data or json to the server.

• Can return the result as bytes, a string, or a json object.

The fetch function is meant to be used in the main thread of Ren'Py, after the game has started. It can be used on desktop, mobile, or the web platform. When used on the web platform, when not fetching from the same server that originally served the game, the server must support CORS.

As a very simple example, this gets news from a server:

$ news = renpy.fetch("https://example.com/news.txt", result="text")
"Here's the news: [news]"

And this posts JSON to a server, and gets JSON back:

$ result = renpy.fetch("https://example.com/api", json={"name": "Ren'Py"}, result="json")

As with any application that communicates over the network, security needs to be considered when using renpy.fetch, especially when displaying media returned this way. (Ren'Py is generally not hardened against malicious images, movies, and audio files.)

renpy.fetch(url, method=None, data=None, json=None, content_type=None, timeout=5, result='bytes', params=None, headers={})

This performs an HTTP (or HTTPS) request to the given URL, and returns the content of that request. If it fails, raises a FetchError exception, with text that describes the failure. (But may not be suitable for presentation to the user.)

url

The URL to fetch.

method

The method to use. Generally one of "GET", "POST", or "PUT", but other HTTP methods are possible. If data or json are not None, defaults to "POST", otherwise defaults to GET.

data

If not None, a byte string of data to send with the request.

json

If not None, a JSON object to send with the request. This takes precendence over data.

content_type

The content type of the data. If not given, defaults to "application/json" if json is not None, or "application/octet-stream" otherwise. Only used on a POST or PUT request.

timeout

The number of seconds to wait for the request to complete.

result

How to process the result. If "bytes", returns the raw bytes of the result. If "text", decodes the result using UTF-8 and returns a unicode string. If "json", decodes the result as JSON. (Other exceptions may be generated by the decoding process.)

params

A dictionary of parameters that are added to the URL as a query string.

headers

A dictionary of headers to send with the request.

This may be called from inside or outside of an interaction.

• Outside of an interation, while waiting for timeout to pass, this will repeatedly call renpy.pause(), so Ren'Py doesn't lock up. It may make sense to display a screen to the user to let them know what is going on.

• Inside of an interaction (for example, inside an Action), this will block the display system until the fetch request finishes or times out. It will try to service the audio system, so audio will continue to play.

This function should work on all platforms. However, on the web platform, requests going to a different origin than the game will fail unless allowed by CORS.

Requests

On desktop and mobile, Ren'Py includes the Requests library. This is more powerful, but doesn't integrate as well as renpy.fetch. (For example, Ren'Py will call renpy.pause() to wait for data, while requests will block, which could lead to problems like audio stalling.)