Metadata-Version: 2.4
Name: altertable-flightsql
Version: 0.3.0
Summary: Python client library for Altertable
Author-email: Your Name <your.email@example.com>
Maintainer-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/altertable-flightsql
Project-URL: Documentation, https://github.com/yourusername/altertable-flightsql#readme
Project-URL: Repository, https://github.com/yourusername/altertable-flightsql
Project-URL: Bug Tracker, https://github.com/yourusername/altertable-flightsql/issues
Keywords: altertable,sql,database,analytics,arrow,flight
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf>=5.26.0
Requires-Dist: pyarrow>=15.0.0
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.73.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: ruff>=0.0.270; extra == "dev"
Requires-Dist: testcontainers>=4.0.0; extra == "dev"
Requires-Dist: pandas>=1.3.0; extra == "dev"
Dynamic: license-file

# altertable-flightsql

Python client library for Altertable.

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## Installation

```bash
pip install altertable-flightsql
```

## Quick Start

```python
from altertable_flightsql import Client

# Connect to Altertable
with Client(username="your_username", password="your_password") as client:
    # Execute a query
    reader = client.query("SELECT * FROM users WHERE age > 18")

    # Process results
    for batch in reader:
        df = batch.data.to_pandas()
        print(df)
```

### Connect to specific catalog/schema

```python
# Connect to custom host/port
client = Client(
    username="admin",
    password="secret",
    catalog="my_catalog",
    schema="my_schema"
)
```

### Queries and Updates

```python
# Execute SELECT query
reader = client.query("SELECT * FROM users")
for batch in reader:
    print(batch.data.to_pandas())

# Execute INSERT/UPDATE/DELETE
rows_affected = client.execute("INSERT INTO users (name) VALUES ('Alice')")
print(f"Affected {rows_affected} rows")
```

### Prepared Statements

```python
# Prepare once, execute multiple times
with client.prepare("SELECT * FROM users WHERE id = $id") as stmt:
    result = stmt.query(parameters={"id": 1}))
    for batch in result:
        print(batch.data.to_pandas())
```

### Transactions

```python
with client.begin_transaction():
    client.execute("INSERT INTO users ...")
    client.execute("UPDATE accounts ...")
```

### Metadata Queries

```python
# Get catalogs, schemas, tables
catalogs = client.get_catalogs()
schemas = client.get_schemas(catalog="my_db")
tables = client.get_tables(catalog="my_db", schema_pattern="public")
```

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/altertable-ai/altertable-flightsql-python.git
cd altertable-flightsql-python

# Install with dev dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest                           # Run tests
```

### Code Quality

```bash
make lint                        # Run all linters (isort, black, ruff, mypy)
```

### Compiling Protocol Definitions

If you modify the `.proto` files, you need to recompile them:

```bash
make gen                         # Compile protobuf definitions
```

**Important:** The CI will fail if generated files are out of sync with the proto definitions. Always run `make gen` and commit the generated files after modifying `.proto` files.

## Examples

See the `examples/` directory for complete examples:

```bash
# High-level client examples
python examples/client_usage.py
```

## Testing

This package includes comprehensive integration tests that validate functionality against a real Altertable service.

### Running Tests

**Using testcontainers (local development):**

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run all tests
# Having the ghcr.io/altertable-ai/altertable-mock docker image locally will speed things up.
pytest tests/
```

The mock service container is forced to run as `linux/amd64` to keep parity with CI
and to work reliably on Apple Silicon machines (Docker Desktop will handle
emulation automatically).

**Using an existing service (CI/production):**

```bash
# Set environment variables
export ALTERTABLE_HOST=localhost
export ALTERTABLE_PORT=15002
export ALTERTABLE_USERNAME=altertable-test
export ALTERTABLE_PASSWORD=lk_test

# Run tests
pytest tests/
```

The test suite automatically detects whether to use testcontainers or an existing service based on environment variables. If `ALTERTABLE_HOST` and `ALTERTABLE_PORT` are set, tests will connect to that service. Otherwise, they'll start a Docker container with `altertable.ai/altertable-mock`.

## Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. If you modified `.proto` files, run `make gen`
5. Run code quality checks: `make lint` and `pytest`
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

### Development Guidelines

- Follow PEP 8 style (enforced by Black, line length: 100)
- Add tests for new features
- Include docstrings (Google style)
- Update documentation as needed
- Run `make gen` and commit generated files when modifying `.proto` files
- Run `make lint` before committing to ensure code quality

## Architecture

```
altertable-flightsql/
├── src/altertable_flightsql/
│   ├── __init__.py              # Package exports
│   ├── client.py                # Main Client class
│   └── generated/               # Internal protocol definitions
├── tests/                       # Test suite
└── examples/                    # Usage examples
```

## License

MIT License - See [LICENSE](LICENSE) file for details.

Built on Apache Arrow Flight SQL protocol.

## Resources

- [Altertable](https://altertable.ai)
- [PyArrow Documentation](https://arrow.apache.org/docs/python/)

## Acknowledgments

Built on Apache Arrow Flight SQL protocol.
