:right-sidebar: True Auth =================================================================== .. currentmodule:: gi.repository.Soup .. class:: Auth(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Soup.AuthBasic`, :class:`~gi.repository.Soup.AuthDigest`, :class:`~gi.repository.Soup.AuthNTLM`, :class:`~gi.repository.Soup.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. :obj:`~gi.repository.Soup.Auth` objects store the authentication data associated with a given bit of web space. They are created automatically by :obj:`~gi.repository.Soup.Session`\. Constructors ------------ .. rst-class:: interim-class .. class:: Auth :no-index: .. classmethod:: new(type: ~gobject.GType, msg: ~gi.repository.Soup.Message, auth_header: str) -> ~gi.repository.Soup.Auth | None Creates a new :obj:`~gi.repository.Soup.Auth` of type ``type`` with the information from ``msg`` and ``auth_header``\. This is called by :obj:`~gi.repository.Soup.Session`\; you will normally not create auths yourself. :param type: the type of auth to create (a subtype of :obj:`~gi.repository.Soup.Auth`\) :param msg: the :obj:`~gi.repository.Soup.Message` the auth is being created for :param auth_header: the WWW-Authenticate/Proxy-Authenticate header Methods ------- .. rst-class:: interim-class .. class:: Auth :no-index: .. method:: 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. :param username: the username provided by the user or client :param password: the password provided by the user or client .. method:: can_authenticate() -> bool Tests if ``auth`` is able to authenticate by providing credentials to the :obj:`~gi.repository.Auth.authenticate`\. .. method:: 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 (:obj:`~gi.repository.Auth.authenticate` is not called). The :obj:`~gi.repository.Soup.Auth` will be cancelled on dispose if it hans't been authenticated. .. method:: do_authenticate(self, username: str, password: str) -> None :param username: :param password: .. method:: do_can_authenticate(self) -> bool .. method:: do_get_authorization(self, msg: ~gi.repository.Soup.Message) -> str :param msg: .. method:: do_get_protection_space(self, source_uri: ~gi.repository.GLib.Uri) -> list[str] :param source_uri: .. method:: do_is_authenticated(self) -> bool .. method:: do_is_ready(self, msg: ~gi.repository.Soup.Message) -> bool :param msg: .. method:: do_update(self, msg: ~gi.repository.Soup.Message, auth_header: dict[~typing.Any, ~typing.Any]) -> bool :param msg: :param auth_header: .. method:: get_authority() -> str Returns the authority (host:port) that ``auth`` is associated with. .. method:: get_authorization(msg: ~gi.repository.Soup.Message) -> str Generates an appropriate "Authorization" header for ``msg``\. (The session will only call this if :obj:`~gi.repository.Auth.is_authenticated` returned :const:`True`.) :param msg: the :obj:`~gi.repository.Soup.Message` to be authorized .. method:: get_info() -> str Gets an opaque identifier for ``auth``\. The identifier can be used as a hash key or the like. :obj:`~gi.repository.Soup.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). .. method:: get_protection_space(source_uri: ~gi.repository.GLib.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.) :param source_uri: the URI of the request that ``auth`` was generated in response to. .. method:: 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.) .. method:: 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") .. method:: is_authenticated() -> bool Tests if ``auth`` has been given a username and password. .. method:: is_cancelled() -> bool Tests if ``auth`` has been cancelled .. method:: is_for_proxy() -> bool Tests whether or not ``auth`` is associated with a proxy server rather than an "origin" server. .. method:: is_ready(msg: ~gi.repository.Soup.Message) -> bool Tests if ``auth`` is ready to make a request for ``msg`` with. For most auths, this is equivalent to :obj:`~gi.repository.Auth.is_authenticated`\, but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated. :param msg: a :obj:`~gi.repository.Soup.Message` .. method:: update(msg: ~gi.repository.Soup.Message, auth_header: str) -> bool Updates ``auth`` with the information from ``msg`` and ``auth_header``\, possibly un-authenticating it. As with :obj:`~gi.repository.Auth.new`\, this is normally only used by :obj:`~gi.repository.Soup.Session`\. :param msg: the :obj:`~gi.repository.Soup.Message` ``auth`` is being updated for :param auth_header: the WWW-Authenticate/Proxy-Authenticate header Properties ---------- .. rst-class:: interim-class .. class:: Auth :no-index: .. attribute:: props.authority :type: str The type of the None singleton. .. attribute:: props.is_authenticated :type: bool The type of the None singleton. .. attribute:: props.is_cancelled :type: bool The type of the None singleton. .. attribute:: props.is_for_proxy :type: bool The type of the None singleton. .. attribute:: props.realm :type: str The type of the None singleton. .. attribute:: props.scheme_name :type: str The type of the None singleton. Virtual Methods --------------- .. rst-class:: interim-class .. class:: Auth :no-index: .. method:: 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. :param username: the username provided by the user or client :param password: the password provided by the user or client .. method:: do_can_authenticate() -> bool Tests if ``auth`` is able to authenticate by providing credentials to the :obj:`~gi.repository.Auth.authenticate`\. .. method:: do_get_authorization(msg: ~gi.repository.Soup.Message) -> str Generates an appropriate "Authorization" header for ``msg``\. (The session will only call this if :obj:`~gi.repository.Auth.is_authenticated` returned :const:`True`.) :param msg: the :obj:`~gi.repository.Soup.Message` to be authorized .. method:: do_get_protection_space(source_uri: ~gi.repository.GLib.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.) :param source_uri: the URI of the request that ``auth`` was generated in response to. .. method:: do_is_authenticated() -> bool Tests if ``auth`` has been given a username and password. .. method:: do_is_ready(msg: ~gi.repository.Soup.Message) -> bool Tests if ``auth`` is ready to make a request for ``msg`` with. For most auths, this is equivalent to :obj:`~gi.repository.Auth.is_authenticated`\, but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated. :param msg: a :obj:`~gi.repository.Soup.Message` .. method:: do_update(msg: ~gi.repository.Soup.Message, auth_header: dict[~typing.Any, ~typing.Any]) -> bool Updates ``auth`` with the information from ``msg`` and ``auth_header``\, possibly un-authenticating it. As with :obj:`~gi.repository.Auth.new`\, this is normally only used by :obj:`~gi.repository.Soup.Session`\. :param msg: the :obj:`~gi.repository.Soup.Message` ``auth`` is being updated for :param auth_header: the WWW-Authenticate/Proxy-Authenticate header Fields ------ .. rst-class:: interim-class .. class:: Auth :no-index: .. attribute:: parent_instance