luxorasap 0.1.1__tar.gz → 0.1.3__tar.gz

luxorasap-0.1.3/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: luxorasap
+Version: 0.1.3
+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.3/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.1 → luxorasap-0.1.3}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
 #############################
 [project]
 name            = "luxorasap"
-version = "0.1.1"
+version = "0.1.3"
 description     = "Luxor’s unified toolbox for data ingestion, querying and analytics."
 readme          = "README.md"
 requires-python = ">=3.9"
@@ -74,7 +74,7 @@ exclude = ["tests*"]
 # bumpver (sem-ver)
 #############################
 [tool.bumpver]
-current_version = "0.1.1"
+current_version = "0.1.3"
 version_pattern = "MAJOR.MINOR.PATCH"
 
 # regex explícito – obrigatório no bumpver 2024+

{luxorasap-0.1.1 → luxorasap-0.1.3}/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.1"
+    __version__ = "0.1.3"
 
 # ─── Lazy loader ─────────────────────────────────────────────────
 def __getattr__(name: str) -> ModuleType:

{luxorasap-0.1.1 → luxorasap-0.1.3}/src/luxorasap/btgapi/__init__.py

@@ -1,7 +1,7 @@
 """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 .reports import request_portfolio, await_report_ticket_result, process_zip_to_dfs, request_investors_transactions_report, request_fundflow_report
 from .trades import submit_offshore_equity_trades, await_transaction_ticket_result
 
 __all__ = [
@@ -12,5 +12,6 @@ __all__ = [
     "submit_offshore_equity_trades",
     "await_transaction_ticket_result",
     "process_zip_to_dfs",
-    "request_investors_transactions_report"
+    "request_investors_transactions_report",
+    "request_fundflow_report",
 ]

{luxorasap-0.1.1 → luxorasap-0.1.3}/src/luxorasap/btgapi/auth.py

@@ -52,6 +52,7 @@ def get_access_token(*, client_id=None, client_secret=None, test_env: bool = Tru
 
     if resp.ok:
         token = resp.json().get("access_token")
-        logger.debug("Token BTG obtido (len=%s)", len(token) if token else "None")
+        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}")

{luxorasap-0.1.1 → luxorasap-0.1.3}/src/luxorasap/btgapi/reports.py

@@ -16,7 +16,8 @@ __all__ = [
     "check_report_ticket",
     "await_report_ticket_result",
     "process_zip_to_dfs",
-    "request_investors_transactions_report"
+    "request_investors_transactions_report",
+    "request_fundflow_report"
 ]
 
 _REPORT_ENDPOINT = "https://funds.btgpactual.com/reports/Portfolio"
@@ -24,6 +25,7 @@ _TICKET_ENDPOINT = "https://funds.btgpactual.com/reports/Ticket"
 _INVESTOR_TX_ENDPOINT = (
     "https://funds.btgpactual.com/reports/RTA/InvestorTransactionsFileReport"
 )
+_FUNDFLOW_ENDPOINT = "https://funds.btgpactual.com/reports/RTA/FundFlow"
 _REPORT_TYPES = {"excel": 10, "xml5": 81, "pdf": 2}
 
 
@@ -93,7 +95,8 @@ def check_report_ticket(token: str, ticket: str, *, page: Optional[int] = None)
     # 2. Caso contrário tenta decodificar JSON
 
     result = payload.get("result")
-    if result == "Processando":
+    
+    if result == "Processando" or result == 'Aguardando processamento':
         raise BTGApiError("Processando")
     
     # 3. Quando pronto, result é JSON string com UrlDownload
@@ -103,7 +106,16 @@ def check_report_ticket(token: str, ticket: str, *, page: Optional[int] = None)
             url = info["UrlDownload"]
             return _download_url(url)
         except Exception as exc:
-            raise BTGApiError(f"Falha ao interpretar result: {exc}") from exc
+            raise BTGApiError(f"Falha ao interpretar resultado: {exc}") from exc
+    
+    # 4. result pode ser uma lista de dados
+    if isinstance(result, list):
+        # Vamos tentar transformar num dataframe e retornar
+        try:
+            df = pd.DataFrame(result)
+            return df
+        except Exception as exc:
+            raise BTGApiError(f"Falha ao converter resultado em DataFrame: {exc}") from exc
 
     raise BTGApiError("Formato de resposta desconhecido")
 
@@ -129,7 +141,7 @@ def await_report_ticket_result(token: str, ticket: str, *, attempts: int = 10,
             return check_report_ticket(token, ticket)
         except BTGApiError as err:
             if "Processando" in str(err):
-                logger.debug("Ticket %s pendente (%d/%d)", ticket, i + 1, attempts)
+                logger.debug(f"Ticket {ticket} pendente ({i+1}/{attempts})")
                 time.sleep(interval)
                 continue
             raise
@@ -185,4 +197,43 @@ def request_investors_transactions_report( token: str, query_date: dt.date, *,
         return r.json()["ticket"]
     raise BTGApiError(
         f"Erro InvestorTransactionsFileReport: {r.status_code} – {r.text}"
-    )
+    )
+    
+    
+def request_fundflow_report( token: str, start_date: dt.date,
+        end_date: dt.date, *, fund_name: str = "", date_type: str = "LIQUIDACAO", page_size: int = 100) -> str:
+    """Dispara geração do **Fund Flow** (RTA) e devolve *ticket*.
+
+    Args:
+        token: JWT obtido via :pyfunc:`luxorasap.btgapi.get_access_token`.
+        start_date,end_date: Datas do intervalo desejado.
+        fund_name: Nome do fundo conforme BTG. String vazia retorna as movimentacoes para todos os fundos.
+        date_type: Enum da API (`LIQUIDACAO`, `MOVIMENTO`, etc.).
+        page_size: Página retornada por chamada (default 100).
+
+    Returns
+    -------
+    str
+        ID do ticket a ser acompanhado em :pyfunc:`await_fundflow_ticket_result`.
+    """
+
+    body = {
+        "contract": {
+            "startDate": f"{start_date}T00:00:00Z",
+            "endDate": f"{end_date}T00:00:00Z",
+            "dateType": date_type,
+            "fundName": fund_name,
+        },
+        "pageSize": page_size,
+        "webhookEndpoint": "string",
+    }
+
+    r = requests.post(
+        _FUNDFLOW_ENDPOINT,
+        headers={"X-SecureConnect-Token": token, "Content-Type": "application/json"},
+        json=body,
+        timeout=30,
+    )
+    if r.ok:
+        return r.json()["ticket"]
+    raise BTGApiError(f"Erro FundFlow: {r.status_code} - {r.text}")

{luxorasap-0.1.1 → luxorasap-0.1.3}/src/luxorasap/ingest/cloud/__init__.py

@@ -18,10 +18,17 @@ def save_table(
     *,
     index: bool = False,
     index_name: str = "index",
-    normalize_columns: bool = False,
+    normalize_columns: bool = True,
     directory: str = "enriched/parquet",
+    override=False
 ):
     """Salva DataFrame como Parquet em ADLS (sobrescrevendo)."""
+    
+    if override == False:
+        lq = LuxorQuery()
+        if lq.table_exists(table_name):
+            return
+    
     df = prep_for_save(df, index=index, index_name=index_name, normalize=normalize_columns)
     _client.write_df(df.astype(str), f"{directory}/{table_name}.parquet")
 
@@ -34,7 +41,7 @@ def incremental_load(
     increment_column: str = "Date",
     index: bool = False,
     index_name: str = "index",
-    normalize_columns: bool = False,
+    normalize_columns: bool = True,
     directory: str = "enriched/parquet",
 ):
     """Concatena novos dados aos existentes, cortando duplicados pela data."""

luxorasap-0.1.3/src/luxorasap.egg-info/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: luxorasap
+Version: 0.1.3
+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.3/tests/test_btgapi_reports.py

@@ -0,0 +1,139 @@
+import datetime as dt, io, json, zipfile
+import pandas as pd
+import pytest
+
+from luxorasap.btgapi.reports import (
+    request_portfolio,
+    await_report_ticket_result,
+    process_zip_to_dfs,
+    check_report_ticket,
+    request_fundflow_report,
+)
+
+_TICKET_URL = "https://funds.btgpactual.com/reports/Ticket"
+_POST_URL   = "https://funds.btgpactual.com/reports/Portfolio"
+_FUNDFLOW_URL = "https://funds.btgpactual.com/reports/RTA/FundFlow"
+
+_TOKEN = "dummy-token"
+
+def test_request_portfolio_returns_ticket(requests_mock):
+    requests_mock.post(_POST_URL, json={"ticket": "ABC"})
+    tk = request_portfolio("tok", "FUND", dt.date(2025,1,1), dt.date(2025,1,31))
+    assert tk == "ABC"
+
+def test_await_ticket_inline_zip(requests_mock, monkeypatch):
+    # 1ª chamada: ainda processando   2ª: devolve ZIP binário
+    # Explicando o que requests_mock faz:
+    # 
+    requests_mock.get(_TICKET_URL, [
+        {"json": {"result": "Processando"}},
+        {"content": b"ZIP!"},
+    ])
+    monkeypatch.setattr("time.sleep", lambda *_: None)
+    out = await_report_ticket_result("tok", "ABC", attempts=2, interval=0)
+    assert out == b"ZIP!"
+
+def test_await_ticket_via_urldownload(requests_mock, monkeypatch):
+    dl_url = "https://download/file.zip"
+    # 1ª chamada ao ticket devolve JSON com UrlDownload
+    requests_mock.get(_TICKET_URL, json={"result": json.dumps({"UrlDownload": dl_url})})
+    requests_mock.get(dl_url, content=b"ZIP2", headers={"Content-Type": "application/zip"})
+    monkeypatch.setattr("time.sleep", lambda *_: None)
+    out = await_report_ticket_result("tok", "XYZ", attempts=1)
+    assert out == b"ZIP2"
+
+
+def test_process_zip_to_dfs():
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        df = pd.DataFrame({"x": [1]})
+        zf.writestr("data.csv", df.to_csv(index=False))
+    dfs = process_zip_to_dfs(buf.getvalue())
+    assert dfs["data.csv"].iloc[0, 0] == 1
+    
+    
+def test_process_zip_latin1_csv():
+    import io, zipfile, pandas as pd
+    from luxorasap.btgapi.reports import process_zip_to_dfs
+
+    df_src = pd.DataFrame({"nome": ["ação", "æøå"]})
+    csv_latin1 = df_src.to_csv(index=False, encoding="latin1")
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        zf.writestr("dados.csv", csv_latin1)
+
+    dfs = process_zip_to_dfs(buf.getvalue())
+    assert dfs["dados.csv"].equals(df_src)
+    
+
+def test_request_fundflow_report_success(requests_mock):
+    """POST devolvendo ticket e corpo montado corretamente."""
+    start, end = dt.date(2025, 5, 4), dt.date(2025, 6, 4)
+    fund_name   = "luxor lipizzaner fia"
+    expected_id = "TCK-123"
+
+    # valida corpo enviado
+    def _match(request):
+        payload = request.json()
+        c = payload["contract"]
+        assert c["startDate"] == f"{start}T00:00:00Z"
+        assert c["endDate"]   == f"{end}T00:00:00Z"
+        assert c["fundName"]  == fund_name
+        assert c["dateType"]  == "LIQUIDACAO"
+        return True
+
+    requests_mock.post(
+        _FUNDFLOW_URL,
+        additional_matcher=_match,
+        json={"ticket": expected_id},
+        status_code=200,
+    )
+
+    ticket = request_fundflow_report(
+        _TOKEN, start, end, fund_name=fund_name
+    )
+    assert ticket == expected_id
+    
+
+def test_check_report_ticket_returns_dataframe(requests_mock):
+    """GET devolvendo JSON-list deve virar DataFrame."""
+    ticket_id   = "TCK-LIST"
+    sample_rows = [
+        {"customerName": "A", "valueTotal": 1_000},
+        {"customerName": "B", "valueTotal": 2_000},
+    ]
+
+    # qualquer query param é aceito; podemos validar se quiser via matcher
+    requests_mock.get(
+        _TICKET_URL,
+        json={"result": sample_rows},
+        status_code=200,
+    )
+
+    df = check_report_ticket(_TOKEN, ticket_id)
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert set(df.columns) == {"customerName", "valueTotal"}
+    
+    
+def test_await_report_ticket_polls_until_ready(requests_mock, monkeypatch):
+    """Primeira chamada ‘Processando’ → segunda retorna lista."""
+    ticket_id   = "TCK-POLL"
+    ready_rows  = [{"x": 1}]
+
+    # sequencia de respostas: processamento → pronto
+    requests_mock.get(
+        _TICKET_URL,
+        [
+            {"json": {"result": "Processando"}, "status_code": 200},
+            {"json": {"result": ready_rows},    "status_code": 200},
+        ],
+    )
+
+    # evita atraso real de sleep
+    monkeypatch.setattr("luxorasap.btgapi.reports.time.sleep", lambda *_: None)
+
+    df = await_report_ticket_result(_TOKEN, ticket_id, attempts=2, interval=0)
+    assert isinstance(df, pd.DataFrame)
+    assert df.iloc[0, 0] == 1

luxorasap-0.1.1/PKG-INFO

@@ -1,80 +0,0 @@
-Metadata-Version: 2.4
-Name: luxorasap
-Version: 0.1.1
-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"
-
-# LuxorASAP
-
-**LuxorASAP** é o pacote-guarda-chuva que concentra as ferramentas internas de dados da Luxor Group:  
-consulta estruturada ao data lake, cargas padronizadas para ADLS, wrappers de API, utilitários e muito mais.
-
-[![PyPI](https://img.shields.io/pypi/v/luxorasap.svg)](https://pypi.org/project/luxorasap/)
-![Python](https://img.shields.io/pypi/pyversions/luxorasap)
-
----
-
-## Instalação
-
-```bash
-# pacote base
-pip install luxorasap
-
-# com o submódulo datareader
-pip install "luxorasap[datareader]"
-```
-## Uso rápido
-```python
-from luxorasap.datareader import LuxorQuery
-
-lq = LuxorQuery(blob_directory="enriched/parquet")
-prices = lq.get_prices("aapl us equity", "2024-01-01", "2024-12-31")
-print(prices.head())
-```
-## Submódulos
-| Módulo                 | Descrição rápida                         | Extras                                |
-| ---------------------- | ---------------------------------------- | ------------------------------------- |
-| `luxorasap.datareader` | Leitura de tabelas e séries no data lake | `pip install "luxorasap[datareader]"` |
-| `luxorasap.ingest`     | Funções de carga padronizada para ADLS   | `"luxorasap[ingest]"`                 |
-| `luxorasap.btgapi`     | Wrapper REST para dados BTG              | `"luxorasap[btgapi]"`                 |
-
-© Luxor Group – uso interno. Todos os direitos reservados.

luxorasap-0.1.1/README.md

@@ -1,35 +0,0 @@
-# LuxorASAP
-
-**LuxorASAP** é o pacote-guarda-chuva que concentra as ferramentas internas de dados da Luxor Group:  
-consulta estruturada ao data lake, cargas padronizadas para ADLS, wrappers de API, utilitários e muito mais.
-
-[![PyPI](https://img.shields.io/pypi/v/luxorasap.svg)](https://pypi.org/project/luxorasap/)
-![Python](https://img.shields.io/pypi/pyversions/luxorasap)
-
----
-
-## Instalação
-
-```bash
-# pacote base
-pip install luxorasap
-
-# com o submódulo datareader
-pip install "luxorasap[datareader]"
-```
-## Uso rápido
-```python
-from luxorasap.datareader import LuxorQuery
-
-lq = LuxorQuery(blob_directory="enriched/parquet")
-prices = lq.get_prices("aapl us equity", "2024-01-01", "2024-12-31")
-print(prices.head())
-```
-## Submódulos
-| Módulo                 | Descrição rápida                         | Extras                                |
-| ---------------------- | ---------------------------------------- | ------------------------------------- |
-| `luxorasap.datareader` | Leitura de tabelas e séries no data lake | `pip install "luxorasap[datareader]"` |
-| `luxorasap.ingest`     | Funções de carga padronizada para ADLS   | `"luxorasap[ingest]"`                 |
-| `luxorasap.btgapi`     | Wrapper REST para dados BTG              | `"luxorasap[btgapi]"`                 |
-
-© Luxor Group – uso interno. Todos os direitos reservados.

luxorasap-0.1.1/src/luxorasap.egg-info/PKG-INFO

@@ -1,80 +0,0 @@
-Metadata-Version: 2.4
-Name: luxorasap
-Version: 0.1.1
-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"
-
-# LuxorASAP
-
-**LuxorASAP** é o pacote-guarda-chuva que concentra as ferramentas internas de dados da Luxor Group:  
-consulta estruturada ao data lake, cargas padronizadas para ADLS, wrappers de API, utilitários e muito mais.
-
-[![PyPI](https://img.shields.io/pypi/v/luxorasap.svg)](https://pypi.org/project/luxorasap/)
-![Python](https://img.shields.io/pypi/pyversions/luxorasap)
-
----
-
-## Instalação
-
-```bash
-# pacote base
-pip install luxorasap
-
-# com o submódulo datareader
-pip install "luxorasap[datareader]"
-```
-## Uso rápido
-```python
-from luxorasap.datareader import LuxorQuery
-
-lq = LuxorQuery(blob_directory="enriched/parquet")
-prices = lq.get_prices("aapl us equity", "2024-01-01", "2024-12-31")
-print(prices.head())
-```
-## Submódulos
-| Módulo                 | Descrição rápida                         | Extras                                |
-| ---------------------- | ---------------------------------------- | ------------------------------------- |
-| `luxorasap.datareader` | Leitura de tabelas e séries no data lake | `pip install "luxorasap[datareader]"` |
-| `luxorasap.ingest`     | Funções de carga padronizada para ADLS   | `"luxorasap[ingest]"`                 |
-| `luxorasap.btgapi`     | Wrapper REST para dados BTG              | `"luxorasap[btgapi]"`                 |
-
-© Luxor Group – uso interno. Todos os direitos reservados.

luxorasap-0.1.1/tests/test_btgapi_reports.py

@@ -1,62 +0,0 @@
-import datetime as dt, io, json, zipfile
-import pandas as pd
-import pytest
-
-from luxorasap.btgapi.reports import (
-    request_portfolio,
-    await_report_ticket_result,
-    process_zip_to_dfs,
-)
-
-_TICKET_URL = "https://funds.btgpactual.com/reports/Ticket"
-_POST_URL   = "https://funds.btgpactual.com/reports/Portfolio"
-
-def test_request_portfolio_returns_ticket(requests_mock):
-    requests_mock.post(_POST_URL, json={"ticket": "ABC"})
-    tk = request_portfolio("tok", "FUND", dt.date(2025,1,1), dt.date(2025,1,31))
-    assert tk == "ABC"
-
-def test_await_ticket_inline_zip(requests_mock, monkeypatch):
-    # 1ª chamada: ainda processando   2ª: devolve ZIP binário
-    # Explicando o que requests_mock faz:
-    # 
-    requests_mock.get(_TICKET_URL, [
-        {"json": {"result": "Processando"}},
-        {"content": b"ZIP!"},
-    ])
-    monkeypatch.setattr("time.sleep", lambda *_: None)
-    out = await_report_ticket_result("tok", "ABC", attempts=2, interval=0)
-    assert out == b"ZIP!"
-
-def test_await_ticket_via_urldownload(requests_mock, monkeypatch):
-    dl_url = "https://download/file.zip"
-    # 1ª chamada ao ticket devolve JSON com UrlDownload
-    requests_mock.get(_TICKET_URL, json={"result": json.dumps({"UrlDownload": dl_url})})
-    requests_mock.get(dl_url, content=b"ZIP2", headers={"Content-Type": "application/zip"})
-    monkeypatch.setattr("time.sleep", lambda *_: None)
-    out = await_report_ticket_result("tok", "XYZ", attempts=1)
-    assert out == b"ZIP2"
-
-
-def test_process_zip_to_dfs():
-    buf = io.BytesIO()
-    with zipfile.ZipFile(buf, "w") as zf:
-        df = pd.DataFrame({"x": [1]})
-        zf.writestr("data.csv", df.to_csv(index=False))
-    dfs = process_zip_to_dfs(buf.getvalue())
-    assert dfs["data.csv"].iloc[0, 0] == 1
-    
-    
-def test_process_zip_latin1_csv():
-    import io, zipfile, pandas as pd
-    from luxorasap.btgapi.reports import process_zip_to_dfs
-
-    df_src = pd.DataFrame({"nome": ["ação", "æøå"]})
-    csv_latin1 = df_src.to_csv(index=False, encoding="latin1")
-
-    buf = io.BytesIO()
-    with zipfile.ZipFile(buf, "w") as zf:
-        zf.writestr("dados.csv", csv_latin1)
-
-    dfs = process_zip_to_dfs(buf.getvalue())
-    assert dfs["dados.csv"].equals(df_src)