:py:mod:`slidge.util.db`
========================

.. py:module:: slidge.util.db

.. autoapi-nested-parse::

   This module covers a backend for storing user data persistently and managing a
   pseudo-roster for the gateway component.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   slidge.util.db.EncryptedShelf
   slidge.util.db.GatewayUser
   slidge.util.db.UserStore




.. py:class:: EncryptedShelf(filename, key, flag='c', protocol=None, writeback=False)




   Shelf implementation using the "dbm" generic dbm interface.

   This is initialized with the filename for the dbm database.
   See the module's __doc__ string for an overview of the interface.

   .. py:method:: get(key, default=None)

      D.get(k[,d]) -> D[k] if k in D, else d.  d defaults to None.


   .. py:method:: pop(key, default=__marker)

      D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
      If key is not found, d is returned if given, otherwise KeyError is raised.


   .. py:method:: popitem()

      D.popitem() -> (k, v), remove and return some (key, value) pair
      as a 2-tuple; but raise KeyError if D is empty.


   .. py:method:: clear()

      D.clear() -> None.  Remove all items from D.


   .. py:method:: update(other=(), /, **kwds)

      D.update([E, ]**F) -> None.  Update D from mapping/iterable E and F.
      If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
      If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
      In either case, this is followed by: for k, v in F.items(): D[k] = v


   .. py:method:: setdefault(key, default=None)

      D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D


   .. py:method:: keys()

      D.keys() -> a set-like object providing a view on D's keys


   .. py:method:: items()

      D.items() -> a set-like object providing a view on D's items


   .. py:method:: values()

      D.values() -> an object providing a view on D's values



.. py:class:: GatewayUser


   A gateway user

   .. py:property:: jid
      :type: slixmpp.JID

      The user's (bare) JID

      :return:


   .. py:attribute:: bare_jid
      :type: str

      Bare JID of the user


   .. py:attribute:: registration_form
      :type: dict[str, Optional[str]]

      Content of the registration form, as a dict



.. py:class:: UserStore


   Basic user store implementation using shelve from the python standard library

   Set_file must be called before it is usable

   .. py:method:: set_file(filename, secret_key = None)

      Set the file to use to store user data

      :param filename: Path to the shelf file
      :param secret_key: Secret key to store files encrypted on disk


   .. py:method:: get_all()

      Get all users in the store

      :return: An iterable of GatewayUsers


   .. py:method:: add(jid, registration_form)

      Add a user to the store.

      NB: there is no reason to call this manually, as this should be covered
      by slixmpp XEP-0077 and XEP-0100 plugins

      :param jid: JID of the gateway user
      :param registration_form: Content of the registration form (:xep:`0077`)


   .. py:method:: get(_gateway_jid, _node, ifrom, iq)

      Get a user from the store

      NB: there is no reason to call this, it is used by SliXMPP internal API

      :param _gateway_jid:
      :param _node:
      :param ifrom:
      :param iq:
      :return:


   .. py:method:: remove(_gateway_jid, _node, ifrom, _iq)

      Remove a user from the store

      NB: there is no reason to call this, it is used by SliXMPP internal API


   .. py:method:: remove_by_jid(jid)

      Remove a user from the store, by JID


   .. py:method:: get_by_jid(jid)

      Convenience function to get a user from their JID.

      :param jid: JID of the gateway user
      :return:


   .. py:method:: get_by_stanza(s)

      Convenience function to get a user from a stanza they sent.

      :param s: A stanza sent by the gateway user
      :return:



