Metadata-Version: 2.4
Name: pysage50e
Version: 0.1.3
Summary: API Python para interactuar con bases de datos Sage50 de forma sencilla y eficiente
Author-email: Pablo Malo <pysage50e@pablomalo.es>
Maintainer-email: Pablo Malo <pysage50e@pablomalo.es>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/pablomaloes/pysage50e
Project-URL: Documentation, https://pablomalo.es/pysage50e
Project-URL: Repository, https://github.com/pablomaloes/pysage50e
Project-URL: Issues, https://github.com/pablomaloes/pysage50e/issues
Keywords: sage50,sql,database,api,erp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyodbc>=5.0.0
Requires-Dist: sqlparse>=0.4.0
Requires-Dist: pysimplegui-4-foss>=4.60.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# pysage50e

Libreria Python para conectar con bases de datos de Sage 50 (SQL Server), construir consultas por ejercicio y transformar resultados de forma sencilla.

Esta version expone como API principal la clase `apiSAGE50`.

## Que hace el codigo

- Carga y mantiene configuracion de conexion en `config.ini`.
- Lee datos del entorno Sage50 (terminal, `cfgclisrv.xml`, comunes, empresa, ejercicios).
- Conecta a SQL Server con autenticacion SQL o Windows (con fallback).
- Genera consultas multi-ejercicio con placeholders de Sage (`#`, `COMUNES!`, etc.).
- Ejecuta SQL y devuelve resultados en varios formatos:
  - diccionario indexado (`sql_to_dict`)
  - lista (`sql_to_list`)
  - objeto tipo namespace (`sql_to_namespace`)
- Incluye logging y excepciones especificas de dominio (`Sage50Error`, `Sage50ConnectionError`, etc.).
- Incluye UI con `PySimpleGUI` para asistentes de configuracion cuando faltan datos.

## Instalacion

Con `pip`:

```bash
pip install pysage50e
```

Con `uv`:

```bash
uv pip install pysage50e
```

## Requisitos

- Windows
- Python 3.10 a 3.14
- Instalacion de Sage50 operativa
- SQL Server accesible desde el equipo
- Driver ODBC configurado por Sage (`cfgclisrv.xml`)

Dependencias runtime del paquete:

- `pyodbc>=5.0.0`
- `sqlparse>=0.4.0`
- `pysimplegui-4-foss>=4.60.4`

Nota de distribucion binaria:

- Este paquete se distribuye en wheels binarios (`.pyd`) por version de Python.
- Para cubrir 3.10, 3.11, 3.12, 3.13 y 3.14 hay que generar/publicar un wheel por cada version.

## Uso rapido

```python
from pysage50e import apiSAGE50

api = apiSAGE50()

if not api.lconecto:
    print(f"Error de conexion: {api.lasterror}")
else:
    print(f"Comunes: {api.comunes}")
    print(f"Empresa: {api.NomEmpresa}")
    print(f"Ejercicio actual: {api.tbyear[-1]}")
```

## Consultas SQL

### 1) Consulta simple con `build_query`

```python
from pysage50e import apiSAGE50

api = apiSAGE50()
sql = api.build_query("SELECT TOP 10 CODIGO, NOMBRE FROM #articulo")
datos = api.sql_to_list(sql)
print(datos)
```

### 2) Resultado como diccionario indexado

```python
sql = api.build_query("SELECT CODIGO, NOMBRE FROM #cliente")
clientes = api.sql_to_dict(sql, key_field="CODIGO")
print(clientes.get("00001"))
```

### 3) Resultado como objeto (namespace)

```python
sql = api.build_query("SELECT TOP 1 CODIGO, NOMBRE FROM #cliente")
cli = api.sql_to_namespace(sql)
print(cli.CODIGO, cli.NOMBRE)
```

## Especificación de ejercicios (years)

El query builder soporta selección por ejercicios con `SAGE50year`:

- `"*"` o `"@"`: Todos los ejercicios disponibles
- `"+"`: Último ejercicio
- `"+2023"`: Ejercicios desde 2023 en adelante
- `"-"`: Primer ejercicio
- `"-2022"`: Ejercicios hasta 2022
- `[2021, 2022, 2023]`: Lista explícita de Python (int, str o mixto)
- `"2024"` o `2024`: Ejercicio único (funciona con string o entero)

> **⚠️ Nota sobre años de cierre**: Los ejercicios de cierre (identificados con `XQ`, ej: `2026XQ`) se filtran automáticamente. Esto evita errores al consultar tablas vacías o inexistentes. Si necesitas acceder a un año de cierre específico, usa la sintaxis de lista: `[2026, 2025]`.

### Ejemplos de uso

```python
# Todos los ejercicios
aprocesar = api.SAGE50year("*")
# Resultado: ['2020EJ', '2021EJ', '2022EJ', '2023EJ', '2024EJ']

# Último ejercicio
aprocesar = api.SAGE50year("+")
# Resultado: '2024EJ'

# Desde 2023 en adelante
aprocesar = api.SAGE50year("+2023")
# Resultado: ['2023EJ', '2024EJ']

# Primer ejercicio
aprocesar = api.SAGE50year("-")
# Resultado: '2020EJ'

# Hasta 2022
aprocesar = api.SAGE50year("-2022")
# Resultado: ['2020EJ', '2021EJ', '2022EJ']

# Lista explícita (int, str o mixto)
aprocesar = api.SAGE50year([2021, "2022", 2023])
# Resultado: ['2021EJ', '2022EJ', '2023EJ']

# Ejercicio único (string o int)
aprocesar = api.SAGE50year("2024")
# Resultado: '2024EJ'

aprocesar = api.SAGE50year(2024)
# Resultado: '2024EJ'

# Uso en query
sql = api.build_query("SELECT * FROM #facturas", aprocesar)
rows = api.sql_to_list(sql)
```

## Recargar comunes/empresa

Puedes recargar el contexto activo:

```python
api.recargar(comunes="COMU0001", empresa="01")
```

## Logging y errores

El paquete exporta utilidades de logging y excepciones:

```python
from pysage50e import (
    log_info,
    log_warning,
    Sage50Error,
    Sage50ConnectionError,
)

try:
    api = apiSAGE50()
except Sage50ConnectionError as e:
    log_warning(str(e), context="conexion")
except Sage50Error as e:
    log_warning(str(e), context="general")
```

## Configuracion

La libreria usa `config.ini` para persistir configuracion local.
Si faltan datos (terminal, servidor, autenticacion), puede abrir asistentes GUI para completarlos.

## API publica principal

- `apiSAGE50`


## Soporte

- Email: `pysage50e@pablomalo.es`

## Licencia

Ver archivo `LICENSE`.
