Quick search

Table Of Contents

Url Request

New in version 1.0.8.

You can use the UrlRequest to make asynchronous requests on the web and get the result when the request is completed. The spirit is the same as the XHR object in Javascript.

The content is also decoded if the Content-Type is application/json and the result automatically passed through json.loads.

The syntax to create a request:

from kivy.network.urlrequest import UrlRequest
req = UrlRequest(url, on_success, on_error, req_body, req_headers)

Only the first argument is mandatory: the rest are optional. By default, a “GET” request will be sent. If the UrlRequest.req_body is not None, a “POST” request will be sent. It’s up to you to adjust UrlRequest.req_headers to suite your requirements.

Example of fetching twitter trends:

def got_twitter_trends(req, result):
    trends = result[0]['trends']
    print('Last %d twitter trends:' % len(trends))
    for trend in trends:
        print(' - ', trend['name'])

req = UrlRequest('https://api.twitter.com/1/trends/1.json',
        got_twitter_trends)

Example of Posting data (adapted from httplib example):

import urllib

def bug_posted(req, result):
    print('Our bug is posted !')
    print(result)

params = urllib.urlencode({'@number': 12524, '@type': 'issue',
    '@action': 'show'})
headers = {'Content-type': 'application/x-www-form-urlencoded',
          'Accept': 'text/plain'}
req = UrlRequest('bugs.python.org', on_success=bug_posted, req_body=params,
        req_headers=headers)

If you want a synchronous request, you can call the wait() method.

class kivy.network.urlrequest.UrlRequest(url, on_success=None, on_redirect=None, on_failure=None, on_error=None, on_progress=None, req_body=None, req_headers=None, chunk_size=8192, timeout=None, method=None, decode=True, debug=False, file_path=None)[source]

Bases: threading.Thread

A UrlRequest. See module documentation for usage.

Changed in version 1.5.1: Add debug parameter

Changed in version 1.0.10: Add method parameter

Parameters:
url: str

Complete url string to call.

on_success: callback(request, result)

Callback function to call when the result has been fetched.

on_redirect: callback(request, result)

Callback function to call if the server returns a Redirect.

on_failure: callback(request, result)

Callback function to call if the server returns a Client or Server Error.

on_error: callback(request, error)

Callback function to call if an error occurs.

on_progress: callback(request, current_size, total_size)

Callback function that will be called to report progression of the download. total_size might be -1 if no Content-Length has been reported in the http response. This callback will be called after each chunk_size is read.

req_body: str, defaults to None

Data to sent in the request. If it’s not None, a POST will be done instead of a GET.

req_headers: dict, defaults to None

Custom headers to add to the request.

chunk_size: int, defaults to 8192

Size of each chunk to read, used only when on_progress callback has been set. If you decrease it too much, a lot of on_progress callbacks will be fired and will slow down your download. If you want to have the maximum download speed, increase the chunk_size or don’t use on_progress.

timeout: int, defaults to None

If set, blocking operations will timeout after this many seconds.

method: str, defaults to ‘GET’ (or ‘POST’ if body is specified)

The HTTP method to use.

decode: bool, defaults to True

If False, skip decoding of the response.

debug: bool, defaults to False

If True, it will use the Logger.debug to print information about url access/progression/errors.

file_path: str, defaults to None

If set, the result of the UrlRequest will be written to this path instead of in memory.

New in version 1.8.0: Parameter decode added. Parameter file_path added. Parameter on_redirect added. Parameter on_failure added.

chunk_size[source]

Return the size of a chunk, used only in “progress” mode (when on_progress callback is set.)

decode_result(result, resp)[source]

Decode the result fetched from url according to his Content-Type. Currently supports only application/json.

error[source]

Return the error of the request. This value is not determined until the request is completed.

get_connection_for_scheme(scheme)[source]

Return the Connection class for a particular scheme. This is an internal function that can be expanded to support custom schemes.

Actual supported schemes: http, https.

is_finished[source]

Return True if the request has finished, whether it’s a success or a failure.

req_body = None

Request body passed in __init__

req_headers = None

Request headers passed in __init__

resp_headers[source]

If the request has been completed, return a dictionary containing the headers of the response. Otherwise, it will return None.

resp_status[source]

Return the status code of the response if the request is complete, otherwise return None.

result[source]

Return the result of the request. This value is not determined until the request is finished.

url = None

Url of the request

wait(delay=0.5)[source]

Wait for the request to finish (until resp_status is not None)

Note

This method is intended to be used in the main thread, and the callback will be dispatched from the same thread from which you’re calling.

New in version 1.1.0.