chore: enable pre-release process (#285)

- Added comments in publish.yml to clarify pre-release version detection by PyPI.
- Enhanced Makefile with a new pre-release target to streamline the pre-release process.
- Modified pyproject.toml to support pre-release version parsing and serialization.

Author: cofin

.github/workflows/publish.yml

@@ -191,6 +191,8 @@ jobs:
 
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        # Pre-release versions (alpha, beta, rc) are automatically detected by PyPI
+        # based on PEP 440 version format (e.g., 0.33.0a1, 0.33.0b1, 0.33.0rc1)
         with:
           packages-dir: dist/
           verbose: true

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.14.8"
+    rev: "v0.14.9"
     hooks:
       - id: ruff
         args: ["--fix"]

Makefile

@@ -117,10 +117,35 @@ release:                                           ## Bump version and create re
 	@make docs
 	@make clean
 	@make build
-	@uv lock --upgrade-package sqlspec >/dev/null 2>&1
 	@uv run bump-my-version bump $(bump)
+	@uv lock --upgrade-package sqlspec >/dev/null 2>&1
 	@echo "${OK} Release complete 🎉"
 
+.PHONY: pre-release
+pre-release:                                       ## Start a pre-release: make pre-release version=0.33.0-alpha.1
+	@if [ -z "$(version)" ]; then \
+		echo "${ERROR} Usage: make pre-release version=X.Y.Z-alpha.N"; \
+		echo ""; \
+		echo "Pre-release workflow:"; \
+		echo "  1. Start alpha:     make pre-release version=0.33.0-alpha.1"; \
+		echo "  2. Next alpha:      make pre-release version=0.33.0-alpha.2"; \
+		echo "  3. Move to beta:    make pre-release version=0.33.0-beta.1"; \
+		echo "  4. Move to rc:      make pre-release version=0.33.0-rc.1"; \
+		echo "  5. Final release:   make release bump=patch (from rc) OR bump=minor (from stable)"; \
+		exit 1; \
+	fi
+	@echo "${INFO} Preparing pre-release $(version)... 🧪"
+	@make clean
+	@make build
+	@uv run bump-my-version bump --new-version $(version) pre
+	@uv lock --upgrade-package sqlspec >/dev/null 2>&1
+	@echo "${OK} Pre-release $(version) complete 🧪"
+	@echo ""
+	@echo "${INFO} Next steps:"
+	@echo "  1. Push: git push origin HEAD"
+	@echo "  2. Create a GitHub pre-release: gh release create v$(version) --prerelease --generate-notes --title 'v$(version)'"
+	@echo "  3. This will publish to PyPI with pre-release tags"
+
 # =============================================================================
 # Cleaning and Maintenance
 # =============================================================================

pyproject.toml

@@ -216,16 +216,30 @@ current_version = "0.32.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"
-parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+parse = """(?x)
+    (?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)
+    (-(?P<pre>alpha|beta|rc)\\.(?P<pre_n>\\d+))?
+"""
 regex = false
 replace = "{new_version}"
 search = "{current_version}"
-serialize = ["{major}.{minor}.{patch}"]
+serialize = [
+    "{major}.{minor}.{patch}",
+    "{major}.{minor}.{patch}-{pre}.{pre_n}",
+]
 sign_tags = false
 tag = false
 tag_message = "chore(release): v{new_version}"
 tag_name = "v{new_version}"
 
+[tool.bumpversion.parts.pre]
+optional_value = "stable"
+first_value = "stable"
+values = ["alpha", "beta", "rc", "stable"]
+
+[tool.bumpversion.parts.pre_n]
+first_value = "1"
+
 [[tool.bumpversion.files]]
 filename = "pyproject.toml"
 replace = 'version = "{new_version}"'

sqlspec/extensions/fastapi/extension.py

@@ -15,6 +15,16 @@
     from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
     from sqlspec.extensions.fastapi.providers import DependencyDefaults, FilterConfig
 
+    # Type aliases for static analysis - IDEs see the real types
+    _AsyncSession = AsyncDriverAdapterBase
+    _SyncSession = SyncDriverAdapterBase
+    _Session = AsyncDriverAdapterBase | SyncDriverAdapterBase
+else:
+    # Runtime fallback - FastAPI sees Any (avoids NameError)
+    _AsyncSession = Any
+    _SyncSession = Any
+    _Session = Any
+
 __all__ = ("SQLSpecPlugin",)
 
 
@@ -122,7 +132,7 @@ async def typed_query2(db = Depends(db_ext.provide_session(AsyncpgConfig))):
         # Extract string key if provided, ignore config types/instances (used only for type narrowing)
         session_key = key if isinstance(key, str) or key is None else None
 
-        def dependency(request: Request) -> "AsyncDriverAdapterBase | SyncDriverAdapterBase":
+        def dependency(request: Request) -> _Session:
             return self.get_session(request, session_key)  # type: ignore[no-any-return]
 
         return dependency
@@ -151,7 +161,7 @@ async def get_products(db = Depends(db_ext.provide_async_session("products_db"))
                 return await db.execute("SELECT * FROM products")
         """
 
-        def dependency(request: Request) -> "AsyncDriverAdapterBase":
+        def dependency(request: Request) -> _AsyncSession:
             return self.get_session(request, key)  # type: ignore[no-any-return]
 
         return dependency
@@ -175,7 +185,7 @@ def get_users(db = Depends(db_ext.provide_sync_session())):
                 return db.execute("SELECT * FROM users")
         """
 
-        def dependency(request: Request) -> "SyncDriverAdapterBase":
+        def dependency(request: Request) -> _SyncSession:
             return self.get_session(request, key)  # type: ignore[no-any-return]
 
         return dependency