:right-sidebar: True

HSTSEnforcer
===================================================================

.. currentmodule:: gi.repository.Soup





.. class:: HSTSEnforcer(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`


Subclasses: :class:`~gi.repository.Soup.HSTSEnforcerDB`


Implemented Interfaces: :class:`~gi.repository.Soup.SessionFeature`



Automatic HTTP Strict Transport Security enforcing for :obj:`~gi.repository.Soup.Session`\.

A :obj:`~gi.repository.Soup.HSTSEnforcer` stores HSTS policies and enforces them when
required. :obj:`~gi.repository.Soup.HSTSEnforcer` implements :obj:`~gi.repository.Soup.SessionFeature`\, so you
can add an HSTS enforcer to a session with
:obj:`~gi.repository.Session.add_feature` or :obj:`~gi.repository.Session.add_feature_by_type`\.

:obj:`~gi.repository.Soup.HSTSEnforcer` keeps track of all the HTTPS destinations that,
when connected to, return the Strict-Transport-Security header with
valid values. :obj:`~gi.repository.Soup.HSTSEnforcer` will forget those destinations
upon expiry or when the server requests it.

When the :obj:`~gi.repository.Soup.Session` the :obj:`~gi.repository.Soup.HSTSEnforcer` is attached to queues or
restarts a message, the :obj:`~gi.repository.Soup.HSTSEnforcer` will rewrite the URI to HTTPS if
the destination is a known HSTS host and is contacted over an insecure
transport protocol (HTTP). Users of :obj:`~gi.repository.Soup.HSTSEnforcer` are advised to listen
to changes in the :obj:`~gi.repository.Soup.Message.props.uri` property in order to be aware of
changes in the message URI.

Note that :obj:`~gi.repository.Soup.HSTSEnforcer` does not support any form of long-term
HSTS policy persistence. See :obj:`~gi.repository.Soup.HSTSEnforcerDB` for a persistent
enforcer.


Constructors
------------

.. rst-class:: interim-class

.. class:: HSTSEnforcer
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Soup.HSTSEnforcer

      Creates a new :obj:`~gi.repository.Soup.HSTSEnforcer`\.

      The base :obj:`~gi.repository.Soup.HSTSEnforcer` class does not support persistent storage of HSTS
      policies, see :obj:`~gi.repository.Soup.HSTSEnforcerDB` for that.













Methods
-------

.. rst-class:: interim-class

.. class:: HSTSEnforcer
   :no-index:


   .. method:: do_changed(self, old_policy: ~gi.repository.Soup.HSTSPolicy, new_policy: ~gi.repository.Soup.HSTSPolicy) -> None

      






      :param old_policy: 

      :param new_policy: 




   .. method:: do_has_valid_policy(self, domain: str) -> bool

      






      :param domain: 




   .. method:: do_is_persistent(self) -> bool

      









   .. method:: get_domains(session_policies: bool) -> list[str]

      Gets a list of domains for which there are policies in ``enforcer``\.






      :param session_policies: whether to include session policies




   .. method:: get_policies(session_policies: bool) -> list[~gi.repository.Soup.HSTSPolicy]

      Gets a list with the policies in ``enforcer``\.






      :param session_policies: whether to include session policies




   .. method:: has_valid_policy(domain: str) -> bool

      Gets whether ``hsts_enforcer`` has a currently valid policy for ``domain``\.






      :param domain: a domain.




   .. method:: is_persistent() -> bool

      Gets whether ``hsts_enforcer`` stores policies persistenly.









   .. method:: set_policy(policy: ~gi.repository.Soup.HSTSPolicy) -> None

      Sets ``policy`` to ``hsts_enforcer``\.

      If ``policy`` is expired, any existing HSTS policy for its host will be removed
      instead. If a policy existed for this host, it will be replaced. Otherwise,
      the new policy will be inserted. If the policy is a session policy, that is,
      one created with :obj:`~gi.repository.HSTSPolicy.new_session_policy`\, the policy will not
      expire and will be enforced during the lifetime of ``hsts_enforcer``\'s
      :obj:`~gi.repository.Soup.Session`\.






      :param policy: the policy of the HSTS host




   .. method:: set_session_policy(domain: str, include_subdomains: bool) -> None

      Sets a session policy for ``domain``\.

      A session policy is a policy that is permanent to the lifetime of
      ``hsts_enforcer``\'s :obj:`~gi.repository.Soup.Session` and doesn't expire.






      :param domain: policy domain or hostname

      :param include_subdomains: :const:`True` if the policy applies on sub domains










Signals
-------

.. rst-class:: interim-class

.. class:: HSTSEnforcer.signals
   :no-index:
   

   .. method:: changed(old_policy: ~gi.repository.Soup.HSTSPolicy, new_policy: ~gi.repository.Soup.HSTSPolicy) -> None

      The type of the None singleton.







      :param old_policy: the old :obj:`~gi.repository.Soup.HSTSPolicy` value

      :param new_policy: the new :obj:`~gi.repository.Soup.HSTSPolicy` value








Virtual Methods
---------------

.. rst-class:: interim-class

.. class:: HSTSEnforcer
   :no-index:
   

   .. method:: do_changed(old_policy: ~gi.repository.Soup.HSTSPolicy, new_policy: ~gi.repository.Soup.HSTSPolicy) -> None

      The type of the None singleton.







      :param old_policy: 

      :param new_policy: 




   .. method:: do_has_valid_policy(domain: str) -> bool

      Gets whether ``hsts_enforcer`` has a currently valid policy for ``domain``\.






      :param domain: a domain.




   .. method:: do_is_persistent() -> bool

      Gets whether ``hsts_enforcer`` stores policies persistenly.













Fields
------

.. rst-class:: interim-class

.. class:: HSTSEnforcer
   :no-index:
   

   .. attribute:: parent_instance