Merge pull request #9 from cuenca-mx/feature/new-api-integration

Feature/new api integration

.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+      - name: Install dependencies
+        run: pip install -qU setuptools wheel twine
+      - name: Generating distribution archives
+        run: python setup.py sdist bdist_wheel
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,58 @@
+name: test
+
+on: push
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+      - name: Install dependencies
+        run: make install-test
+      - name: Lint
+        run: make lint
+
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: make install-test
+    - name: Run tests
+      run: |
+        export $(<env.template)
+        pytest
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+      - name: Install dependencies
+        run: make install-test
+      - name: Generate coverage report
+        run: |
+          export $(<env.template)
+          pytest --cov-report=xml
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: true

Makefile

@@ -1,32 +1,54 @@
 SHELL := bash
 PATH := ./venv/bin:${PATH}
-PYTHON=python3.7
+PYTHON = python3.13
+PROJECT = quienesquien
+isort = isort $(PROJECT) tests setup.py
+black = black -S -l 79 --target-version py313 $(PROJECT) tests setup.py
 
 
 all: test
 
-install-dev:
-		pip install -q -e .[dev]
-
 venv:
-		$(PYTHON) -m venv --prompt quienesquien venv
-		source venv/bin/activate
-		pip install --quiet --upgrade pip
+	$(PYTHON) -m venv --prompt $(PROJECT) venv
+	pip install -qU pip
+
+install:
+	pip install -qU -r requirements.txt
 
-test: clean install-dev lint
-		python setup.py test
+install-test: install
+	pip install -qU -r requirements-test.txt
 
-coverage: clean install-dev lint
-		coverage run --source=quienesquien setup.py test
-		coverage report -m
+test: clean install-test lint
+	pytest
+
+format:
+	$(isort)
+	$(black)
 
 lint:
-		pycodestyle setup.py quienesquien/
+	flake8 $(PROJECT) tests setup.py
+	$(isort) --check-only
+	$(black) --check
+	mypy $(PROJECT) tests
 
 clean:
-		find . -name '*.pyc' -exec rm -f {} +
-		find . -name '*.pyo' -exec rm -f {} +
-		find . -name '*~' -exec rm -f {} +
-		rm -rf build dist quienesquien.egg-info
-
-.PHONY: all coverage lint install-dev release test clean
+	rm -rf `find . -name __pycache__`
+	rm -f `find . -type f -name '*.py[co]' `
+	rm -f `find . -type f -name '*~' `
+	rm -f `find . -type f -name '.*~' `
+	rm -rf .cache
+	rm -rf .pytest_cache
+	rm -rf .mypy_cache
+	rm -rf htmlcov
+	rm -rf *.egg-info
+	rm -f .coverage
+	rm -f .coverage.*
+	rm -rf build
+	rm -rf dist
+
+release: test clean
+	python setup.py sdist bdist_wheel
+	twine upload dist/*
+
+
+.PHONY: all install-test test format lint clean release

README.md

@@ -1,6 +1,91 @@
-# quienesquien-python
+# quienesquien
 
-Cliente para el servicio de listas de Quienesquien
+[![test](https://github.com/cuenca-mx/quienesquien-python/workflows/test/badge.svg)](https://github.com/cuenca-mx/quienesquien-python/actions?query=workflow%3Atest)
+[![codecov](https://codecov.io/gh/cuenca-mx/quienesquien-python/branch/master/graph/badge.svg)](https://codecov.io/gh/cuenca-mx/quienesquien-python)
+[![PyPI](https://img.shields.io/pypi/v/quienesquien.svg)](https://pypi.org/project/quienesquien/)
 
-**Requerimientos**
-Python v3 o superior
+Client for the Quienesquien list service (https://app.q-detect.com/)
+
+## Installation
+
+```bash
+pip install quienesquien
+```
+
+## Development & Testing
+
+The project configuration is managed through environment variables. Set them before running tests:
+```bash
+export $(<env.template)
+```
+
+To run unit tests, use `pytest`.
+```bash
+pytest
+```
+
+## Usage
+
+Before using the client, configure the required environment variables:
+```bash
+export QEQ_USER=your_user
+export QEQ_CLIENT_ID=your_client_id
+export QEQ_SECRET_ID=your_secret_key
+```
+
+## Example
+```python
+import os
+from quienesquien import Client
+from quienesquien.enums import Gender, SearchList, SearchType
+from quienesquien.exc import (
+    InsufficientBalanceError,
+    InvalidPlanError,
+    InvalidTokenError,
+    PersonNotFoundError,
+)
+
+client = Client(
+    os.environ['QEQ_USER'],
+    os.environ['QEQ_CLIENT_ID'],
+    os.environ['QEQ_SECRET_ID'],
+)
+
+try:
+    persons = await client.search(
+        full_name='Andres Manuel Lopez Obrador',
+        match_score=85,
+        rfc='LOOA531113F15',
+        curp='LOOA531113HTCPBN07',
+        gender=Gender.masculino,
+        birthday=dt.date(1953, 11, 13),
+        search_type=SearchType.fisica,
+        search_list=(SearchList.PPE, SearchList.ONU),
+    )
+except InsufficientBalanceError:
+    print('Saldo insuficiente')
+except InvalidPlanError:
+    print('Plan inválido')
+except InvalidTokenError:
+    print('Token inválido')
+except PersonNotFoundError:
+    persons = []
+```
+
+## Search Parameters
+- `full_name` (str): Full name of the person.
+- `match_score` (int): Minimum match percentage (default: 60).
+- `rfc` (str): Mexican RFC.
+- `curp` (str): Mexican CURP.
+- `gender` (Gender): masculino or femenino.
+- `birthday` (datetime.date): Date of birth.
+- `search_type` (SearchType): fisica or moral.
+- `search_list` (tuple[SearchList, ...]): Lists to search.
+    If not provided, searches all.
+
+The search follows a hierarchical approach: it first attempts to find a match using the RFC.
+If no match is found, it searches by CURP. Finally, if neither is found, it looks for a match by name.
+You must specify at least one search parameter: full_name, rfc or curp.
+
+## Response Structure
+- `persons` (list): List of matched persons.

env.template

@@ -0,0 +1,3 @@
+[email protected]
+QEQ_CLIENT_ID=123456-1234-1234
+QEQ_SECRET_ID=notsecurepassword

quienesquien/__init__.py

@@ -1 +1,5 @@
-name = "quienesquien"
+__all__ = ['__version__', 'Client', 'Person']
+
+from .client import Client
+from .person import Person
+from .version import __version__