Release 0.0.7: production-readiness hardening

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.6
+current_version = 0.0.7
 commit = True
 tag = True
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)

.github/workflows/workflow.yaml

@@ -21,6 +21,58 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  lint:
+    name: Lint (flake8)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Install dependencies
+        run: uv pip install --system flake8
+        # Bound so a stuck index resolve can't hang the job.
+        timeout-minutes: 5
+
+      - name: Run flake8
+        # flake8 reads its [flake8] config from tox.ini.
+        run: flake8 src tests
+        timeout-minutes: 5
+
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    # Advisory for now: the codebase has a backlog of strict-mode errors to
+    # burn down. Surface them on every run, but don't block merges yet.
+    # Flip continue-on-error to false once `mypy src/timescaledb` is clean.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Install package and type deps
+        # Installs the project (so mypy resolves its deps/stubs) plus mypy.
+        # [tool.mypy] strict = true lives in pyproject.toml.
+        run: uv pip install --system mypy .
+        timeout-minutes: 5
+
+      - name: Run mypy
+        run: mypy src/timescaledb
+        timeout-minutes: 5
+
   tests:
     name: Python ${{ matrix.python-version }}
     runs-on: ubuntu-24.04
@@ -94,7 +146,6 @@ jobs:
         run: |
           coverage combine
           coverage report --fail-under=85
-        continue-on-error: true
 
       - name: Upload HTML report
         if: ${{ failure() }}

CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.7] - 2026-06-25
+
+Production-readiness hardening release.
+
+### Added
+
+- SQLAlchemy dialect support, including psycopg 3.
+- `py.typed` marker so downstream consumers pick up the package's type hints.
+- `LICENSE` and `CONTRIBUTING.md` files.
+- mypy type checking and flake8 linting jobs in CI.
+- Python 3.14 to the CI test matrix.
+- `get_defaults()` helper to inspect the package's default settings.
+- Database-free unit tests for the engine and query builders.
+
+### Changed
+
+- Moved `fastapi` and `uvicorn` out of the core dependencies into optional extras.
+- Bumped GitHub Actions off the deprecated Node 20 runtime and added job timeouts.
+- Pinned `setup-uv` to a fixed version.
+- Cleaned up the requirements compile script (dropped a vestigial `--constraint -`).
+- Coverage now fails the build below 85% instead of merely warning.
+
+### Fixed
+
+- Repaired broken `__all__` exports.
+- Hardened sync error handling so failures roll back the session and propagate
+  instead of being silently swallowed.
+
+## [0.0.6] - 2026-06-25
+
+### Changed
+
+- Version bump release (0.0.5 → 0.0.6).
+
+## [0.0.5] - 2026-06-25
+
+### Added
+
+- Hypercore columnstore support.
+- Continuous aggregate support.
+- `samples/`: 10 runnable, Docker-tested TimescaleDB sample projects.
+
+## [0.0.4] - 2025-03-20
+
+### Changed
+
+- Reworked retention handling.
+- Dropped Python 3.10 support.
+
+### Fixed
+
+- Updated and expanded the test suite.
+
+## [0.0.3] - 2025-03-20
+
+### Added
+
+- Compression policies.
+
+### Changed
+
+- Updates to hypertable creation, compression, and retention.
+- Reorganized the codebase into focused modules.
+- Improved test coverage and updated the README example.
+
+## [0.0.2] - 2025-02-19
+
+### Changed
+
+- Updated dependencies.
+- Updated the sample project.
+
+## [0.0.1] - 2025-02-17
+
+### Added
+
+- Initial release: the TimescaleDB model and base package layout.

CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing
+
+Thanks for your interest in improving `timescaledb`. This guide covers setting up
+a development environment, running the tests and checks, and the release process.
+
+By contributing you agree that your work is licensed under the project's
+[MIT License](./LICENSE).
+
+## Requirements
+
+- Python 3.11, 3.12, 3.13, or 3.14
+- **Docker** running locally (Docker Desktop, Colima, OrbStack, …). The test
+  suite starts a real TimescaleDB container via
+  [`testcontainers`](https://testcontainers.com/), so a working Docker daemon is
+  required to run the tests.
+
+## Development environment
+
+Either [`uv`](https://docs.astral.sh/uv/) or a plain `venv` works. The CI uses
+`uv`.
+
+### Using uv
+
+```bash
+uv venv
+source .venv/bin/activate              # Windows: .venv\Scripts\activate
+
+# Install the package in editable mode
+uv pip install -e .
+
+# Install the dev/test tooling
+uv pip install -r requirements.dev.txt
+```
+
+### Using venv + pip
+
+```bash
+python -m venv .venv
+source .venv/bin/activate              # Windows: .venv\Scripts\activate
+
+pip install -e .
+pip install -r requirements.dev.txt
+```
+
+`requirements.dev.txt` pulls in `tox`, `coverage`, `pytest`, `bump2version`,
+`pre_commit`, and `testcontainers[postgres]`.
+
+## Running the test suite
+
+The tests need **no manual database setup** — `testcontainers` starts a
+throwaway TimescaleDB container and tears it down afterwards. Make sure Docker is
+running first.
+
+Run the tests directly with `pytest`:
+
+```bash
+python -m pytest tests
+```
+
+Or run them across an interpreter with `tox` (the locked dependency sets for
+each Python version live in `tests/requirements/`):
+
+```bash
+# all configured interpreters (py311–py314)
+tox
+
+# a single interpreter, e.g. 3.12
+tox run -f py312
+```
+
+The first run is slow because Docker pulls the TimescaleDB image; subsequent runs
+reuse the cached image.
+
+### Coverage
+
+`tox` runs the suite under `coverage`. To combine results and view a report
+(CI fails under 85%):
+
+```bash
+coverage combine
+coverage report
+```
+
+### Sample projects
+
+The [`samples/`](./samples/) directory has its own fully-tested example projects
+with their own dependencies. See [`samples/README.md`](./samples/README.md) for
+how to run those suites.
+
+### Long-lived database (optional)
+
+For manual experimentation against a persistent database instead of throwaway
+containers, a `compose.yaml` is provided:
+
+```bash
+docker compose up -d
+# DATABASE_URL=postgresql+psycopg://timescaledb:timescaledb@localhost:5432/timescaledb
+docker compose down -v                 # stop + wipe when finished
+```
+
+## Lint and type checks
+
+Both run in CI and should pass before opening a PR.
+
+```bash
+# flake8 (config lives in the [flake8] section of tox.ini)
+flake8 src tests
+
+# mypy (strict mode, configured in [tool.mypy] in pyproject.toml)
+mypy src/timescaledb
+```
+
+Imports are sorted with `isort` (`force_single_line`, black profile) — see the
+`[tool.isort]` config in `pyproject.toml`. A `pre-commit` config can be installed
+with `pre-commit install` if you use it.
+
+## Pull request guidelines
+
+- Keep PRs focused on a single change.
+- Add or update tests for any behavior change; new helpers should ship with
+  coverage (CI enforces an 85% floor).
+- Make sure `flake8`, `mypy`, and the test suite pass locally.
+- Update the `README.md` and/or `samples/` when you add or change public API.
+- Do **not** bump the version in your PR — releases are cut separately (see
+  below).
+
+## Release process
+
+Releases are published to [PyPI](https://pypi.org/project/timescaledb/) by CI
+when a tag is pushed. Versioning is `MAJOR.MINOR.PATCH` and driven by
+[`bump2version`](https://github.com/c4urself/bump2version) (config in
+`.bumpversion.cfg`, which updates `pyproject.toml` and
+`src/timescaledb/__init__.py`).
+
+1. On `main`, bump the version. `bump2version` is configured to create the
+   commit **and** the git tag automatically (`commit = True`, `tag = True`):
+
+   ```bash
+   bump2version patch     # or: minor / major
+   ```
+
+2. Push the commit and the tag:
+
+   ```bash
+   git push origin main --follow-tags
+   ```
+
+3. The `Release` workflow (`.github/workflows/workflow.yaml`) runs lint, type
+   checks, and the full test matrix. When the pushed ref is a tag and everything
+   passes, the `release` job builds the package with `uv build` and publishes it
+   to PyPI via trusted publishing (OIDC) using
+   `pypa/gh-action-pypi-publish`.
+
+No PyPI token is needed locally — publishing happens entirely in CI.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Justin Mitchel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.