MambuPy 1.10.1__tar.gz → 2.0.0__tar.gz

{MambuPy-1.10.1 → mambupy-2.0.0}/MambuPy/__init__.py

@@ -5,18 +5,18 @@
 
     MambuPy.mambuconfig
     MambuPy.mambuutil
-    MambuPy.rest
-    MambuPy.orm
     MambuPy.api
     MambuPy.api.connector
-    MambuPy.rest1to2
+    MambuPy.orm
+    MambuPy.rest
 
 
 Currently, there are two different ways to access Mambu objects:
 
 1) Objects using `Mambu REST API
    <https://developer.mambu.com/customer/en/portal/articles/1162276-rest-apis-overview/>`_
-   , they live at the :any:`MambuPy.rest` package
+   , they live at the :any:`MambuPy.api` package (the old-and-soon-to-be-deprecated,
+   V1-compatible code lives at :any:`MambuPy.rest`
 
 2) An ORM using a `DB backup retrieved from Mambu
    <https://support.mambu.com/docs/mambu-data-dictionary>`_
@@ -35,5 +35,21 @@ TODOS
           to achive TDD when implementing features or correcting bugs.
 """
 
-__version__ = "1.10.1"
+import sys
+from importlib.abc import MetaPathFinder
+from importlib.util import spec_from_file_location
+
+__version__ = "2.0.0"
 """The version of this module."""
+
+
+class CaseInsensitiveFinder(MetaPathFinder):
+    def find_spec(self, fullname, path, target=None):
+        if fullname.lower() == "mambupy":
+            # Get the actual module file location
+            return spec_from_file_location(fullname, __file__)
+        return None
+
+
+# Register the finder
+sys.meta_path.insert(0, CaseInsensitiveFinder())

mambupy-2.0.0/MambuPy/api/__init__.py

@@ -0,0 +1,25 @@
+""" MambuPy's Mambu REST API v2 package.
+
+Objects using `Mambu REST API <https://api.mambu.com/?python>`_
+
+.. autosummary::
+   :toctree: _autosummary
+
+    MambuPy.api.classes
+    MambuPy.api.entities
+    MambuPy.api.interfaces
+    MambuPy.api.vos
+    MambuPy.api.mambustruct
+    MambuPy.api.mambuproduct
+    MambuPy.api.mambuloan
+    MambuPy.api.mambutransaction
+    MambuPy.api.mambugroup
+    MambuPy.api.mambuclient
+    MambuPy.api.mambubranch
+    MambuPy.api.mambucentre
+    MambuPy.api.mambuuser
+    MambuPy.api.mambutask
+    MambuPy.api.mambucustomfield
+
+Entities use the Mixin pattern to acquire functionality.
+"""

mambupy-2.0.0/MambuPy/api/classes.py

@@ -0,0 +1,220 @@
+"""Base and utility Classes for Mambu Objects.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: _autosummary
+"""
+
+import copy
+
+
+class GenericClass:  # pragma: no coverage
+    """Generic class for init of MambuMapObj"""
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+
+class MambuMapObj:
+    """An object with dictionary-like behaviour for key-value data"""
+
+    def __init__(self, cf_class=GenericClass, **kwargs):
+        self._attrs = {}
+        self._cf_class = cf_class
+        if hasattr(self, "_default_tzattrs"):
+            self._tzattrs = copy.deepcopy(self._default_tzattrs)
+        else:
+            self._tzattrs = {}
+        if "tzattrs" in kwargs:
+            self._tzattrs.update(copy.deepcopy(kwargs.pop("tzattrs")))
+        if kwargs:
+            for key, val in kwargs.items():
+                self._attrs[key] = val
+
+    def __getattribute__(self, name):
+        """Object-like get attribute
+
+        When accessing an attribute, tries to find it in the _attrs
+        dictionary, so now MambuMapObj may act not only as a dict-like
+        structure, but as a full object-like too (this is the getter
+        side).
+        """
+        try:
+            # first, try to read 'name' as if it's a property of the object
+            # if it doesn't exists as property, AttributeError raises
+            return object.__getattribute__(self, name)
+        except AttributeError:
+            # try to read the _attrs property
+            _attrs = object.__getattribute__(self, "_attrs")
+            if isinstance(_attrs, list) or name not in _attrs:
+                # magic won't happen when not a dict-like MambuMapObj or
+                # when _attrs has not the 'name' key (this last one means
+                # that if 'name' is not a property of the object too,
+                # AttributeError will raise by default)
+                return object.__getattribute__(self, name)
+            # all else, read the property from the _attrs dict, but with a . syntax
+            # if a cf_class, just return its value
+            if _attrs[name].__class__.__name__ == self._cf_class.__name__:
+                return _attrs[name]["value"]
+            return _attrs[name]
+
+    def __setattr__(self, name, value):
+        """Object-like set attribute
+
+        When setting an attribute, tries to set it in the _attrs
+        dictionary, so now MambuMapObj acts not only as a dict-like
+        structure, but as a full object-like too (this is the setter
+        side).
+        """
+        # if name beginning with _, assign it as a property of the object
+        if name[0] == "_":
+            object.__setattr__(self, name, value)
+        else:
+            try:
+                # _attrs needs to exist to make the magic happen!
+                # ... if not, AttributeError raises
+                _attrs = object.__getattribute__(self, "_attrs")
+                if isinstance(_attrs, list):
+                    # when not treating with a dict-like MambuMapObj...
+                    raise AttributeError
+                try:
+                    # see if 'name' is currently a property of the object
+                    object.__getattribute__(self, name)
+                except AttributeError:
+                    # if not, then assign it as a new key in the dict
+                    if (
+                        name in _attrs
+                        and _attrs[name].__class__.__name__ == self._cf_class.__name__
+                    ):
+                        path = _attrs[name]["path"]
+                        typecf = _attrs[name]["type"]
+                        _attrs[name] = self._cf_class(value, path, typecf)
+                    else:
+                        _attrs[name] = value
+                else:  # pragma: no cover
+                    raise AttributeError
+            except AttributeError:
+                # all else assign it as a property of the object
+                object.__setattr__(self, name, value)
+
+    def __getitem__(self, key):
+        """Dict-like key query"""
+        # if a cf_class, just return its value
+        if self._attrs[key].__class__.__name__ == self._cf_class.__name__:
+            return self._attrs[key]["value"]
+        return self._attrs[key]
+
+    def __setitem__(self, key, value):
+        """Dict-like set"""
+        # if no _attrs attribute, should be automatically created?
+        if (
+            key in self._attrs
+            and self._attrs[key].__class__.__name__ == self._cf_class.__name__
+        ):
+            path = self._attrs[key]["path"]
+            typecf = self._attrs[key]["type"]
+            self._attrs[key] = self._cf_class(value, path, typecf)
+        else:
+            self._attrs[key] = value
+
+    def __delitem__(self, key):
+        """Dict-like del key"""
+        del self._attrs[key]
+
+    def __str__(self):
+        """Mambu object str gives a string representation of the _attrs attribute."""
+        try:
+            return self.__class__.__name__ + " - " + str(self._attrs)
+        except AttributeError:
+            return repr(self)
+
+    def __repr__(self):
+        """Mambu object repr tells the class name and the usual 'id' for it.
+
+        If an iterable, it instead gives its length.
+        """
+        try:
+            return self.__class__.__name__ + " - id: %s" % self._attrs["id"]
+        except KeyError:
+            return self.__class__.__name__ + " - " + str(self._attrs)
+        except AttributeError:
+            return (
+                self.__class__.__name__
+                + " - id: '%s' (not synced with Mambu)" % self.entid
+            )
+        except TypeError:
+            return self.__class__.__name__ + " - len: %s" % len(self._attrs)
+
+    def __eq__(self, other):
+        """Very basic way to compare to Mambu objects.
+
+                Only looking at their EncodedKey field (its primary key on the
+                Mambu DB).
+
+        .. todo:: a lot of improvements may be done here.
+        """
+        if isinstance(other, MambuMapObj):
+            try:
+                if "encodedKey" not in other._attrs or "encodedKey" not in self._attrs:
+                    return NotImplemented
+            except AttributeError:
+                return NotImplemented
+            return other["encodedKey"] == self["encodedKey"]
+
+    def __hash__(self):
+        """Hash of the object"""
+        try:
+            return hash(self.encodedKey)
+        except AttributeError:
+            try:
+                return hash(self.__class__.__name__ + self.id)
+            except Exception:
+                return hash(self.__repr__())
+
+    def __len__(self):
+        """Length of the _attrs attribute.
+
+        If dict-like (not iterable), it's the number of keys holded on the _attrs dictionary.
+        If list-like (iterable), it's the number of elements of the _attrs list.
+        """
+        return len(self._attrs)
+
+    def __contains__(self, item):
+        """Dict-like and List-like behaviour"""
+        return item in self._attrs
+
+    def get(self, key, default=None):
+        """Dict-like behaviour"""
+        if isinstance(self._attrs, dict):
+            return self._attrs.get(key, default)
+        raise NotImplementedError  # if _attrs is not a dict
+
+    def keys(self):
+        """Dict-like behaviour"""
+        try:
+            return self._attrs.keys()
+        except AttributeError:
+            raise NotImplementedError
+
+    def items(self):
+        """Dict-like behaviour"""
+        try:
+            return self._attrs.items()
+        except AttributeError:
+            raise NotImplementedError
+
+    def values(self):
+        """Dict-like behaviour"""
+        try:
+            return self._attrs.values()
+        except AttributeError:
+            raise NotImplementedError
+
+    def has_key(self, key):
+        """Dict-like behaviour"""
+        try:
+            if isinstance(self._attrs, dict):
+                return key in self._attrs
+            raise AttributeError  # if _attrs is not a dict
+        except AttributeError:  # if _attrs doesnt exist
+            raise NotImplementedError

mambupy-2.0.0/MambuPy/api/connector/__init__.py

@@ -0,0 +1,8 @@
+""" MambuPy's Mambu REST API v2 connectors package.
+
+.. autosummary::
+   :toctree: _autosummary
+
+    MambuPy.api.connector.mambuconnector
+    MambuPy.api.connector.rest
+"""

mambupy-2.0.0/MambuPy/api/connector/mambuconnector.py

@@ -0,0 +1,297 @@
+"""Connectors to Mambu.
+
+Currently supports REST.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: _autosummary
+"""
+
+from abc import ABC, abstractmethod
+
+
+class MambuConnector(ABC):
+    """Interface for Connectors"""
+
+
+class MambuConnectorReader(ABC):
+    """Interface for Readers.
+
+    A Reader supports the followint operations:
+
+    - get (gets a single entity)
+    - get_all (gets several entities, filtering allowed)
+    - search (gets several entities, advanced filtering)
+    - get_documents_metadata (gets the metadata of documents attached to some
+                              entity)
+    """
+
+    @abstractmethod
+    def mambu_get(self, entid, prefix, detailsLevel="BASIC"):
+        """get, a single entity, identified by its entid.
+
+        Args:
+          entid (str): ID for the entity
+          prefix (str): entity's URL prefix
+          detailsLevel (str BASIC/FULL): ask for extra details or not
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_get_all(
+        self,
+        prefix,
+        filters=None,
+        offset=None,
+        limit=None,
+        paginationDetails="OFF",
+        detailsLevel="BASIC",
+        sortBy=None,
+        **kwargs
+    ):
+        """get_all, several entities, filtering allowed
+
+        Args:
+          prefix (str): entity's URL prefix
+          filters (dict): key-value filters (depends on each entity)
+          offset (int): pagination, index to start searching
+          limit (int): pagination, number of elements to retrieve
+          paginationDetails (str ON/OFF): ask for details on pagination
+          detailsLevel (str BASIC/FULL): ask for extra details or not
+          sortBy (str): ``field1:ASC,field2:DESC``, sorting criteria for
+                        results
+          kwargs (dict): extra parameters that a specific entity may receive in
+                         its get_all method
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_search(
+        self,
+        prefix,
+        filterCriteria=None,
+        sortingCriteria=None,
+        offset=None,
+        limit=None,
+        paginationDetails="OFF",
+        detailsLevel="BASIC",
+    ):
+        """search, several entities, filtering criteria allowed
+
+        Args:
+          filterCriteria (list of dicts): fields according to
+                              LoanAccountFilterCriteria schema
+          sortingCriteria (dict): fields according to
+                            LoanAccountSortingCriteria
+          offset (int): pagination, index to start searching
+          limit (int): pagination, number of elements to retrieve
+          paginationDetails (str ON/OFF): ask for details on pagination
+          detailsLevel (str BASIC/FULL): ask for extra details or not
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_get_documents_metadata(
+        self,
+        entid,
+        owner_type,
+        offset=None,
+        limit=None,
+        paginationDetails="OFF",
+    ):
+        """Gets metadata for all the documents attached to an entity
+
+        Args:
+          entid (str): the id or encoded key of the entity owning the document
+          owner_type (str): the type of the owner of the document
+          offset (int): pagination, index to start searching
+          limit (int): pagination, number of elements to retrieve
+          paginationDetails (str ON/OFF): ask for details on pagination
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_loanaccount_getSchedule(self, loanid):
+        """Retrieves the installments schedule
+
+        Args:
+          loanid (str): the id or encoded key of the loan account
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_get_customfield(self, customfieldid):
+        """Retrieves a Custom Field.
+
+        Args:
+          customfieldid (str): the id or encoded key of the custom field
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_get_comments(self, owner_id, owner_type):
+        """Retrieves the comments of entity with owner_id.
+
+        Args:
+          owner_id (str): the id or encoded key of the owner
+          owner_type (str): the type of the entity owning the comments
+        """
+        raise NotImplementedError
+
+
+class MambuConnectorWriter(ABC):
+    """Interface for Writers.
+
+    A Reader supports the followint operations:
+
+    - update (updates an entity)
+    - create (creates an entity)
+    - patch (patches an entity)
+    - upload_document (gets a single entity)
+    - delete_document (gets several entities, filtering allowed)
+    """
+
+    @abstractmethod
+    def mambu_update(self, entid, prefix, attrs):
+        """updates a mambu entity
+
+        Args:
+          entid (str): the id or encoded key of the entity owning the document
+          prefix (str): entity's URL prefix
+          attrs (dict): entity to be updated, complying with Mambu's schemas
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_create(self, prefix, attrs):
+        """creates a mambu entity
+
+        Args:
+          prefix (str): entity's URL prefix
+          attrs (dict): entity to be created, complying with Mambu's schemas
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_patch(self, entid, prefix, fields):
+        """patches certain parts of a mambu entity"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_delete(self, entid, prefix):
+        """deletes a mambu entity"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_upload_document(self, owner_type, entid, filename, name, notes):
+        """uploads an attachment to this entity
+
+        Args:
+          owner_type (str): the type of the owner of the document
+          entid (str): the id or encoded key of the entity owning the document
+          filename (str): path and filename of file to upload as attachment
+          name (str): name to assign to the attached file in Mambu
+          notes (str): notes to associate to the attached file in Mambu
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_delete_document(self, documentId):
+        """deletes an attachment by its documentId
+
+        Args:
+          documentId (str): the id or encodedkey of the document to be deleted
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_change_state(self, entid, prefix, action, notes):
+        """change state of mambu entity
+
+        Args:
+          entid (str): the id or encoded key of the entity owning the document
+          prefix (str): entity's URL prefix
+          action (str): specify the action state
+          notes (str): notes to associate to the change of status
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_comment(self, owner_id, owner_type, text):
+        """Comments an entity with owner_id.
+
+        Args:
+          owner_id (str): the id or encoded key of the owner
+          owner_type (str): the type of the entity owning the comments
+          text (str): the text of the comment
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_make_disbursement(
+        self, loan_id, firstRepaymentDate, notes, valueDate, allowed_fields, **kwargs
+    ):
+        """Make a disbursement transacton on a loan account.
+
+        Args:
+          loan_id (str): loan account id to disburse
+          firstRepaymentDate (str): first repayment date in ISO format
+          notes (str): notes for the disbursement transaction
+          valueDate (str): entry date for the disbursement transaction
+          allowed_fields (list): extra fields allowed for the transaction
+          kwargs (dict): key-values of extra fields for the transaction
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_make_repayment(
+        self, loan_id, amount, notes, valueDate, allowed_fields, **kwargs
+    ):
+        """Make a repayment transaction on a loan account.
+
+        Args:
+          loan_id (str): loan account id to make a repayment
+          amount (float): the amount of the repayment
+          notes (str): notes for the repayment transaction
+          valueDate (str): entry date for the repayment transaction
+          allowed_fields (list): extra fields allowed for the transaction
+          kwargs (dict): key-values of extra fields for the transaction
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_make_fee(
+        self, loan_id, amount, installmentNumber, notes, valueDate, allowed_fields, **kwargs
+    ):
+        """Make a fee transaction on a loan account.
+
+        Args:
+          loan_id (str): loan account id to apply a fee
+          amount (float): the amount of the fee
+          installmentNumber (int): the installment number to apply the fee
+          notes (str): notes for the fee transaction
+          valueDate (str): entry date for the fee transaction
+          allowed_fields (list): extra fields allowed for the transaction
+          kwargs (dict): key-values of extra fields for the transaction
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_loanaccount_writeoff(self, loanid, notes):
+        """Writesoff a loan account
+
+        Args:
+          loanid (str): the id or encoded key of the loan account
+          notes (str): notes to associate to the writeoff operation in Mambu
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def mambu_loantransaction_adjust(self, transactionid, notes):
+        """Adjust a loan transaction
+
+        Args:
+          transactionid (str): the id or encoded key of the loan transaction
+          notes (str): notes to associate to the transaction adjustment in Mambu
+        """
+        raise NotImplementedError