Se añadió Makefile y la carpeta ejemplos. Se añadió más contenido al README.rst. Se corrigieron la base de la API, boletas.py, y tests. Se eliminó la carpeta docs. Se debe volver a generar automáticamente con Sphinx. Se corrigieron múltiples errores de texto.

Author: SantiagoFiol

Makefile

@@ -0,0 +1,19 @@
+all: dist
+
+dist:
+	python3 setup.py sdist
+
+upload: dist
+	twine upload dist/*
+
+install-dev:
+	python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
+
+tests: install-dev
+	python tests/run.py
+
+docs:
+	sphinx-apidoc -o docs bhexpress && sphinx-build -b html docs docs/_build/html
+
+clean:
+	rm -rf dist bhexpress.egg-info bhexpress/__pycache__ bhexpress/*.pyc

README.rst

@@ -45,39 +45,78 @@ el cual será reconocida automáticamente por el cliente:
 
     client = Boleta()
 
-    boletas = self.client.listar()
+    boletas = client.listar()
     print(boletas)
 
 Lo que hizo el ejemplo anterior es listar boletas emitidas en un resultado e imprimir dicho resultado en consola.
 
 Ejemplos
 --------
 
-Estos ejemplos provienen de la versión PHP. Para crear la versión Python de BHExpress,
-se tomó en cuenta dichos ejemplos.
+Para crear la versión Python de BHExpress, se tomaron en cuenta ejemplos para 5 casos de uso que
+involucran boletas, y se llevaron a Python.
 Los ejemplos cubren los siguientes casos:
 
-- `001-boletas_listado.php`: obtener las boletas de un período.
-- `002-boleta_emitir.php`: emisitir una BHE.
-- `003-boleta_pdf.php`: descargar el PDF de una BHE.
-- `004-boleta_email.php`: enviar por email una BHE.
-- `005-boleta_anular.php`: anular una BHE.
+- `e01-boletas_listado.py`: obtener las boletas de un período.
+- `e02-boleta_emitir.py`: emitir una BHE.
+- `e03-boleta_pdf.py`: descargar el PDF de una BHE.
+- `e04-boleta_email.py`: enviar por email una BHE.
+- `e05-boleta_anular.py`: anular una BHE.
 
 Los ejemplos, por defecto, hacen uso de variables de entornos, si quieres usar
 esto debes tenerlas creadas, por ejemplo, en Windows 10, con:
 
 .. code:: shell
+
     set BHEXPRESS_API_URL="https://bhexpress.cl"
     set BHEXPRESS_API_TOKEN="" # aquí el token obtenido en https://bhexpress.cl/usuarios/perfil#token
     set BHEXPRESS_EMISOR_RUT="" # aquí el RUT del emisor de las BHE
 
-Ejemplo en la consola de Linux:
+Ejemplo de definición de variables de entorno en la consola de Linux:
 
 .. code:: shell
+    
     export BHEXPRESS_API_URL="https://bhexpress.cl"
     export BHEXPRESS_API_TOKEN="" # aquí el token obtenido en https://bhexpress.cl/usuarios/perfil#token
     export BHEXPRESS_EMISOR_RUT="" # aquí el RUT del emisor de las BHE
 
+Pruebas
+-------
+
+Las pruebas utilizan un archivo llamado `test.env`, que sirve para definir todas las variables de entorno
+necesarias para ejecutar estas pruebas. Las pruebas se crearon para probar los ejemplos vistos previamente 
+en el capítulo `Ejemplos`.
+
+Estas pruebas utilizan `unittest`, se ejecutan con el archivo `run.py`, y dependiendo de cómo se configure
+`test.env`, se pueden omitir ciertas pruebas. Asegúrate de definir `BHEXPRESS_API_URL`, `BHEXPRESS_API_TOKEN` 
+y `BHEXPRESS_EMISOR_RUT` en `test.env`, o no podrás efectuar las pruebas.
+
+A continuación se pondrán instrucciones de cómo probar el cliente de API de Python:
+
+* `test1_listar()`: 
+    - Prueba que permite obtener un listado de todas las boletas emitidas a través de BHExpress usando algunos filtros.
+    - Variables necesarias: `TEST_LISTAR_PERIODO`, `TEST_LISTAR_CODIGORECEPTOR`
+    - Variable de ejecución: `Ninguna`
+* `test2_emitir()`: 
+    - Prueba que permite emitir una BHE a un receptor.
+    - Variables necesarias: `TEST_EMITIR_FECHA_EMIS`, `TEST_EMITIR_EMISOR`, `TEST_EMITIR_RECEPTOR`, `TEST_EMITIR_RZNSOC_REC`, `TEST_EMITIR_DIR_REC`, `TEST_EMITIR_COM_REC` 
+    - Variable de ejecución: `TEST_EMITIR_EMISOR`
+* `test3_pdf()`: 
+    - Prueba que permite obtener una BHE y convertirla a un PDF.
+    - Variables necesarias: `Ninguna`
+    - Variable de ejecución: `TEST_PDF_PROBAR`
+* `test4_email()`: 
+    - Prueba que permite enviar un email a un destinatario con una BHE específica.
+    - Variables necesarias: `TEST_EMAIL_NUMEROBHE`, `TEST_EMAIL_CORREO`
+    - Variable de ejecución: `TEST_EMAIL_NUMEROBHE` y `TEST_EMAIL_CORREO`
+* `test5_anular()`: 
+    - Prueba que permite anular una BHE existente.
+    - Variables necesarias: `Ninguna`
+    - Variables de ejecución: `TEST_ANULAR_PROBAR`
+
+Las `variables necesarias` son aquellas variables que se necesitan para ejecutar las pruebas.
+Las `variables de ejecución` son aquellas variables que permitirán ejecutar u omitir las pruebas a las que pertenecen.
+Si las variables de ejecución tienen un valor específico o son texto en blanco, entonces la prueba será omitida, pero no fallida.
 
 Licencia
 --------

bhexpress/api_client/__init__.py

@@ -36,9 +36,13 @@ class ApiClient:
     __DEFAULT_URL = 'https://bhexpress.cl'
     __DEFAULT_VERSION = 'v1'
 
-    def __init__(self, token=None, url=None, version=None, raise_for_status=True):
+    def __init__(self, token = None, url = None, version = None, raise_for_status = True):
+        '''
+        Constructor para inicializar el Cliente de la API de BHExpress.
+        '''
         self.token = self.__validate_token(token)
         self.url = self.__validate_url(url)
+        self.rut = self.__validate_rut()
         self.headers = self.__generate_headers()
         self.version = version or self.__DEFAULT_VERSION
         self.raise_for_status = raise_for_status
@@ -68,6 +72,20 @@ def __validate_url(self, url):
         '''
         return str(url).strip() if url else getenv('BHEXPRESS_API_URL', self.__DEFAULT_URL).strip()
 
+    def __validate_rut(self):
+        '''
+        Valida y retorna el RUT del Emisor de BHEs a utilizar.
+
+        :param str rut: RUT a validar.
+        :return: RUT validado.
+        :rtype: str
+        :raises ApiException: Si el RUT no es válido o está ausente.
+        '''
+        rut = getenv('BHEXPRESS_EMISOR_RUT', '')
+        if rut == '':
+            raise ApiException('Se debe configurar la variable de entorno: BHEXPRESS_EMISOR_RUT.')
+        return str(rut).strip()
+
     def __generate_headers(self):
         '''
         Genera y retorna las cabeceras por defecto para las solicitudes.
@@ -78,11 +96,12 @@ def __generate_headers(self):
         return {
             'User-Agent': 'BHExpress: Cliente de API en Python.',
             'Accept': 'application/json',
-            'Content-Type': 'application/json', # Faltaba ESTA línea de código...
-            'Authorization': 'Token ' + self.token
+            'Content-Type': 'application/json',
+            'Authorization': 'Token %(token)s' % {'token': self.token},
+            'X-Bhexpress-Emisor': self.rut
         }
 
-    def get(self, resource, headers=None):
+    def get(self, resource, headers = None):
         '''
         Realiza una solicitud GET a la API.
 
@@ -91,9 +110,9 @@ def get(self, resource, headers=None):
         :return: Respuesta de la solicitud.
         :rtype: requests.Response
         '''
-        return self.__request('GET', resource, headers=headers)
+        return self.__request('GET', resource, headers = headers)
 
-    def delete(self, resource, headers=None):
+    def delete(self, resource, headers = None):
         '''
         Realiza una solicitud DELETE a la API.
 
@@ -102,9 +121,9 @@ def delete(self, resource, headers=None):
         :return: Respuesta de la solicitud.
         :rtype: requests.Response
         '''
-        return self.__request('DELETE', resource, headers=headers)
+        return self.__request('DELETE', resource, headers = headers)
 
-    def post(self, resource, data=None, headers=None):
+    def post(self, resource, data = None, headers = None):
         '''
         Realiza una solicitud POST a la API.
 
@@ -114,9 +133,9 @@ def post(self, resource, data=None, headers=None):
         :return: Respuesta de la solicitud.
         :rtype: requests.Response
         '''
-        return self.__request('POST', resource, data, headers)
+        return self.__request('POST', resource, data = data, headers = headers)
 
-    def put(self, resource, data=None, headers=None):
+    def put(self, resource, data = None, headers = None):
         '''
         Realiza una solicitud PUT a la API.
 
@@ -126,9 +145,9 @@ def put(self, resource, data=None, headers=None):
         :return: Respuesta de la solicitud.
         :rtype: requests.Response
         '''
-        return self.__request('PUT', resource, data, headers)
+        return self.__request('PUT', resource, data = data, headers = headers)
 
-    def __request(self, method, resource, data=None, headers=None):
+    def __request(self, method, resource, data = None, headers = None):
         '''
         Método privado para realizar solicitudes HTTP.
 
@@ -140,21 +159,21 @@ def __request(self, method, resource, data=None, headers=None):
         :rtype: requests.Response
         :raises ApiException: Si el método HTTP no es soportado o si hay un error de conexión.
         '''
-        api_path = f'/api/{self.version}{resource}'
+        api_path = '/api/%(version)s%(resource)s' % {'version': self.version, 'resource': resource}
         full_url = urllib.parse.urljoin(self.url + '/', api_path.lstrip('/'))
         headers = headers or {}
         headers = {**self.headers, **headers}
         if data and not isinstance(data, str):
             data = json.dumps(data)
         try:
-            response = requests.request(method, full_url, data=data, headers=headers)
+            response = requests.request(method, full_url, data = data, headers = headers)
             return self.__check_and_return_response(response)
         except requests.exceptions.ConnectionError as error:
-            raise ApiException(f'Error de conexión: {error}')
+            raise ApiException('Error de conexión: %(error)s' % {'error': error})
         except requests.exceptions.Timeout as error:
-            raise ApiException(f'Error de timeout: {error}')
+            raise ApiException('Error de timeout: %(error)s' % {'error': error})
         except requests.exceptions.RequestException as error:
-            raise ApiException(f'Error en la solicitud: {error}')
+            raise ApiException('Error en la solicitud: %(error)s' % {'error': error})
 
     def __check_and_return_response(self, response):
         '''
@@ -173,20 +192,23 @@ def __check_and_return_response(self, response):
                     error = response.json()
                     message = error.get('message', '') or error.get('exception', '') or 'Error desconocido.'
                 except json.decoder.JSONDecodeError:
-                    message = f'Error al decodificar los datos en JSON: {response.text}'
-                raise ApiException(f'Error HTTP: {message}')
+                    message = 'Error al decodificar los datos en JSON: %(response)s' % {'response': response.text}
+                raise ApiException('Error HTTP: %(message)s' % {'message': message})
         return response
 
 class ApiException(Exception):
     '''
     Excepción personalizada para errores en el cliente de la API.
-
-    :param str message: Mensaje de error.
-    :param int code: Código de error (opcional).
-    :param dict params: Parámetros adicionales del error (opcional).
     '''
 
-    def __init__(self, message, code=None, params=None):
+    def __init__(self, message, code = None, params = None):
+        '''
+        Constructor para la creación de manejo de errores.
+
+        :param str message: Mensaje de error.
+        :param int code: Código de error (opcional).
+        :param dict params: Parámetros adicionales del error (opcional).
+        '''
         self.message = message
         self.code = code
         self.params = params
@@ -207,9 +229,9 @@ def __str__(self):
         :return: Una cadena que representa el error de una manera clara y concisa.
         '''
         if self.code is not None:
-            return f'[BHExpress] Error {self.code}: {self.message}'
+            return '[BHExpress] Error %(code)s: %(message)s' % {'code': self.code, 'message': self.message}
         else:
-            return f'[BHExpress] {self.message}'
+            return '[BHExpress] %(message)s' % {'message': self.message}
 
 class ApiBase(ABC):
     '''
@@ -221,6 +243,6 @@ class ApiBase(ABC):
     :param bool api_raise_for_status: Si se debe lanzar una excepción automáticamente para respuestas de error HTTP. Por defecto es True.
     '''
 
-    def __init__(self, api_token=None, api_url=None, api_version=None, api_raise_for_status=True):
+    def __init__(self, api_token = None, api_url = None, api_version = None, api_raise_for_status = True):
         self.client = ApiClient(api_token, api_url, api_version, api_raise_for_status)