Metadata-Version: 2.4
Name: sqlean-stubs
Version: 0.0.2
Summary: Type hints for sqlean.py (sqlite3 + extensions)
Home-page: https://github.com/nalgeon/sqlean.py
Author: Type Hints Contributors
Author-email: Kracekumar <me@kracekumar.com>
License: Zlib
Project-URL: Repository, https://github.com/kracekumar/sqlean-stubs
Project-URL: Documentation, https://github.com/kracekumar/sqlean-stubs
Project-URL: Bug Tracker, https://github.com/kracekumar/sqlean-stubs/issues
Keywords: sqlite,sqlean,type-hints,stubs,type-checking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: zlib/libpng License
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ty>=0.0.7; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Requires-Dist: sqlean.py>=3.50; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# sqlean-stubs

Type hints for [sqlean.py](https://github.com/nalgeon/sqlean.py) - Python's sqlite3 + extensions.

## Installation

```bash
pip install sqlean-stubs
```

or with uv:

```bash
uv add sqlean-stubs
```

## Usage

Type hints enable IDE autocomplete and type checking for sqlean code:

```python
import sqlean

conn: sqlean.Connection = sqlean.connect(":memory:")
cursor = conn.cursor()

# Type hints work with parameters
cursor.execute("SELECT * FROM users WHERE id = ?", (1,))

# fetchone() returns Optional[Any]
row = cursor.fetchone()
if row is not None:
    print(row[0])  # Type-safe indexing

# User-defined functions
def double(x: int) -> int:
    return x * 2

conn.create_function("double", 1, double)
conn.close()
```

**Benefits:**
- IDE autocomplete and navigation
- Catch type errors before runtime with mypy or ty
- Better code documentation and refactoring safety

## Features

- Complete type hints for Connection, Cursor, and Row objects
- Support for custom factories and row factories
- Type hints for user-defined functions and aggregates
- Callbacks support (authorizer, progress handler, trace callback, busy handler)
- Window function support
- Extensions management API
- Compatible with mypy, ty, pyright, and other type checkers

## Requirements

- Python 3.9 or later
- pip, uv, or pipx for installation

---

## Contributing

### Development Setup

```bash
git clone https://github.com/nalgeon/sqlean-stubs.git
cd sqlean-stubs
uv sync
```

### Running Tests

```bash
# Run all tests
uv run pytest tests/

# Linting
uv run ruff check .

# Type checking
uv run mypy tests/test_mypy.py
uv run ty check

# Test multiple Python versions (3.9-3.14)
uv run tox
```

### Project Structure

- `sqlean/dbapi2.pyi` - Main DB-API 2.0 interface
- `sqlean/extensions.pyi` - Extension management API
- `sqlean/py.typed` - PEP 561 marker file
- `tests/test_types.py` - Runtime tests
- `tests/test_mypy.py` - Type checking tests

### Adding Type Hints

1. Update the `.pyi` stub file
2. Add runtime test in `tests/test_types.py`
3. Add type checking test in `tests/test_mypy.py`
4. Run `pytest tests/`, `mypy tests/test_mypy.py`, and `ty check`

### Code Style

- Follow PEP 484 for type hints
- Use `Optional[X]` instead of `X | None` (Python 3.9 compatibility)
- Use `Literal` types for constrained values
- Include docstrings for complex types

### Before Submitting

```bash
uv run ruff check .
uv run pytest tests/ -v
uv run mypy tests/test_mypy.py
uv run ty check
```

## License

Zlib (same as sqlean.py)
