luxorasap 0.1.0__tar.gz → 0.1.2__tar.gz

luxorasap-0.1.2/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: luxorasap
+Version: 0.1.2
+Summary: Luxor’s unified toolbox for data ingestion, querying and analytics.
+Author-email: Luxor Group <backoffice@luxor.com.br>
+License: Proprietary – All rights reserved
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.2
+Requires-Dist: numpy>=1.25
+Requires-Dist: loguru>=0.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: azure-storage-blob>=12.19
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: requests>=2.32
+Requires-Dist: pydantic>=2.7
+Requires-Dist: scipy>=1.13
+Requires-Dist: openpyxl
+Provides-Extra: storage
+Requires-Dist: azure-storage-blob>=12.19; extra == "storage"
+Requires-Dist: pyarrow>=15.0; extra == "storage"
+Provides-Extra: dataframe
+Requires-Dist: pandas>=2.2; extra == "dataframe"
+Provides-Extra: datareader
+Requires-Dist: luxorasap[dataframe,storage]; extra == "datareader"
+Requires-Dist: numpy>=1.25; extra == "datareader"
+Requires-Dist: scipy>=1.13; extra == "datareader"
+Provides-Extra: ingest
+Requires-Dist: luxorasap[dataframe,storage]; extra == "ingest"
+Requires-Dist: pandas>=2.2; extra == "ingest"
+Provides-Extra: btgapi
+Requires-Dist: requests>=2.32; extra == "btgapi"
+Requires-Dist: pydantic>=2.7; extra == "btgapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: requests-mock>=1.11; extra == "dev"
+Requires-Dist: black>=24.4.0; extra == "dev"
+Requires-Dist: isort>=5.13; extra == "dev"
+Requires-Dist: bumpver>=2024.3; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+
+# 📚 Documentação LuxorASAP
+
+> Guia do desenvolvedor para os subpacotes **datareader**, **ingest**, **btgapi** e **utils**.
+>
+> • Instalação rápida  • Visão arquitetural  • APIs detalhadas  • Exemplos de uso  • Extras opcional
+
+---
+
+## Índice
+
+1. [Visão Geral](#visao-geral)
+2. [Instalação](#instalacao)
+3. [utils](#utils)
+4. [datareader](#datareader)
+5. [ingest](#ingest)
+6. [btgapi](#btgapi)
+7. [Roadmap & Contribuições](#roadmap)
+
+---
+
+## 1. Visão Geral
+
+LuxorASAP é o *toolbox* unificado da Luxor para ingestão, consulta e automação de dados financeiros.
+
+| Subpacote      | Função‑chave                                                          | Extras PyPI            |
+| -------------- | --------------------------------------------------------------------- | ---------------------- |
+| **utils**      | Utilidades puras (I/O ADLS, transformação de DataFrame, decorators)   | `storage`, `dataframe` |
+| **datareader** | Consulta de preços/tabelas no data lake via `LuxorQuery`              | `datareader`           |
+| **ingest**     | Carga de dados nova (parquet/zip/excel) em ADLS + loader legado       | `ingest`               |
+| **btgapi**     | Wrapper autenticado para as APIs do BTG Pactual (relatórios & trades) | `btgapi`               |
+
+---
+
+## 2. Instalação
+
+```bash
+# core + leitura de dados
+pip install luxorasap[datareader]
+
+# tudo incluído (leitura, ingest, btg)
+pip install luxorasap[datareader,ingest,btgapi]
+
+# desenvolvimento
+pip install -e ".[dev]"
+```
+
+Extras podem ser combinados à vontade (`luxorasap[storage]`, etc.).
+
+Configuração obrigatória do **ADLS**:
+
+```bash
+export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=..."
+```
+
+---
+
+## 3. utils
+
+Camada de utilidades **sem dependências internas**.
+
+### 3.1 storage.BlobParquetClient
+
+```python
+from luxorasap.utils.storage import BlobParquetClient
+client = BlobParquetClient(container="luxorasap")
+
+# write
+client.write_df(df, "bronze/parquet/mytable.parquet")
+
+# read (tuple -> DataFrame, success_flag)
+df, ok = client.read_df("bronze/parquet/mytable.parquet")
+```
+
+### 3.2 dataframe
+
+```python
+from luxorasap.utils.dataframe import prep_for_save, persist_column_formatting, read_bytes
+
+df2 = prep_for_save(df, index=True, index_name="ID", normalize=True)
+```
+
+### 3.3 decorators & misc
+
+`with_retry`, `chunkify`, `timer`… ficam em *utils.helpers* (caso precise).
+
+---
+
+## 4. datareader
+
+### 4.1 Visão rápida
+
+```python
+from luxorasap.datareader import LuxorQuery
+lq = LuxorQuery()
+
+# DataFrame completo
+df = lq.get_table("assets")
+
+# Série de preços diária
+aapl = lq.get_prices("aapl us equity", start="2025-01-01", end="2025-03-31")
+
+# Preço pontual
+price = lq.get_price("aapl us equity", on="2025-03-31")
+```
+
+*Caching*: `@lru_cache(maxsize=32)` evita hits repetidos ao Blob.
+
+### 4.2 Métodos-chave
+
+| Método                                          | Descrição                     |
+| ----------------------------------------------- | ----------------------------- |
+| `table_exists(name)`                            | checa metadados no ADLS       |
+| `get_table(name)`                               | DataFrame completo (cached)   |
+| `get_prices(asset, start, end, column="Price")` | `pd.Series`                   |
+| `get_price(asset, on)`                          | preço pontual (float ou None) |
+
+---
+
+## 5. ingest
+
+### 5.1 ingest.cloud (novo)
+
+```python
+from luxorasap.ingest import save_table, incremental_load
+from luxorasap.datareader import LuxorQuery
+
+save_table("trades", df)
+
+lq = LuxorQuery()
+incremental_load(lq, "prices_daily", df_new, increment_column="Date")
+```
+
+### 5.2 ingest.legacy\_local
+
+```python
+from luxorasap.ingest import DataLoader   # Deprecado – ainda funcional
+```
+
+*Decoration*: ao importar `DataLoader` você verá `DeprecationWarning`.
+
+---
+
+## 6. btgapi
+
+### 6.1 Autenticação
+
+```python
+from luxorasap.btgapi import get_access_token
+TOKEN = get_access_token(test_env=True)
+```
+
+### 6.2 Relatórios – Portfolio & Investor Transactions
+
+```python
+from luxorasap.btgapi.reports import (
+    request_portfolio, await_report_ticket_result, process_zip_to_dfs,
+    request_investors_transactions_report,
+)
+
+ticket = request_portfolio(TOKEN, "LUXOR FUND - CLASS A",
+                           start=dt.date(2025,1,1), end=dt.date(2025,1,31))
+zip_bytes = await_report_ticket_result(TOKEN, ticket)
+carteiras = process_zip_to_dfs(zip_bytes)
+```
+
+### 6.3 Trades offshore
+
+```python
+from luxorasap.btgapi.trades import (
+    submit_offshore_equity_trades,
+    await_transaction_ticket_result,
+)
+
+ticket = submit_offshore_equity_trades(TOKEN, trades=[{...}], test_env=True)
+status_df = await_transaction_ticket_result(TOKEN, ticket, test_env=True)
+```
+
+### 6.4 Extras
+
+* `BTGApiError` — exceção customizada para qualquer falha.
+
+---
+
+## 7. Roadmap & Contribuições
+
+* **Remover** `ingest.legacy_local` quando não houver mais dependências.
+* Suporte a partições Parquet (delta‑like) na gravação.
+* Adicionar `pydantic` para validar contratos BTG.
+* Pull requests bem‑vindos!  Rode `make lint && pytest -q` antes de enviar.
+
+---
+
+### Contatos
+
+* Dados / Back‑Office – [backoffice@luxor.com.br](mailto:backoffice@luxor.com.br)
+* Mantenedor principal – Sergio

luxorasap-0.1.2/README.md

@@ -0,0 +1,196 @@
+# 📚 Documentação LuxorASAP
+
+> Guia do desenvolvedor para os subpacotes **datareader**, **ingest**, **btgapi** e **utils**.
+>
+> • Instalação rápida  • Visão arquitetural  • APIs detalhadas  • Exemplos de uso  • Extras opcional
+
+---
+
+## Índice
+
+1. [Visão Geral](#visao-geral)
+2. [Instalação](#instalacao)
+3. [utils](#utils)
+4. [datareader](#datareader)
+5. [ingest](#ingest)
+6. [btgapi](#btgapi)
+7. [Roadmap & Contribuições](#roadmap)
+
+---
+
+## 1. Visão Geral
+
+LuxorASAP é o *toolbox* unificado da Luxor para ingestão, consulta e automação de dados financeiros.
+
+| Subpacote      | Função‑chave                                                          | Extras PyPI            |
+| -------------- | --------------------------------------------------------------------- | ---------------------- |
+| **utils**      | Utilidades puras (I/O ADLS, transformação de DataFrame, decorators)   | `storage`, `dataframe` |
+| **datareader** | Consulta de preços/tabelas no data lake via `LuxorQuery`              | `datareader`           |
+| **ingest**     | Carga de dados nova (parquet/zip/excel) em ADLS + loader legado       | `ingest`               |
+| **btgapi**     | Wrapper autenticado para as APIs do BTG Pactual (relatórios & trades) | `btgapi`               |
+
+---
+
+## 2. Instalação
+
+```bash
+# core + leitura de dados
+pip install luxorasap[datareader]
+
+# tudo incluído (leitura, ingest, btg)
+pip install luxorasap[datareader,ingest,btgapi]
+
+# desenvolvimento
+pip install -e ".[dev]"
+```
+
+Extras podem ser combinados à vontade (`luxorasap[storage]`, etc.).
+
+Configuração obrigatória do **ADLS**:
+
+```bash
+export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=..."
+```
+
+---
+
+## 3. utils
+
+Camada de utilidades **sem dependências internas**.
+
+### 3.1 storage.BlobParquetClient
+
+```python
+from luxorasap.utils.storage import BlobParquetClient
+client = BlobParquetClient(container="luxorasap")
+
+# write
+client.write_df(df, "bronze/parquet/mytable.parquet")
+
+# read (tuple -> DataFrame, success_flag)
+df, ok = client.read_df("bronze/parquet/mytable.parquet")
+```
+
+### 3.2 dataframe
+
+```python
+from luxorasap.utils.dataframe import prep_for_save, persist_column_formatting, read_bytes
+
+df2 = prep_for_save(df, index=True, index_name="ID", normalize=True)
+```
+
+### 3.3 decorators & misc
+
+`with_retry`, `chunkify`, `timer`… ficam em *utils.helpers* (caso precise).
+
+---
+
+## 4. datareader
+
+### 4.1 Visão rápida
+
+```python
+from luxorasap.datareader import LuxorQuery
+lq = LuxorQuery()
+
+# DataFrame completo
+df = lq.get_table("assets")
+
+# Série de preços diária
+aapl = lq.get_prices("aapl us equity", start="2025-01-01", end="2025-03-31")
+
+# Preço pontual
+price = lq.get_price("aapl us equity", on="2025-03-31")
+```
+
+*Caching*: `@lru_cache(maxsize=32)` evita hits repetidos ao Blob.
+
+### 4.2 Métodos-chave
+
+| Método                                          | Descrição                     |
+| ----------------------------------------------- | ----------------------------- |
+| `table_exists(name)`                            | checa metadados no ADLS       |
+| `get_table(name)`                               | DataFrame completo (cached)   |
+| `get_prices(asset, start, end, column="Price")` | `pd.Series`                   |
+| `get_price(asset, on)`                          | preço pontual (float ou None) |
+
+---
+
+## 5. ingest
+
+### 5.1 ingest.cloud (novo)
+
+```python
+from luxorasap.ingest import save_table, incremental_load
+from luxorasap.datareader import LuxorQuery
+
+save_table("trades", df)
+
+lq = LuxorQuery()
+incremental_load(lq, "prices_daily", df_new, increment_column="Date")
+```
+
+### 5.2 ingest.legacy\_local
+
+```python
+from luxorasap.ingest import DataLoader   # Deprecado – ainda funcional
+```
+
+*Decoration*: ao importar `DataLoader` você verá `DeprecationWarning`.
+
+---
+
+## 6. btgapi
+
+### 6.1 Autenticação
+
+```python
+from luxorasap.btgapi import get_access_token
+TOKEN = get_access_token(test_env=True)
+```
+
+### 6.2 Relatórios – Portfolio & Investor Transactions
+
+```python
+from luxorasap.btgapi.reports import (
+    request_portfolio, await_report_ticket_result, process_zip_to_dfs,
+    request_investors_transactions_report,
+)
+
+ticket = request_portfolio(TOKEN, "LUXOR FUND - CLASS A",
+                           start=dt.date(2025,1,1), end=dt.date(2025,1,31))
+zip_bytes = await_report_ticket_result(TOKEN, ticket)
+carteiras = process_zip_to_dfs(zip_bytes)
+```
+
+### 6.3 Trades offshore
+
+```python
+from luxorasap.btgapi.trades import (
+    submit_offshore_equity_trades,
+    await_transaction_ticket_result,
+)
+
+ticket = submit_offshore_equity_trades(TOKEN, trades=[{...}], test_env=True)
+status_df = await_transaction_ticket_result(TOKEN, ticket, test_env=True)
+```
+
+### 6.4 Extras
+
+* `BTGApiError` — exceção customizada para qualquer falha.
+
+---
+
+## 7. Roadmap & Contribuições
+
+* **Remover** `ingest.legacy_local` quando não houver mais dependências.
+* Suporte a partições Parquet (delta‑like) na gravação.
+* Adicionar `pydantic` para validar contratos BTG.
+* Pull requests bem‑vindos!  Rode `make lint && pytest -q` antes de enviar.
+
+---
+
+### Contatos
+
+* Dados / Back‑Office – [backoffice@luxor.com.br](mailto:backoffice@luxor.com.br)
+* Mantenedor principal – Sergio

{luxorasap-0.1.0 → luxorasap-0.1.2}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
 #############################
 [project]
 name            = "luxorasap"
-version = "0.1.0"
+version = "0.1.2"
 description     = "Luxor’s unified toolbox for data ingestion, querying and analytics."
 readme          = "README.md"
 requires-python = ">=3.9"
@@ -36,6 +36,7 @@ dependencies = [
   "requests>=2.32",     # usado por btgapi
   "pydantic>=2.7",      # usado por btgapi
   "scipy>=1.13",
+  "openpyxl"
 ]
 
 [project.optional-dependencies]
@@ -47,6 +48,7 @@ ingest     = ["luxorasap[storage,dataframe]", "pandas>=2.2"]
 btgapi     = ["requests>=2.32", "pydantic>=2.7"]
 dev        = [
   "pytest>=8.2",
+  "requests-mock>=1.11",
   "black>=24.4.0",
   "isort>=5.13",
   "bumpver>=2024.3",
@@ -72,7 +74,7 @@ exclude = ["tests*"]
 # bumpver (sem-ver)
 #############################
 [tool.bumpver]
-current_version = "0.1.0"
+current_version = "0.1.2"
 version_pattern = "MAJOR.MINOR.PATCH"
 
 # regex explícito – obrigatório no bumpver 2024+

{luxorasap-0.1.0 → luxorasap-0.1.2}/src/luxorasap/__init__.py

@@ -13,7 +13,7 @@ from types import ModuleType
 try:
     __version__: str = metadata.version(__name__)
 except metadata.PackageNotFoundError:  # editable install
-    __version__ = "0.1.0"
+    __version__ = "0.1.2"
 
 # ─── Lazy loader ─────────────────────────────────────────────────
 def __getattr__(name: str) -> ModuleType:

luxorasap-0.1.2/src/luxorasap/btgapi/__init__.py

@@ -0,0 +1,16 @@
+"""Wrapper para as APIs do BTG Pactual."""
+
+from .auth import get_access_token, BTGApiError
+from .reports import request_portfolio, await_report_ticket_result, process_zip_to_dfs, request_investors_transactions_report
+from .trades import submit_offshore_equity_trades, await_transaction_ticket_result
+
+__all__ = [
+    "BTGApiError",
+    "get_access_token",
+    "request_portfolio",
+    "await_report_ticket_result",
+    "submit_offshore_equity_trades",
+    "await_transaction_ticket_result",
+    "process_zip_to_dfs",
+    "request_investors_transactions_report"
+]

luxorasap-0.1.2/src/luxorasap/btgapi/auth.py

@@ -0,0 +1,58 @@
+import os
+import requests
+from dotenv import load_dotenv
+from loguru import logger
+
+__all__ = ["BTGApiError", "get_access_token"]
+
+
+class BTGApiError(Exception):
+    """Erro genérico da API do BTG."""
+
+
+def get_access_token(*, client_id=None, client_secret=None, test_env: bool = True,
+                    timeout: int = 20) -> str:
+    """Obtém JWT válido por ~1 h para autenticação nas APIs BTG.
+    Args:
+        client_id: ID do cliente (opcional, lê de env var se None).
+        client_secret: Segredo do cliente (opcional, lê de env var se None).
+        test_env: Ambiente de teste (True) ou produção (False).
+        timeout: Timeout da requisição em segundos.
+
+    Returns:
+        Token de acesso.
+
+    Raises:
+        BTGApiError: Se as credenciais não estiverem disponíveis ou a requisição falhar.
+    """
+
+    if not client_id or not client_secret:
+        load_dotenv()
+        client_id = os.getenv("BTG_CLIENT_ID")
+        client_secret = os.getenv("BTG_CLIENT_SECRET")
+    if not client_id or not client_secret:
+        raise BTGApiError("BTG_CLIENT_ID ou BTG_CLIENT_SECRET não definidos no ambiente")
+
+    url = (
+        "https://funds-uat.btgpactual.com/connect/token"
+        if test_env
+        else "https://funds.btgpactual.com/connect/token"
+    )
+
+    resp = requests.post(
+        url,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        data={
+            "grant_type": "client_credentials",
+            "client_id": client_id,
+            "client_secret": client_secret,
+        },
+        timeout=timeout,
+    )
+
+    if resp.ok:
+        token = resp.json().get("access_token")
+        len_token = len(token) if token else None
+        logger.debug(f"Token BTG obtido (len={len_token})")
+        return token or ""
+    raise BTGApiError(f"Falha ao autenticar: HTTP {resp.status_code} – {resp.text}")