Callbacks

AuthDomainBasicAuthCallback (domain, msg, username, password, *user_data)

AuthDomainDigestAuthCallback (domain, msg, username, *user_data)

AuthDomainFilter (domain, msg, *user_data)

AuthDomainGenericAuthCallback (domain, msg, username, *user_data)

LoggerFilter (logger, msg, *user_data)

LoggerPrinter (logger, level, direction, data, *user_data)

MessageHeadersForeachFunc (name, value, *user_data)

ServerCallback (server, msg, path, query, *user_data)

ServerWebsocketCallback (server, msg, path, connection, *user_data)

Details

Soup.AuthDomainBasicAuthCallback(domain, msg, username, password, *user_data)
Parameters:

  • domain (Soup.AuthDomainBasic) – the domain

  • msg (Soup.ServerMessage) – the message being authenticated

  • username (str) – the username provided by the client

  • password (str) – the password provided by the client

  • user_data (object or None) – the data passed to [method`AuthDomainBasic`.set_auth_callback]

Returns:

True if username and password are valid

Return type:

bool

Callback used by Soup.AuthDomainBasic for authentication purposes.

The application should verify that username and password and valid and return True or False.

If you are maintaining your own password database (rather than using the password to authenticate against some other system like PAM or a remote server), you should make sure you know what you are doing. In particular, don’t store cleartext passwords, or easily-computed hashes of cleartext passwords, even if you don’t care that much about the security of your server, because users will frequently use the same password for multiple sites, and so compromising any site with a cleartext (or easily-cracked) password database may give attackers access to other more-interesting sites as well.

Soup.AuthDomainDigestAuthCallback(domain, msg, username, *user_data)
Parameters:
Returns:

the encoded password, or None if username is not a valid user. domain will free the password when it is done with it.

Return type:

str or None

Callback used by Soup.AuthDomainDigest for authentication purposes.

The application should look up username in its password database, and return the corresponding encoded password (see [func`AuthDomainDigest`.encode_password].

Soup.AuthDomainFilter(domain, msg, *user_data)
Parameters:
Returns:

True if msg requires authentication, False if not.

Return type:

bool

The prototype for a Soup.AuthDomain filter.

See [method`AuthDomain`.set_filter] for details.

Soup.AuthDomainGenericAuthCallback(domain, msg, username, *user_data)
Parameters:
Returns:

True if msg is authenticated, False if not.

Return type:

bool

The prototype for a Soup.AuthDomain generic authentication callback.

The callback should look up the user’s password, call [method`AuthDomain`.check_password], and use the return value from that method as its own return value.

In general, for security reasons, it is preferable to use the auth-domain-specific auth callbacks (eg, [callback`AuthDomainBasicAuthCallback`] and [callback`AuthDomainDigestAuthCallback`]), because they don’t require keeping a cleartext password database. Most users will use the same password for many different sites, meaning if any site with a cleartext password database is compromised, accounts on other servers might be compromised as well. For many of the cases where [class`Server`] is used, this is not really relevant, but it may still be worth considering.

Soup.LoggerFilter(logger, msg, *user_data)
Parameters:
Returns:

a [enum`LoggerLogLevel`] value indicating how much of the message to log

Return type:

Soup.LoggerLogLevel

The prototype for a logging filter.

The filter callback will be invoked for each request or response, and should analyze it and return a [enum`LoggerLogLevel`] value indicating how much of the message to log.

Soup.LoggerPrinter(logger, level, direction, data, *user_data)
Parameters:

The prototype for a custom printing callback.

level indicates what kind of information is being printed. Eg, it will be Soup.LoggerLogLevel.HEADERS if data is header data.

direction is either ‘<’, ‘>’, or ‘ ‘, and data is the single line to print; the printer is expected to add a terminating newline.

To get the effect of the default printer, you would do:

``c printf (“%c %sn”, direction, data); ``

Soup.MessageHeadersForeachFunc(name, value, *user_data)
Parameters:

  • name (str) – the header name

  • value (str) – the header value

  • user_data (object or None) – the data passed to [method`MessageHeaders`.foreach]

The callback passed to [method`MessageHeaders`.foreach].

Soup.ServerCallback(server, msg, path, query, *user_data)
Parameters:

  • server (Soup.Server) – the Soup.Server

  • msg (Soup.ServerMessage) – the message being processed

  • path (str) – the path component of msg's Request-URI

  • query ({str: str} or None) – the parsed query component of msg's Request-URI

  • user_data (object or None) – the data passed to [method`Server`.add_handler] or [method`Server`.add_early_handler].

A callback used to handle requests to a [class`Server`].

path and query contain the likewise-named components of the Request-URI, subject to certain assumptions. By default, [class`Server`] decodes all percent-encoding in the URI path, such that "/foo%2Fbar" is treated the same as "/foo/bar". If your server is serving resources in some non-POSIX-filesystem namespace, you may want to distinguish those as two distinct paths. In that case, you can set the [property`Server`:raw-paths] property when creating the [class`Server`], and it will leave those characters undecoded.

query contains the query component of the Request-URI parsed according to the rules for HTML form handling. Although this is the only commonly-used query string format in HTTP, there is nothing that actually requires that HTTP URIs use that format; if your server needs to use some other format, you can just ignore query, and call [method`Message`.get_uri] and parse the URI’s query field yourself.

See [method`Server`.add_handler] and [method`Server`.add_early_handler] for details of what handlers can/should do.

Soup.ServerWebsocketCallback(server, msg, path, connection, *user_data)
Parameters:

A callback used to handle WebSocket requests to a Soup.Server.

The callback will be invoked after sending the handshake response back to the client (and is only invoked if the handshake was successful).

path contains the path of the Request-URI, subject to the same rules as [callback`ServerCallback`] (qv).