Source code for woob.capabilities.account

# Copyright(C) 2010-2011 Romain Bignon
#
# This file is part of woob.
#
# woob is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# woob is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with woob. If not, see <http://www.gnu.org/licenses/>.

from __future__ import annotations

from .base import (
    BaseObject,
    Capability,
    Field,
    IntField,
    NotAvailableType,
    NotLoaded,
    NotLoadedType,
    StringField,
    UserError,
)


__all__ = ["AccountRegisterError", "Account", "StatusField", "CapAccount", "CapCredentialsCheck"]


class AccountRegisterError(UserError):
    """
    Raised when there is an error during registration.
    """


class Account(BaseObject):
    """
    Describe an account and its properties.
    """

    login = StringField("Login")
    password = StringField("Password")
    properties = Field("List of key/value properties", dict)

    def __init__(self, id: str = "", url: str | NotLoadedType | NotAvailableType = NotLoaded):
        super().__init__(id, url)


class StatusField(BaseObject):
    """
    Field of an account staeobjectus.
    """

    FIELD_TEXT = 0x001  # the value is a long text
    FIELD_HTML = 0x002  # the value is HTML formated

    key = StringField("Key")
    label = StringField("Label")
    value = StringField("Value")
    flags = IntField("Flags")

    def __init__(
        self, key: str, label: str, value: str, flags: int = 0, url: str | NotLoadedType | NotAvailableType = NotLoaded
    ):
        super().__init__(key, url)
        self.__setattr__("key", key)
        self.__setattr__("label", label)
        self.__setattr__("value", value)
        self.__setattr__("flags", flags)


class CapAccount(Capability):
    """
    Capability for websites when you can create and manage accounts.

    :var ACCOUNT_REGISTER_PROPERTIES: This class constant may be a list of
                                      :class:`woob.tools.value.Value` objects.
                                      If the value remains None, woob considers
                                      that :func:`register_account` isn't supported.
    """

    ACCOUNT_REGISTER_PROPERTIES = None

    @staticmethod
    def register_account(account: Account):
        """
        Register an account on website

        This is a static method, it would be called even if the backend is
        instancied.

        :param account: describe the account to create
        :type account: :class:`Account`
        :raises: :class:`AccountRegisterError`
        """
        raise NotImplementedError()

    def confirm_account(self, mail: str):
        """
        From an email go to the confirm link.
        """
        raise NotImplementedError()

    def get_account(self) -> Account:
        """
        Get the current account.
        """
        raise NotImplementedError()

    def update_account(self, account: Account):
        """
        Update the current account.
        """
        raise NotImplementedError()

    def get_account_status(self) -> list[StatusField]:
        """
        Get status of the current account.

        :returns: a list of fields
        :rtype: list[StatusField]
        """
        raise NotImplementedError()


class CapCredentialsCheck(Capability):
    def check_credentials(self) -> bool:
        """
        Its purpose is to check that the credentials (in the config) are valid
        for the module's website, API, whatever requires credentials to be
        accessed.
        """
        raise NotImplementedError()