pyproject.toml

[project]
authors = [{ name = "Cody Fincher", email = "cody@litestar.dev" }]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Programming Language :: Python :: 3 :: Only",
  "Typing :: Typed",
]
dependencies = [
  "typing-extensions",
  "sqlglot>=30.0.0",
  "mypy-extensions",
  "rich-click>=1.9.0",
  "tomli>=2.0.0; python_version < '3.11'",
]
description = "SQL Experiments in Python"
license = "MIT"
maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
name = "sqlspec"
readme = "README.md"
requires-python = ">=3.10, <4.0"
version = "0.43.0"

[project.urls]
Discord = "https://discord.gg/litestar"
Issue = "https://github.com/litestar-org/sqlspec/issues/"
Source = "https://github.com/litestar-org/sqlspec"

[project.optional-dependencies]
adbc = ["adbc_driver_manager", "pyarrow"]
adk = ["google-adk"]
aioodbc = ["aioodbc"]
aiosqlite = ["aiosqlite"]
alloydb = ["google-cloud-alloydb-connector"]
asyncmy = ["asyncmy"]
asyncpg = ["asyncpg"]
attrs = ["attrs", "cattrs"]
bigquery = ["google-cloud-bigquery", "google-cloud-storage"]
cloud-sql = ["cloud-sql-python-connector"]
cockroachdb = ["psycopg[binary,pool]", "asyncpg"]
duckdb = ["duckdb", "pytz"]
fastapi = ["fastapi"]
flask = ["flask"]
fsspec = ["fsspec"]
litestar = ["litestar"]
msgspec = ["msgspec"]
mypyc = ["sqlglot[c]>=30.0.0"]
mysql-connector = ["mysql-connector-python"]
nanoid = ["fastnanoid>=0.4.1"]
obstore = ["obstore"]
opentelemetry = ["opentelemetry-instrumentation"]
oracledb = ["oracledb"]
orjson = ["orjson"]
pandas = ["pandas", "pyarrow"]
performance = ["msgspec"]
polars = ["polars", "pyarrow"]
prometheus = ["prometheus-client"]
psqlpy = ["psqlpy"]
psycopg = ["psycopg[binary,pool]"]
pydantic = ["pydantic", "pydantic-extra-types"]
pymssql = ["pymssql"]
pymysql = ["pymysql"]
spanner = ["google-cloud-spanner"]
uuid = ["uuid-utils"]

[dependency-groups]
benchmarks = ["sqlalchemy[asyncio]", "psutil", "types-psutil", "duckdb-engine>=0.17.0"]
build = ["bump-my-version", "hatch-mypyc", "mypy>=1.19.1", "pydantic-settings"]
dev = [
  { include-group = "extras" },
  { include-group = "lint" },
  { include-group = "doc" },
  { include-group = "test" },
  { include-group = "build" },
  { include-group = "benchmarks" },
]
doc = [
  "auto-pytabs[sphinx]>=0.5.0",
  "shibuya",
  "sphinx",
  "sphinx-autobuild>=2021.3.14",
  "sphinx-copybutton>=0.5.2",
  "sphinx-click>=6.0.0",
  "click-extra[sphinx]",
  "sphinx-design>=0.5.0",
  "sphinx-tabs",
  "sphinx-datatables",
  "sphinxcontrib-jquery",
  "sphinxcontrib-mermaid>=0.9.2",
  "sphinx-paramlinks>=0.6.0",
  "sphinx-togglebutton>=0.3.2",
  "myst-parser",
  "sphinx-autodoc-typehints",
  "numpydoc",
  "sphinx-iconify",
  "jupyter-sphinx",
  "nbsphinx",
]
extras = [
  "adbc_driver_manager",
  "fsspec[s3]",
  "pgvector",
  "pyarrow",
  "polars",
  "adbc_driver_sqlite",
  "adbc_driver_postgresql",
  "adbc_driver_flightsql",
  "adbc_driver_bigquery",
  "dishka",
]
lint = [
  "mypy>=1.19.1",
  "pre-commit>=3.5.0",
  "pyright>=1.1.386",
  "ruff>=0.7.1",
  "slotscheck>=0.16.5",
  "types-Pygments",
  "types-colorama",
  "types-cffi",
  "types-protobuf",
  "asyncpg-stubs",
  "pyarrow-stubs",
  "pandas-stubs",
  "tomli>=2.0.0",
  "types-PyMySQL",
]
test = [
  "aiohttp",
  "requests",
  "anyio",
  "sniffio",
  "coverage>=7.6.1",
  "covdefaults",
  "pytest>=8.0.0",

  "pytest-cov>=5.0.0",
  "pytest-databases[postgres,oracle,mysql,bigquery,spanner,minio]>=0.17.0",
  "pytest-mock>=3.14.0",
  "pytest-sugar>=1.0.0",
  "pytest-xdist>=3.6.1",
  "pytest-timeout>=2.3.1",
]

[project.scripts]
sqlspec = "sqlspec.__main__:run_cli"

[project.entry-points."pygments.styles"]
sqlspec-dark = "tools.sphinx_ext.pygments_styles:SQLSpecDarkStyle"
sqlspec-light = "tools.sphinx_ext.pygments_styles:SQLSpecLightStyle"

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling", "hatch-mypyc"]

[tool.hatch.build.targets.sdist]
dev-mode-dirs = ["."]
exclude = ["/.github", "/docs"]

[tool.hatch.metadata]
allow-direct-references = true

[tool.hatch.build.targets.wheel]
packages = ["sqlspec"]


[tool.hatch.build.targets.wheel.hooks.mypyc]
dependencies = ["hatch-mypyc", "hatch-cython", "mypy>=1.19.1"]
enable-by-default = false
exclude = [
  "tests/**",                                 # Test files
  "sqlspec/__main__.py",                      # Entry point (can't run directly when compiled)
  "sqlspec/cli.py",                           # CLI module (not performance critical)
  "sqlspec/typing.py",                        # Type aliases
  "sqlspec/_typing.py",                       # Type aliases
  "sqlspec/**/_typing.py",                    # Type aliases (mypyc-incompatible)
  "sqlspec/config.py",                        # Main config
  "sqlspec/extensions/**",                    # All extensions
  "sqlspec/dialects/**/*.py",                 # Keep SQLGlot dialect subclasses interpreted
  "sqlspec/**/__init__.py",                   # Init files (usually just imports)
  "sqlspec/protocols.py",                     # Protocol definitions
  "sqlspec/adapters/mock/**",                 # Mock adapter (testing only)
  "sqlspec/migrations/commands.py",           # Migration command CLI (dynamic imports)
  "sqlspec/data_dictionary/_loader.py",       # Loader relies on __file__ which fails in compiled modules
  "sqlspec/extensions/fastapi/providers.py",  # Uses SingletonMeta metaclass
  "sqlspec/extensions/litestar/providers.py", # Uses SingletonMeta metaclass
  "sqlspec/adapters/**/data_dictionary.py",   # Cross-module inheritance causes mypyc segfaults
  "sqlspec/observability/_formatting.py",     # Inherits from non-compiled logging.Formatter
  "sqlspec/utils/arrow_helpers.py",           # Arrow operations cause segfaults when compiled
]
include = [
  "sqlspec/core/**/*.py",                  # Core module
  "sqlspec/builder/**/*.py",               # Builder module
  "sqlspec/exceptions.py",                 # Exceptions module
  "sqlspec/loader.py",                     # Loader module
  "sqlspec/observability/**/*.py",         # Observability utilities
  "sqlspec/driver/**/*.py",                # Driver module
  "sqlspec/storage/registry.py",           # Safe storage registry/runtime routing
  "sqlspec/storage/errors.py",             # Safe storage error normalization
  "sqlspec/storage/backends/base.py",      # Storage backend runtime base classes
  "sqlspec/data_dictionary/**/*.py",       # Data dictionary mixin (required for adapter inheritance)
  "sqlspec/adapters/**/core.py",           # Adapter compiled helpers
  "sqlspec/adapters/**/type_converter.py", # All adapters type converters
  "sqlspec/utils/text.py",                 # Text utilities
  "sqlspec/utils/sync_tools.py",           # Synchronous utility functions
  "sqlspec/utils/type_guards.py",          # Type guard utilities
  "sqlspec/utils/fixtures.py",             # File fixture loading
  "sqlspec/utils/config_tools.py",         # Configuration utilities
  "sqlspec/utils/deprecation.py",          # Deprecation helpers
  "sqlspec/utils/dispatch.py",             # Dispatch helpers
  "sqlspec/utils/logging.py",              # Logging helpers
  "sqlspec/utils/serializers/**/*.py",     # Serialization helpers package
  "sqlspec/utils/type_converters.py",      # Adapter type converters
  "sqlspec/utils/correlation.py",          # Correlation context helpers
  "sqlspec/utils/portal.py",               # Thread portal utilities
  "sqlspec/utils/singleton.py",            # Lightweight singleton helpers
  "sqlspec/utils/schema.py",               # Schema transformation (refactored for mypyc)
  "sqlspec/utils/uuids.py",                # UUID utilities
]
mypy-args = [
  "--ignore-missing-imports",
  "--allow-untyped-defs",
  "--allow-untyped-globals",
  "--no-implicit-reexport",
  "--no-warn-redundant-casts",
  "--no-warn-unused-ignores",
  "--follow-imports=skip",
]
require-runtime-dependencies = true
require-runtime-features = ["mypyc"]

[tool.hatch.build.targets.wheel.hooks.mypyc.options]
debug_level = "0" # No debug info in production (0-2)
multi_file = true # Enable cross-module optimization
opt_level = "3"   # Maximum optimization (0-3)


[tool.bumpversion]
allow_dirty = true
commit = false
commit_args = "--no-verify"
current_version = "0.43.0"
ignore_missing_files = false
ignore_missing_version = false
message = "chore(release): bump to v{new_version}"
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}", "{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]
first_value = "stable"
optional_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}"'
search = 'version = "{current_version}"'

[[tool.bumpversion.files]]
filename = "uv.lock"
replace = """
name = "sqlspec"
version = "{new_version}"
"""
search = """
name = "sqlspec"
version = "{current_version}"
"""

[tool.codespell]
ignore-words-list = "te,ECT,SELCT,froms,ccompiler,BRIN"
skip = 'uv.lock'

[tool.coverage.run]
branch = true
concurrency = ["multiprocessing"]
disable_warnings = ["no-data-collected", "module-not-measured", "module-not-imported"]
omit = ["*/tests/*"]
parallel = true
plugins = ["covdefaults"]
relative_files = true
source = ["sqlspec"]

[tool.coverage.report]
# Regexes for lines to exclude from consideration
exclude_lines = [
  # Have to re-enable the standard pragma
  "pragma: no cover",

  # Don't complain about missing debug-only code:
  "def __repr__",
  "if self\\.debug",

  # Don't complain if tests don't hit defensive assertion code:
  "raise AssertionError",
  "raise NotImplementedError",

  # Don't complain if non-runnable code isn't run:
  "if 0:",
  "if __name__ == .__main__.:",
  "if TYPE_CHECKING:",
  'class .*\bProtocol\):',
  '@(abc\.)?abstractmethod',
]

[tool.pytest.ini_options]
addopts = ["-q", "-ra"]
anyio_mode = "auto"
filterwarnings = [
  "ignore::DeprecationWarning:pkg_resources.*",
  "ignore:pkg_resources is deprecated as an API:DeprecationWarning",
  "ignore::DeprecationWarning:pkg_resources",
  "ignore:You are using a Python version .+ google\\.api_core:FutureWarning",
  "ignore::DeprecationWarning:google.rpc",
  "ignore::DeprecationWarning:google.gcloud",
  "ignore::DeprecationWarning:google.iam",
  "ignore::DeprecationWarning:google",
  "ignore::DeprecationWarning:websockets.connection",
  "ignore::DeprecationWarning:websockets.legacy",
  "ignore::PendingDeprecationWarning:rich_click.*",
  "ignore:`use_markdown=` will be deprecated:PendingDeprecationWarning",
  "ignore:`use_rich_markup=` will be deprecated:PendingDeprecationWarning",
  "ignore:`show_metavars_column=` will be deprecated:PendingDeprecationWarning",
  "ignore:`append_metavars_help=` will be deprecated:PendingDeprecationWarning",
  "ignore:You are using a Python version .+ which Google will stop supporting:FutureWarning",
  "ignore:You are using a Python version .+ which Google will stop supporting in new releases of google.api_core:FutureWarning",
  "ignore:You are using a Python version .+ which Google will stop supporting in new releases of google.cloud.spanner_admin_database_v1:FutureWarning",
  "ignore:You are using a Python version .+ which Google will stop supporting in new releases of google.cloud.spanner_admin_instance_v1:FutureWarning",
  "ignore:You are using a Python version .+ which Google will stop supporting in new releases of google.cloud.bigquery_storage_v1:FutureWarning",
]
markers = [
  "integration: marks tests that require an external database",
  "postgres: marks tests specific to PostgreSQL",
  "duckdb: marks tests specific to DuckDB",
  "sqlite: marks tests specific to SQLite",
  "bigquery: marks tests specific to Google BigQuery",
  "mysql: marks tests specific to MySQL",
  "oracle: marks tests specific to Oracle",
  "spanner: marks tests specific to Google Cloud Spanner",
  "snowflake: marks tests specific to Snowflake",
  "mssql: marks tests specific to Microsoft SQL Server",
  # Driver markers
  "adbc: marks tests using ADBC drivers",
  "aioodbc: marks tests using aioodbc",
  "aiosqlite: marks tests using aiosqlite",
  "asyncmy: marks tests using asyncmy",
  "asyncpg: marks tests using asyncpg",
  "duckdb_driver: marks tests using the duckdb driver",
  "google_bigquery: marks tests using google-cloud-bigquery",
  "google_spanner: marks tests using google-cloud-spanner",
  "oracledb: marks tests using oracledb",
  "psycopg: marks tests using psycopg",
  "pymssql: marks tests using pymssql",
  "mysql_connector: marks tests using mysql-connector",
  "pymysql: marks tests using pymysql",
  "psqlpy: marks tests using psqlpy",
]
python_files = ["test_*.py", "quickstart_*.py", "usage_*.py"]
testpaths = ["tests", "docs/examples"]
timeout = 300
timeout_method = "thread"

[tool.mypy]
exclude = ["tmp/", ".tmp/", ".bugs/"]
packages = ["sqlspec", "tests"]
python_version = "3.10"

disallow_any_generics = false
disallow_untyped_decorators = true
enable_error_code = "ignore-without-code"
implicit_reexport = false
show_error_codes = true
strict = true
warn_redundant_casts = true
warn_return_any = true
warn_unreachable = false
warn_unused_configs = true
warn_unused_ignores = true

[[tool.mypy.overrides]]
ignore_missing_imports = true
module = [
  "orjson",
  "uvicorn.*",
  "uvloop.*",
  "asyncmy",
  "asyncmy.*",
  "pyarrow",
  "pyarrow.*",
  "opentelemetry.*",
  "opentelemetry.instrumentation.*",
  "opentelemetry",
  "prometheus_client",
  "prometheus_client.*",
  "fsspec",
  "fsspec.*",
  "sqlglot",
  "sqlglot.*",
  "minio",
]

[[tool.mypy.overrides]]
disable_error_code = "ignore-without-code"
module = "sqlspec.extensions.litestar.providers"

[[tool.mypy.overrides]]
disable_error_code = "ignore-without-code,method-assign,attr-defined,unused-ignore,assignment,no-untyped-def,return-value"
module = "tests.*"


[tool.pyright]
disableBytesTypePromotions = true
exclude = ["**/node_modules", "**/__pycache__", ".venv", "tools", "docs", "tmp", ".tmp", ".bugs"]
include = ["sqlspec", "tests"]
pythonVersion = "3.10"
reportMissingTypeStubs = false
reportPrivateImportUsage = false
reportPrivateUsage = false
reportTypedDictNotRequiredAccess = false
reportUnknownArgumentType = false
reportUnnecessaryCast = false
venv = ".venv"

[tool.slotscheck]
strict-imports = false

[tool.ruff]
exclude = [".venv", "node_modules", "tmp", ".tmp", ".bugs"]
line-length = 120
src = ["sqlspec", "tests", "docs/examples", "tools"]
target-version = "py310"

[tool.ruff.format]
docstring-code-format = true
docstring-code-line-length = 60
preview = true
skip-magic-trailing-comma = true

[tool.ruff.lint]
extend-safe-fixes = ["TC"]
fixable = ["ALL"]
ignore = [
  "A003",    # flake8-builtins - class attribute {name} is shadowing a python builtin
  "B010",    # flake8-bugbear - do not call setattr with a constant attribute value
  "B904",    # Within an `except` clause, raise exceptions with `raise ... from err` or `raise ... from None`
  "D100",    # pydocstyle - missing docstring in public module
  "D101",    # pydocstyle - missing docstring in public class
  "D102",    # pydocstyle - missing docstring in public method
  "D103",    # pydocstyle - missing docstring in public function
  "D104",    # pydocstyle - missing docstring in public package
  "D105",    # pydocstyle - missing docstring in magic method
  "D106",    # pydocstyle - missing docstring in public nested class
  "D107",    # pydocstyle - missing docstring in __init__
  "D202",    # pydocstyle - no blank lines allowed after function docstring
  "D205",    # pydocstyle - 1 blank line required between summary line and description
  "D415",    # pydocstyle - first line should end with a period, question mark, or exclamation point
  "DOC501",  # pydocstyle - Missing raise information in docstring
  "E501",    # pycodestyle line too long, handled by ruff format
  "PLW2901", # pylint - for loop variable overwritten by assignment target
  "RUF012",  # Ruff-specific rule - annotated with classvar
  "ISC001",  # Ruff formatter incompatible
  "A005",    # flake8 - Module `x` shadows a Python standard-library module
  "PLC0415", # pylint - `import` should be at the top of the file
  "FA100",   # Add `from __future__ import annotations` to simplify
  "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed
  "FBT001",  # Boolean-typed positional argument in function definition
  "FBT002",  # Boolean default positional argument in function definition
  "FBT003",  # Boolean positional value in function call
  "PLR0913", # pylint - Too many arguments in function definition
  "ARG002",  # Unused method argument
  "ARG001",  # Unused function argument
  "CPY001",  # pycodestyle - Missing Copywrite notice at the top of the file
  "RUF029",  # Ruff - function is declared as async but has no awaitable calls
  "COM812",  # flake8-comma - Missing trailing comma
  "PGH003",  # Use Specific ignore for pyright
  "PLR0911", # pylint - Too many return statements
  "PLR0912", # pylint - Too many branches
  "PLR0914", # pylint - Too many statements
  "PLR0915", # pylint - Too many lines in module
  "PLR0916", # pylint - Too many statements in function
  "PLR0917", # pylint - Too many statements in class
  "DOC201",  # pydocstyle - Missing return statement
  "BLE001",  # pylint -  Blind exception
  "S101",    # S101 - Use of assert
  "FIX002",  # Ruff - Allow the use of TODO in comments
  "TD003",   # Ruff - Missing issue link for TODO
  "TD002",   # Ruff - Missing author for TODO
  "PYI036",  # pyright - Missing type annotation for `__aexit__`
  "A002",    # ruff - function argument is shadowing a python builtin
  "DOC202",  # pydocstyle - Code should not have a return section in the docstring
  "SLF001",  # ruff - access of private method outside of class
  "S608",    # ruff - Possible sql injection
  "PLR0904", # too many public methods
  "PLR6301", # method could be static or class method
  "B903",    # class could be a dataclass or named tuple
  "PLW0603", # Using the global statement to update is discouraged
  "PLW0108", # Replace lambda expression with a def
  "RUF067",  # ruff - init should only have import statements
]
select = ["ALL"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.mccabe]
max-complexity = 25

[tool.ruff.lint.pylint]
max-bool-expr = 10
max-branches = 20
max-locals = 20
max-nested-blocks = 7
max-returns = 15

[tool.ruff.lint.pep8-naming]
classmethod-decorators = ["classmethod"]

[tool.ruff.lint.isort]
known-first-party = ["sqlspec", "tests"]
split-on-trailing-comma = false

[tool.ruff.lint.per-file-ignores]
"docs/**/*.*" = ["S", "B", "DTZ", "A", "TC", "ERA", "D", "RET", "PLW0127", "PLR2004"]
"docs/examples/**" = ["T201"]
"sqlspec/adapters/spanner/config.py" = ["PLC2801"]
"sqlspec/builder/mixins/**/*.*" = ["SLF001"]
"sqlspec/extensions/adk/converters.py" = ["S403"]
"sqlspec/migrations/utils.py" = ["S404"]
"tests/**/*.*" = [
  "A",
  "ARG",
  "B",
  "BLE",
  "C901",
  "D",
  "DTZ",
  "EM",
  "FBT",
  "G",
  "N",
  "PGH",
  "PIE",
  "PLR",
  "PLW",
  "PTH",
  "RSE",
  "S",
  "S101",
  "SIM",
  "TC",
  "TRY",
  "PT012",
  "INP001",
  "DOC",
  "ERA001",
  "SLF001",
  "PLC",
  "PT",
  "PERF203",
  "ANN",
]
"tools/**/*.*" = ["D", "ARG", "EM", "TRY", "G", "FBT", "S603", "F811", "PLW0127", "PLR0911"]
"tools/prepare_release.py" = ["S603", "S607"]

[tool.ruff.lint.flake8-tidy-imports]
# Disallow all relative imports.
ban-relative-imports = "all"