Auth

class Auth(**properties: Any)

Superclasses: Object

Subclasses: AuthBasic, AuthDigest, AuthNTLM, AuthNegotiate

The abstract base class for handling authentication.

Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used.

Auth objects store the authentication data associated with a given bit of web space. They are created automatically by Session.

Constructors

class Auth

classmethod new(type: type, msg: Message, auth_header: str) → Auth | None

Creates a new Auth of type type with the information from msg and auth_header.

This is called by Session; you will normally not create auths yourself.

Parameters:

• type – the type of auth to create (a subtype of Auth)

• msg – the Message the auth is being created for

• auth_header – the WWW-Authenticate/Proxy-Authenticate header

Methods

class Auth

authenticate(username: str, password: str) → None

Call this on an auth to authenticate it.

Normally this will cause the auth’s message to be requeued with the new authentication info.

Parameters:

• username – the username provided by the user or client

• password – the password provided by the user or client

can_authenticate() → bool

Tests if auth is able to authenticate by providing credentials to the authenticate.

cancel() → None

Call this on an auth to cancel it.

You need to cancel an auth to complete an asynchronous authenticate operation when no credentials are provided (authenticate is not called). The Auth will be cancelled on dispose if it hans’t been authenticated.

get_authority() → str

Returns the authority (host:port) that auth is associated with.

get_authorization(msg: Message) → str

Generates an appropriate “Authorization” header for msg.

(The session will only call this if is_authenticated returned True.)

Parameters:

msg – the Message to be authorized

get_info() → str

Gets an opaque identifier for auth.

The identifier can be used as a hash key or the like. Auth objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords).

get_protection_space(source_uri: Uri) → list[str]

Returns a list of paths on the server which auth extends over.

(All subdirectories of these paths are also assumed to be part of auth’s protection space, unless otherwise discovered not to be.)

Parameters:

source_uri – the URI of the request that auth was generated in response to.

get_realm() → str

Returns auth’s realm.

This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.)

get_scheme_name() → str

soup_auth_get_scheme_name: (attributes org.gtk.Method.get_property=scheme-name) Returns auth’s scheme name. (Eg, “Basic”, “Digest”, or “NTLM”)

is_authenticated() → bool

Tests if auth has been given a username and password.

is_cancelled() → bool

Tests if auth has been cancelled

is_for_proxy() → bool

Tests whether or not auth is associated with a proxy server rather than an “origin” server.

is_ready(msg: Message) → bool

Tests if auth is ready to make a request for msg with.

For most auths, this is equivalent to is_authenticated, but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

Parameters:

msg – a Message

update(msg: Message, auth_header: str) → bool

Updates auth with the information from msg and auth_header, possibly un-authenticating it.

As with new, this is normally only used by Session.

Parameters:

• msg – the Message auth is being updated for

• auth_header – the WWW-Authenticate/Proxy-Authenticate header

Properties

class Auth

props.authority: str

The authority (host:port) being authenticated to.

props.is_authenticated: bool

Whether or not the auth has been authenticated.

props.is_cancelled: bool

Whether or not the auth has been cancelled.

props.is_for_proxy: bool

Whether or not the auth is for a proxy server.

props.realm: str

The authentication realm.

props.scheme_name: str

The authentication scheme name.

Virtual Methods

class Auth

do_authenticate(username: str, password: str) → None

Call this on an auth to authenticate it.

Normally this will cause the auth’s message to be requeued with the new authentication info.

Parameters:

• username – the username provided by the user or client

• password – the password provided by the user or client

do_can_authenticate() → bool

Tests if auth is able to authenticate by providing credentials to the authenticate.

do_get_authorization(msg: Message) → str

Generates an appropriate “Authorization” header for msg.

(The session will only call this if is_authenticated returned True.)

Parameters:

msg – the Message to be authorized

do_get_protection_space(source_uri: Uri) → list[str]

Returns a list of paths on the server which auth extends over.

(All subdirectories of these paths are also assumed to be part of auth’s protection space, unless otherwise discovered not to be.)

Parameters:

source_uri – the URI of the request that auth was generated in response to.

do_is_authenticated() → bool

Tests if auth has been given a username and password.

do_is_ready(msg: Message) → bool

Tests if auth is ready to make a request for msg with.

For most auths, this is equivalent to is_authenticated, but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

Parameters:

msg – a Message

do_update(msg: Message, auth_header: dict[None, None]) → bool

Updates auth with the information from msg and auth_header, possibly un-authenticating it.

As with new, this is normally only used by Session.

Parameters:

• msg – the Message auth is being updated for

• auth_header – the WWW-Authenticate/Proxy-Authenticate header

Fields

class Auth

parent_instance