Metadata-Version: 2.4
Name: lib-bigquery-connection-g
Version: 1.0.0
Summary: Cliente utilitário para conexão e consultas ao Google BigQuery
Author-email: SEU NOME <seu-email@exemplo.com>
License: MIT
Project-URL: Homepage, https://github.com/SEU_USUARIO/lib-bigquery-connection-g
Project-URL: Repository, https://github.com/SEU_USUARIO/lib-bigquery-connection-g
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-cloud-bigquery>=3.11.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Requires-Dist: db-dtypes>=1.0.0; extra == "pandas"
Dynamic: license-file

# lib-bigquery-connection-g

Cliente utilitário para conexão e consultas ao Google BigQuery.

> Nome de instalação (`pip install lib-bigquery-connection-g`) é diferente do nome de
> import (`from bq_connector import BQConnector`) — o módulo interno continua se chamando
> `bq_connector`, só o nome de publicação no PyPI mudou.

## Instalação local (dev)

```bash
pip install -e ".[pandas]"
```

## Versionamento

A versão do pacote é gerada automaticamente a partir da tag do Git (via `setuptools_scm`) —
não precisa editar nenhum arquivo pra bumpar versão. Basta criar uma tag no formato `vX.Y.Z`:

```bash
git tag v1.2.0
git push origin v1.2.0
```

O pipeline do GitLab vai gerar o wheel como `lib_bigquery_connection_g-1.2.0-py3-none-any.whl`.
Sem tag, a versão fica algo como `0.1.dev3+g1a2b3c4` (indicando commits após a última tag).

## Build do pacote

```bash
pip install build
python -m build
```

Isso gera `dist/lib_bigquery_connection_g-X.Y.Z-py3-none-any.whl` e o `.tar.gz` correspondente
(com a versão vindo da tag do git mais recente).

## Publicar no PyPI (público)

O pipeline agora tem duas etapas de publicação:

1. **`publish-test`** (automática, roda em qualquer tag) — sobe o pacote pro **TestPyPI**
   (`test.pypi.org`), um índice separado só pra validar que o build/metadata estão OK.
2. **`publish`** (manual — você precisa clicar em "play" no pipeline do GitLab) — só depois
   de conferir que a instalação a partir do TestPyPI funciona, você aciona esse job pra
   publicar de verdade no PyPI. Isso evita "queimar" uma tag/versão no índice real por causa
   de um erro de metadata que só aparece no upload.

Testando a instalação a partir do TestPyPI (o `--extra-index-url` é necessário porque
dependências como `google-cloud-bigquery` não existem no TestPyPI):
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "lib-bigquery-connection-g[pandas]"
```

Se estiver tudo certo, vai no pipeline do GitLab e clica em "play" no job `publish`
pra liberar a versão de verdade no PyPI.

### Configuração necessária no GitLab (Settings > CI/CD > Variables)

| Variável | De onde vem |
|---|---|
| `TEST_PYPI_API_TOKEN` | Conta separada em test.pypi.org → https://test.pypi.org/manage/account/token/ |
| `PYPI_API_TOKEN` | Conta em pypi.org → https://pypi.org/manage/account/token/ |

Marque as duas como **Protected** e **Masked**.

## Instalar (uma vez publicado)

```bash
pip install "lib-bigquery-connection-g[pandas]"
```

## Uso

```python
from bq_connector import BQConnector

bq = BQConnector(project_id="minha-empresa-prod")

# Query simples
rows = bq.query("SELECT * FROM `dataset.tabela` LIMIT 10")

# Query para DataFrame
df = bq.query_to_dataframe("SELECT * FROM `dataset.tabela` LIMIT 10")

# Query parametrizada
df = bq.query_to_dataframe(
    "SELECT * FROM `dataset.tabela` WHERE status = @status",
    params={"status": "ativo"},
)

# Dry run (estimar custo antes de rodar)
bytes_processados = bq.dry_run("SELECT * FROM `dataset.tabela_grande`")

# Insert de linhas
bq.insert_rows("dataset", "tabela", [{"coluna1": "valor1"}])

# Load de DataFrame inteiro
bq.load_dataframe(df, "dataset", "tabela", write_disposition="WRITE_APPEND")

# Metadados
bq.list_datasets()
bq.list_tables("dataset")
bq.get_table_schema("dataset", "tabela")
bq.table_exists("dataset", "tabela")
```
