creditpulse 0.0.1__tar.gz

creditpulse-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 svelezsaman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

creditpulse-0.0.1/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: creditpulse
+Version: 0.0.1
+Summary: A pyhton library for financial analysis with external databases
+Author-email: Santiago Velez <s.velez@saman-wm.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click==8.1.8
+Requires-Dist: requests==2.32.4
+Requires-Dist: pydantic==2.8.0
+Requires-Dist: pylint==3.3.7
+Dynamic: license-file

creditpulse-0.0.1/creditpulse/__init__.py

@@ -0,0 +1,25 @@
+"""A clean Python project template with public API.
+
+This package provides a simple, clean interface for users to import and use.
+
+Example:
+    >>> from CreditPulse import Check
+    >>> client = Check()
+    >>> result_juridica = client.persona_juridica()
+    >>> result_natural = client.persona_natural()
+"""
+
+# Import version
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+# Package metadata
+__author__ = "Santiago Velez"
+__email__ = "s.velez@saman-wm.com"
+__description__ = "A python library for financial analysis"
+
+from .check import Check
+
+__all__ = ["Check"]

creditpulse-0.0.1/creditpulse/bases_externas/database.py

@@ -0,0 +1,39 @@
+"""
+    Clase abstracta para definir una base de datos
+"""
+
+from creditpulse.bases_externas.schema import PersonType, CountryCode, GeneralDatabase
+from creditpulse.requests.request_manager import RequestActionManager
+from abc import ABC, abstractmethod
+
+
+class Database(RequestActionManager, ABC):
+
+    @abstractmethod
+    def create_check(self, identificacion: str,
+                     person_type: PersonType,
+                     autorizacion_datos: bool = False,
+                     pais: CountryCode = CountryCode.COLOMBIA
+                     ) -> GeneralDatabase:
+        """
+        Implementacion de
+        :param identificacion:
+        :param person_type:
+        :param autorizacion_datos:
+        :param pais:
+        :return:
+        """
+
+    @abstractmethod
+    def get_name(self) -> str:
+        """
+        Da el nombre de la actual base de datos
+        :return:
+        """
+
+    @abstractmethod
+    def to_general(self) -> GeneralDatabase:
+        """
+        Traduce base de datos a general
+        :return:
+        """

creditpulse-0.0.1/creditpulse/bases_externas/external.py

@@ -0,0 +1,43 @@
+"""
+
+External Database Schema standarization
+"""
+
+from enum import Enum
+
+
+from creditpulse.bases_externas.database import Database
+from creditpulse.bases_externas.truora import Truora
+from creditpulse.bases_externas.schema import CountryCode, PersonType
+
+
+class BasesDeDatos(str, Enum):
+    """Supported country codes for checks"""
+    TRUORA = "tr"  # International Lists
+
+
+class ExternalDatabases:
+
+    def __init__(self, *bases: BasesDeDatos):
+
+        if len(bases) == 0:
+            raise Exception('Debe seleccionar al menos una base de datos')
+
+        self.data_bases: [Database] = []
+
+        for base in bases:
+            if base == BasesDeDatos.TRUORA:
+                self.data_bases.append(Truora())
+
+    def obtain_data(self, identificacion: str, natural: bool = True):
+        response = {}
+
+        for base in self.data_bases:
+            response[base.get_name()] = base.create_check(
+                identificacion=identificacion,
+                person_type=PersonType.PERSONA if natural else PersonType.COMPANIA,
+                pais=CountryCode.COLOMBIA,
+                autorizacion_datos=True
+            )
+
+        return response

creditpulse-0.0.1/creditpulse/bases_externas/schema.py

@@ -0,0 +1,80 @@
+"""
+Definicion de tipos de datos para base de datos externas
+"""
+
+from datetime import datetime
+from typing import Literal
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class CountryCode(str, Enum):
+    """Supported country codes for checks"""
+    ALL = "ALL"  # International Lists
+    BRAZIL = "BR"  # Brazil
+    COLOMBIA = "CO"  # Colombia
+    CHILE = "CL"  # Chile
+    COSTA_RICA = "CR"  # Costa Rica
+    MEXICO = "MX"  # Mexico
+    PERU = "PE"  # Peru
+
+
+class PersonType(str, Enum):
+    """Supported country codes for checks"""
+    PERSONA = "person"  # Used to perform a background check on a person.
+    VEHICULO = "vehicle"  # Used to perform a background check on a driver and their vehicle
+    COMPANIA = "company"  # Used to perform a background check on a company
+
+
+class CheckStatus(str, Enum):
+    """Status values for checks"""
+    NOT_STARTED = "not_started"  # The check is enqueued and the data collection has not started yet
+    IN_PROGRESS = "in_progress"  # Data is being collected but some data sources may have finished already
+    DELAYED = "delayed"  # One or more data sources are taking a long time to query the data. Most data sources will have already finished
+    COMPLETED = "completed"  # The check finished and 70% or more of the data sources did not end in error status
+    ERROR = "error"  # The check finished and more than 30% of the data sources ended in error status
+
+
+class TruoraCheck(BaseModel):
+    """
+    Definicion para Check de truora
+    """
+    check_id: str = Field(..., description="Unique identifier for the check")
+    country: CountryCode = Field(
+        ...,
+        description="""
+            Country code - 
+            ALL for International Lists, 
+            BR for Brazil, 
+            CO for Colombia, 
+            CL for Chile, 
+            CR for Costa Rica, 
+            MX for Mexico, 
+            PE for Peru
+        """
+    )
+    creation_date: datetime = Field(..., description="When the check was created")
+    name_score: int = Field(..., description="Score for name matching")
+    id_score: int = Field(..., description="Score for ID matching")
+    score: int = Field(..., description="Overall check score")
+    status: CheckStatus = Field(..., description="Current status of the check")
+    update_date: datetime = Field(..., description="When the check was last updated")
+    billing_hub: str = Field(..., description="Billing hub identifier")
+    national_id: str = Field(..., description="National ID number being checked")
+    type: Literal["person"] = Field(..., description="Type of check (person, business, etc.)")
+
+
+class TruoraCheckData(BaseModel):
+    """
+    Definicion para la respuesta de truora
+    """
+    check: TruoraCheck = Field(..., description="Check details")
+    details: str = Field(..., description="API endpoint for detailed check information")
+    self: str = Field(..., description="API endpoint for this check resource")
+
+
+class GeneralDatabase(BaseModel):
+    score: int = Field(..., description="Overall check score")
+    creation_date: datetime = Field(..., description="When the check was created")
+    national_id: str = Field(..., description="National ID number being checked")

creditpulse-0.0.1/creditpulse/bases_externas/truora.py

@@ -0,0 +1,194 @@
+"""
+    Request manager ara base de datos externa truora
+"""
+import json
+import os
+import logging
+from typing import Optional
+
+import requests
+from creditpulse.requests.request_manager import RequestManager
+from creditpulse.bases_externas.schema import TruoraCheckData, CountryCode, PersonType, CheckStatus, GeneralDatabase
+from creditpulse.common.error_messages import (
+    AutorizacionDatosPersonales,
+    TruoraApiKeyRequired,
+    TruoraGeneralError
+)
+
+from creditpulse.bases_externas.database import Database
+
+# https://www.postman.com/truora-api-docs/truora-api-docs/collection/iwmyaus/truora-collection
+TRUORA_API_VERSIONS = '/v1'
+TRUORA_BASE_URL = 'https://api.checks.truora.com' + TRUORA_API_VERSIONS
+CHECK_URL = TRUORA_BASE_URL + '/checks'
+CHECK_URL_DETAILS = TRUORA_BASE_URL + '/checks/{}/details'
+CHECK_SETTINGS_URL = ' https://api.checks.truora.com/v1/settings'
+
+settings_data = {
+    'names_matching_type': 'exact',
+    'retries': True,
+    'max_duration': '3m'
+}
+
+
+class Truora(Database):
+    """
+
+    Clase principal para consultar base de datos externa truora
+    """
+
+    def get_name(self) -> str:
+        return 'truora'
+
+    def _get_check(self, check_id: str):
+        return self.session.post(CHECK_URL + "/" + check_id)
+
+    def on_execute(self) -> requests.Response:
+        return self._get_check(self.tcheck.check.check_id)
+
+    def success_callback(self, response: requests.Response) -> None:
+        self.logger.info("Consulta a Base De datos ha sido finalizada")
+        response_json = response.json()
+        self.tcheck = TruoraCheckData(**response_json)
+        self.status = self.tcheck.check.status
+
+    def error_callback(self, response: requests.Response) -> None:
+        response_json = response.json()
+        inter_check: TruoraCheckData = TruoraCheckData(**response_json)
+
+        if inter_check.check.status == CheckStatus.DELAYED:
+            self.logger.warning("Consulta base de datos ha sido delayed")
+
+        self.status = inter_check.check.status
+
+    def is_request_successful(self, response: requests.Response) -> bool:
+        """
+
+        :param response:
+        :return:
+        """
+        if response.status_code in [200, 203]:
+            response_json = response.json()
+            try:
+                t_checker: TruoraCheckData = TruoraCheckData(**response_json)
+                return t_checker.check.status == CheckStatus.COMPLETED
+            except (KeyError, TypeError):
+                return False
+        return False
+
+    def __init__(self):
+        """
+
+        """
+
+        self.api_key = os.environ.get('TRUORA_API_TOKEN')
+
+        if self.api_key is None:
+            raise TruoraApiKeyRequired()
+
+        self.session = requests.session()
+
+        self.session.headers.update({
+            "Truora-API-Key": self.api_key,
+            'Accept': 'application/json'
+        })
+
+        self.request_manager = RequestManager(
+            manager=self,
+            max_retries=10
+        )
+
+        self.tcheck: Optional[TruoraCheckData] = None
+
+        self.logger = logging.getLogger(__name__)
+
+        self.status: CheckStatus = CheckStatus.NOT_STARTED
+
+    def create_check(self,
+                     identificacion: str,
+                     person_type: PersonType,
+                     autorizacion_datos: bool = False,
+                     pais: CountryCode = CountryCode.COLOMBIA
+                     ):
+        """
+        Funcion principal para consulatr base de datos externa tuora
+
+        :param identificacion:
+        :param person_type:
+        :param autorizacion_datos:
+        :param pais:
+        :return:
+        """
+        if not autorizacion_datos:
+            raise AutorizacionDatosPersonales()
+
+        settings_response = self.session.post(CHECK_SETTINGS_URL, data=settings_data)
+        response_json = settings_response.json()
+
+        if settings_response.status_code not in [200, 201, 202, 203]:
+            self.logger.error(f"Error al crear consulta base de datos externa: {response_json['message']}")
+            raise TruoraGeneralError(f"Error al crear consulta base de datos externa: {response_json['message']}")
+
+        form_data = {
+            'national_id': identificacion,
+            'country': pais,
+            'type': person_type,
+            'user_authorized': autorizacion_datos,
+            'force_creation': True
+        }
+
+        response = self.session.post(CHECK_URL, data=form_data)
+        response_json = response.json()
+
+        if response.status_code not in [200, 201, 202, 203]:
+            self.logger.error(f"Error al crear consulta base de datos externa: {response_json['message']}")
+            raise TruoraGeneralError(f"Error al crear consulta base de datos externa: {response_json['message']}")
+
+        self.tcheck = TruoraCheckData(**response_json)
+
+        if self.tcheck is None:
+            raise TruoraGeneralError('Check de truora no fue creado')
+
+        self.request_manager.start()
+
+        open('file.txt', "w+").write(json.dumps(self.get_check_details(self.tcheck.check.check_id)))
+
+        return self.to_general()
+
+    def get_check(self, check_id: str) -> TruoraCheckData:
+        """
+
+        :param check_id:
+        :return:
+        """
+        response = self._get_check(check_id=check_id)
+        if response.status_code not in range(200, 203):
+            self.logger.error(response.text)
+            raise TruoraGeneralError(response.text)
+
+        response_json = response.json()
+        return TruoraCheckData(**response_json)
+
+    def get_check_details(self, check_id: str):
+        """
+
+        :param check_id:
+        :return:
+        """
+        response = self.session.post(CHECK_URL_DETAILS.format(check_id))
+        if response.status_code not in range(200, 203):
+            self.logger.error(response.text)
+            raise TruoraGeneralError(response.text)
+
+        return response.json()
+
+    def to_general(self) -> GeneralDatabase:
+        """
+        Traduce truora a general
+        :return:
+        """
+        return GeneralDatabase(
+            score=self.tcheck.check.score,
+            creation_date=self.tcheck.check.creation_date,
+            national_id=self.tcheck.check.national_id
+        )

creditpulse-0.0.1/creditpulse/check.py

@@ -0,0 +1,27 @@
+"""
+Clase pincipal para analysis de creditos financieros
+
+"""
+import logging
+
+from creditpulse.bases_externas.external import ExternalDatabases, BasesDeDatos
+from creditpulse.bases_externas.truora import Truora
+
+
+class Check:
+    """
+        Clase que provee interfaz para analysis the personas
+    """
+
+    def __init__(self):
+        # Module logger
+        self.logger = logging.getLogger(__name__)
+
+    def get_data(self, identificacion: str, natural: bool = True):
+        """
+
+        :return: Analysis financiero de la persona natural o juridica
+        """
+        external = ExternalDatabases(BasesDeDatos.TRUORA)
+
+        return external.obtain_data(identificacion=identificacion, natural=natural)

creditpulse-0.0.1/creditpulse/cli/commands.py

@@ -0,0 +1,11 @@
+"""Command line interface."""
+
+import click
+
+
+@click.command()
+@click.option("--name", "-n", help="Name to greet", type=str, default=None, )
+@click.version_option()
+def main(name: str) -> None:
+    """My Project CLI."""
+    print(name)

creditpulse-0.0.1/creditpulse/common/error_messages.py

@@ -0,0 +1,39 @@
+"""
+Manejo de error generales
+"""
+
+AUTORIZACION_BASE_DE_DATOS = """
+    Es necesario obtener autorizacion para el el uso y lectura de base de datos
+"""
+
+TRUORA_API_KEY = """
+    Debe obtener un API key de truora para consulta bases de datos externas, mas info en: https://dev.truora.com/checks/account/
+"""
+
+
+class AutorizacionDatosPersonales(Exception):
+    """
+    Error por falta de autorizacion para uso de datos personales
+    """
+
+    def __init__(self):
+        super().__init__(AUTORIZACION_BASE_DE_DATOS)
+
+
+class TruoraApiKeyRequired(Exception):
+    """
+    Error por falta de api key de truora
+    """
+
+    def __init__(self):
+        super().__init__(TRUORA_API_KEY)
+
+
+class TruoraGeneralError(Exception):
+    """
+    Error general de truora que permite dar mensaje de error como paramtero
+    """
+
+    def __init__(self, msg: str):
+        super().__init__(msg)
+

creditpulse-0.0.1/creditpulse/requests/request_manager.py

@@ -0,0 +1,114 @@
+"""
+Clase para hacer exponential back of de algun callback
+"""
+import time
+from abc import ABC, abstractmethod
+import requests
+
+
+
+
+class RequestActionManager(ABC):
+    """Abstract base class for handling HTTP requests with decision logic"""
+
+    @abstractmethod
+    def on_execute(self) -> requests.Response:
+        """Execute the HTTP request and return the response"""
+
+    @abstractmethod
+    def success_callback(self, response: requests.Response) -> None:
+        """Handle successful response"""
+
+    @abstractmethod
+    def error_callback(self, response: requests.Response) -> None:
+        """Handle error response"""
+
+    @abstractmethod
+    def is_request_successful(self, response: requests.Response) -> bool:
+        """Determine if the request was successful"""
+
+
+class RequestManager:
+    """
+        Maneja los request para poder hacer un exponential backoff
+    """
+
+    def __init__(self, manager: RequestActionManager, max_retries: int = 10):
+        """
+
+        :param decision: Objeto que ayuda a tomar decisiones para el exponential backoff
+        :param max_retries:
+        """
+
+        self.initial_delay = 1.0
+        self.max_delay = 60.0
+        self.backoff_factor = 1.5
+        self.max_retries = max_retries
+        self.manager = manager
+
+        # State variables
+        self.current_delay = self.initial_delay
+        self.retry_count = 0
+        self.running = False
+
+    def reset_delay(self):
+        """
+        Re-inicia el delay
+        :return:
+        """
+        self.current_delay = self.initial_delay
+        self.retry_count = 0
+
+    def increase_delay(self):
+        """
+        Aumenta el delay cada
+        :return:
+        """
+        self.current_delay = min(self.current_delay * self.backoff_factor, self.max_delay)
+        self.retry_count += 1
+
+    def should_continue(self) -> bool:
+        """
+        Determina si debe seguir ejecutando la accion
+        :return:
+        """
+
+        if not self.running:
+            return False
+        if self.max_retries is not None and self.retry_count >= self.max_retries:
+            return False
+        return True
+
+    def stop(self):
+        """
+        Detiene la ejecusion fozosamente
+        :return:
+        """
+        self.running = False
+
+    def start(self):
+        """
+        Inicia el proceso de llamada con backoof
+        :return:
+        """
+        self.running = True
+        while self.should_continue():
+            try:
+                response = self.manager.on_execute()
+
+                if self.manager.is_request_successful(response=response):
+                    self.stop()
+                    self.manager.success_callback(response=response)
+                    self.reset_delay()
+                else:
+                    self.manager.error_callback(response=response)
+                    self.increase_delay()
+
+            except requests.exceptions.RequestException:
+                self.increase_delay()
+            except KeyboardInterrupt:
+                self.stop()
+            except Exception:
+                self.increase_delay()
+            if self.should_continue():
+                time.sleep(self.current_delay)

creditpulse-0.0.1/creditpulse.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: creditpulse
+Version: 0.0.1
+Summary: A pyhton library for financial analysis with external databases
+Author-email: Santiago Velez <s.velez@saman-wm.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click==8.1.8
+Requires-Dist: requests==2.32.4
+Requires-Dist: pydantic==2.8.0
+Requires-Dist: pylint==3.3.7
+Dynamic: license-file

creditpulse-0.0.1/creditpulse.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+creditpulse/__init__.py
+creditpulse/check.py
+creditpulse.egg-info/PKG-INFO
+creditpulse.egg-info/SOURCES.txt
+creditpulse.egg-info/dependency_links.txt
+creditpulse.egg-info/entry_points.txt
+creditpulse.egg-info/requires.txt
+creditpulse.egg-info/top_level.txt
+creditpulse/bases_externas/__init__.py
+creditpulse/bases_externas/database.py
+creditpulse/bases_externas/external.py
+creditpulse/bases_externas/schema.py
+creditpulse/bases_externas/truora.py
+creditpulse/cli/__init__.py
+creditpulse/cli/commands.py
+creditpulse/common/__init__.py
+creditpulse/common/error_messages.py
+creditpulse/requests/__init__.py
+creditpulse/requests/request_manager.py
+test/test_back_off.py
+test/test_truora_check.py

creditpulse-0.0.1/creditpulse.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

creditpulse-0.0.1/creditpulse.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+creditpulse = creditpulse.cli.commands:main

creditpulse-0.0.1/creditpulse.egg-info/requires.txt

@@ -0,0 +1,4 @@
+click==8.1.8
+requests==2.32.4
+pydantic==2.8.0
+pylint==3.3.7

creditpulse-0.0.1/creditpulse.egg-info/top_level.txt

@@ -0,0 +1 @@
+creditpulse

creditpulse-0.0.1/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "creditpulse"
+version = "0.0.1"
+description = "A pyhton library for financial analysis with external databases"
+authors = [{ name = "Santiago Velez", email = "s.velez@saman-wm.com" }]
+readme = "README.md"
+requires-python = ">=3.7"
+
+dependencies = [
+    "click==8.1.8",
+    "requests==2.32.4",
+    "pydantic==2.8.0",
+    "pylint==3.3.7"
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+creditpulse = "creditpulse.cli.commands:main"

creditpulse-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

creditpulse-0.0.1/test/test_back_off.py

@@ -0,0 +1,56 @@
+from creditpulse.requests.request_manager import RequestManager, RequestActionManager
+
+import unittest
+import requests
+
+
+class SimpleCheck(RequestActionManager):
+
+    def __init__(self, endpoint):
+        self.endpoint = endpoint
+        self.success_called = False
+        self.error_called = False
+
+    def on_execute(self) -> requests.Response:
+        return requests.get(self.endpoint)
+
+    def success_callback(self, response: requests.Response) -> None:
+        self.success_called = True
+
+    def error_callback(self, response: requests.Response) -> None:
+        self.error_called = True
+
+    def is_request_successful(self, response: requests.Response) -> bool:
+        return response.status_code in [200, 201]
+
+
+class TestRequestManager(unittest.TestCase):
+
+    def test_request_success(self):
+        check = SimpleCheck(endpoint='https://httpbin.org/get')
+        manager = RequestManager(
+            manager=check,
+            max_retries=1
+        )
+
+        manager.start()
+
+        self.assertTrue(check.success_called, "Success callback was not called")
+
+    def test_request_error(self):
+        self.error_callback_code = 200
+        self.retries = 3
+        check = SimpleCheck(endpoint='https://httpbin.org/status/500')
+
+        manager = RequestManager(
+            manager=check,
+            max_retries=self.retries,
+        )
+
+        manager.start()
+        self.assertTrue(check.error_called, "Success callback was not called")
+        self.assertEqual(manager.retry_count, self.retries)
+
+
+if __name__ == '__main__':
+    unittest.main()

creditpulse-0.0.1/test/test_truora_check.py

@@ -0,0 +1,16 @@
+import unittest
+
+from creditpulse.bases_externas.truora import Truora
+from creditpulse.bases_externas.schema import CountryCode, PersonType
+
+
+class TestTruoraCheck(unittest.TestCase):
+
+    def test_simple_request(self):
+        client = Truora()
+        client.create_check(
+            identificacion='1053778047',
+            person_type=PersonType.PERSONA,
+            pais=CountryCode.COLOMBIA,
+            autorizacion_datos=True
+        )