pyproject.toml

# Reference: https://packaging.python.org/en/latest/guides/writing-pyproject-toml
[build-system]
requires = ["uv_build>=0.11.0,<0.12.0"]
build-backend = "uv_build"

[project]
name = "narwhals"
version = "2.21.2"
dependencies = []
requires-python = ">=3.10"
authors = [
  { name = "Marco Gorelli", email = "hello_narwhals@proton.me" },
]
license = "MIT"
license-files = ["LICENSE.md"]
description = "Extremely lightweight compatibility layer between dataframe libraries"
readme = "README.md"
keywords = ["dataframes", "interoperability", "pandas", "polars", "pyarrow", "dask", "modin", "cudf"]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Operating System :: OS Independent",
  "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 :: Free Threading :: 2 - Beta",
  "Typing :: Typed",
]

[project.urls]
Homepage = "https://github.com/narwhals-dev/narwhals"
Documentation = "https://narwhals-dev.github.io/narwhals/"
Repository = "https://github.com/narwhals-dev/narwhals"
"Bug Tracker" = "https://github.com/narwhals-dev/narwhals/issues"

[project.optional-dependencies]
# These should be aligned with MIN_VERSIONS in narwhals/utils.py
# Exception: modin, because `modin.__version__` isn't aligned with
# `modin.pandas.__version__`. The latter is the one that we make
# API decisions based on, so that's the one we track internally.
# We have yet to determine the minimum Modin version we support
# https://github.com/narwhals-dev/narwhals/issues/817 
pandas = ["pandas>=1.3.4"]
modin = ["modin>=0.22.0"]
cudf = ["cudf-cu12>=24.10.0; sys_platform == 'linux'"]
pyarrow = ["pyarrow>=13.0.0"]
pyspark = ["pyspark>=3.5.0"]
pyspark-connect = ["pyspark[connect]>=3.5.0"]
polars = ["polars>=0.20.4"]
dask = ["dask[dataframe]>=2024.8"]
duckdb = ["duckdb>=1.1"]
ibis = ["ibis-framework>=6.0.0", "rich>=12.4.4", "packaging>=21.3", "pyarrow_hotfix>=0.7"]
# TODO(FBruzzesi): Investigate if dependencies other than ibis-framework itself
# can be moved to constraint-dependencies section. See:
#  * docs.astral.sh/uv/reference/settings#constraint-dependencies
#  * https://github.com/narwhals-dev/narwhals/pull/3608#discussion_r3252827624

sqlframe = ["sqlframe>=3.22.0,!=3.39.3"]
sql = ["narwhals[duckdb]", "sqlparse>=0.5.5"]

[dependency-groups]
core = [
  "pandas>=1.3.4",
  "duckdb>=1.5",
  "narwhals[duckdb,polars,pyarrow,sqlframe,sql]"
]
plugins = [
  "test-plugin",
]
tests = [
  "covdefaults",
  "pytest>=9.0.3",
  "pytest-cov",
  "pytest-env",
  "pytest-randomly",
  "pytest-xdist",
  "hypothesis>=6.0.0",
  {include-group = "plugins"},
]
extra = [  # heavier dependencies we don't necessarily need in every testing job
  "scikit-learn",
]
typing = [  # keep some of these pinned and bump periodically so there's fewer surprises for contributors
  # Type checkers
  "mypy==2.1.0",
  "pyrefly==1.0.0",
  "pyright",
  # Dependencies
  "pyarrow<24", # temporary pin due to https://github.com/narwhals-dev/narwhals/issues/3560
  "hypothesis>=6.0.0",
  "pytest>=9.0.3",
  "pandas-stubs==2.3.0.250703",
  "pyarrow-stubs==19.2",
  "typing-extensions==4.15.0",
  "narwhals[dask,duckdb,ibis,pandas,polars,pyarrow,sql,sqlframe]",
  {include-group = "plugins"},
]
docs = [
  "black>=26.3.1",  # required by mkdocstrings_handlers
  "jinja2>=3.1.6",
  "markdown-exec[ansi]>=1.12.1",
  "mkdocs-autorefs>=1.4.4",
  "mkdocstrings-python>=2.0.3",
  "pandas>=1.3.4",
  "narwhals[duckdb,pyarrow,polars,sql,sqlframe]",
  "zensical>=0.0.38"
]
dev = [
  "prek",
  "ruff",
  {include-group = "tests"},
]
dev-core = [
  {include-group = "dev"},
  {include-group = "core"},
]
core-tests = [
  {include-group = "core"},
  {include-group = "tests"},
]
local-dev = [
  {include-group = "dev"},
  {include-group = "core"},
  {include-group = "docs"},
  {include-group = "plugins"},
]

extreme-minimum-versions = [
  "setuptools",
  "tzdata",
  "pandas==1.3.4",
  "polars==0.20.4",
  "numpy==1.21.4",
  "pyarrow==13.0.0",
  "pyarrow-stubs<17",
  "scipy==1.7.3",
  "scikit-learn==1.1.0",
  "duckdb==1.1",
  {include-group = "tests"},
]

extreme-pretty-old-versions = [
  "setuptools",
  "tzdata",
  "pandas==1.4.1",
  "polars==0.20.4",
  "numpy==1.22.0",
  "pyarrow==14.0.0",
  "pyarrow-stubs<17",
  "scipy==1.8.0",
  "scikit-learn==1.1.0",
  "duckdb==1.2",
  {include-group = "tests"},
]

extreme-not-so-old-versions = [
  "setuptools",
  "tzdata",
  "pandas==2.0.3",
  "polars==0.20.8",
  "numpy==1.24.4",
  "pyarrow==15.0.0",
  "pyarrow-stubs<17",
  "scipy==1.8.0",
  "scikit-learn==1.3.0",
  "duckdb==1.3",
  "dask[dataframe]==2024.10",
  {include-group = "tests"},
]

min-pyspark-version = [
  "pyspark==3.5.0",
  {include-group = "core-tests"},
]

[tool.uv.build-backend]
source-include = [
  "src/*",
  "tests/*",
]
wheel-include = [
  "src/*",
]

[tool.uv]
# NOTE: When updating these conflicts, every entry in a single inner list is
# treated as mutually exclusive with every other entry in the same list.
# See https://docs.astral.sh/uv/reference/settings/#conflicts.
conflicts = [
  # TODO: Remove these conflict when Modin and/or CuDF will support pandas v3.0+
  # In the meanwhile, this is needed to run tests with pandas v3.0+
  [
    { extra = "cudf" },
    { extra = "modin" },
    { extra = "pandas" },
  ],
  # `typing` dependecy group pins "pyarrow" and, potentially, other
  # dependencies for which we want to check latest versions during tests
  [
    { group = "core" },
    { group = "typing" },
  ],
  # The `extreme-*` groups pin mutually incompatible pyarrow/pandas/numpy
  # versions, and all pin `pyarrow-stubs<17` while `typing` pins ==19.2. `cudf`
  # is here because old pandas/numpy forces cudf-cu12==24.10.x, whose
  # nvidia-stub build backend fails on non-linux platforms during lock.
  [
    { extra = "cudf" },
    { group = "typing" },
    { group = "extreme-minimum-versions" },
    { group = "extreme-not-so-old-versions" },
    { group = "extreme-pretty-old-versions" },
  ],
  # `dask[dataframe]>=2024.8` transitively requires pyarrow>=16 / pandas>=2,
  # and `modin>=0.22` pins pandas==1.5.3, both incompatible with the older two
  # `extreme-*` groups. `extreme-not-so-old-versions` is omitted: it already
  # pins dask==2024.10 and pandas==2.0.3, which are compatible.
  [
    { extra = "cudf" },
    { extra = "dask" },
    { extra = "modin" },
    { group = "extreme-minimum-versions" },
    { group = "extreme-pretty-old-versions" },
  ],
  # `core` resolves modern pandas/duckdb/polars/etc., conflicting with every
  # `extreme-*` group's old version pins.
  [
    { group = "core" },
    { group = "extreme-minimum-versions" },
    { group = "extreme-not-so-old-versions" },
    { group = "extreme-pretty-old-versions" },
  ],
]

[tool.uv.workspace]
members = ["packages/*"]

[tool.uv.sources]
test-plugin = { workspace = true }

[tool.ruff]
line-length = 90
fix = true
target-version = "py310"
extend-exclude = ["**/this.py"]

[tool.ruff.lint]
preview = true
explicit-preview-rules = true
typing-modules = ["narwhals._typing_compat"]

extend-safe-fixes = [
  "C419",    # unnecessary-comprehension-in-call
  "C420",    # unnecessary-dict-comprehension-for-iterable
  "EM101",   # raw-string-in-exception
  "EM102",   # f-string-in-exception
  "PLR6201", # literal-membership
  "TC",      # flake8-type-checking
  "UP",      # pyupgrade
  "PLW1514", # unspecified-encoding
]
extend-select = [
  "PLR0914", # too-many-locals
  "PLR0916", # too-many-boolean-expressions
  "PLR1702", # too-many-nested-blocks
  "PLR6201", # literal-membership
  "PLW1514", # unspecified-encoding
]
select = ["ALL"]
ignore = [
  "A001",    # builtin-variable-shadowing
  "A004",    # builtin-import-shadowing
  "ARG002",  # unused-method-argument
  "ANN401",  # any-type
  "COM812",  # missing-trailing-comma
  "D100",    # undocumented-public-module
  "D101",    # undocumented-public-class
  "D102",    # undocumented-public-method
  "D103",    # undocumented-public-function
  "D104",    # undocumented-public-package
  "D105",    # undocumented-magic-method
  "D107",    # undocumented-public-init
  "DTZ001",  # call-datetime-without-tzinfo
  "E501",    # line-too-long
  "FBT003",  # boolean-positional-value-in-call (We enforce at definition site when it is a flag, not a value (e.g. `lit(False)`))
  "FIX",     # flake8-fixme
  "PD010",   # pandas-use-of-dot-pivot-or-unstack
  "PLC0415", # `import` should be at the top-level of a file
  "PLR0913", # too-many-arguments
  "PLR2004", # magic-value-comparison
  "PLW1641", # Object does not implement `__hash__` method
  "SLF001",  # private-member-access
  "TD003",   # missing-todo-link
  "TD004",   # missing-todo-colon
]

[tool.ruff.lint.flake8-builtins]
builtins-ignorelist = ["format"]

[tool.ruff.lint.pep8-naming]
extend-ignore-names = [
  "Series", 
  "DataFrame", 
  "_Window", 
  "F", 
  "_F",
]

[tool.ruff.lint.per-file-ignores]
"src/narwhals/expr_dt.py" = ["RUF002"] 
"src/narwhals/typing.py" = [
  "PYI042",  # snake-case-type-alias (catches `_1DArray`)
] 
"src/narwhals/_*/utils.py" = [
  "PLR0911", # too-many-return-statements
]
"tests/*" = [
  "S101", 
  "C901",    # complex-structure
  "PLR0912", # too-many-branches
  "PLR0916", # too-many-boolean-expressions
]
"tpch/tests/*" = ["S101"]
"utils/*" = ["S311", "T201"]
"utils/bump_version.py" = ["S603", "S607"]
"tpch/execute/*" = ["T201"]
"tpch/notebooks/*" = [
  "ANN001",
  "ANN201",
  "EM101",
  "EXE002",
  "PTH123",
  "T203",
  "TRY003",
]

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

[tool.ruff.lint.pylint]
max-nested-blocks = 4

[tool.ruff.lint.isort]
required-imports = ["from __future__ import annotations"]
combine-as-imports = true
split-on-trailing-comma = false

[tool.ruff.format]
docstring-code-format = true
skip-magic-trailing-comma = true

[tool.pytest.ini_options]
norecursedirs =  ['*.egg', '.*', '_darcs', 'build', 'CVS', 'dist', 'node_modules', 'venv', '{arch}', 'src/narwhals/_*']
testpaths = ["tests"]
pythonpath = ["src"]
filterwarnings = [
  "error",
  'ignore:.*defaulting to pandas implementation:Warning:modin',
  'ignore:.*implementation has mismatches with pandas:Warning:modin',
  'ignore:.*You are using pyarrow version',
  
  # Deprecation raised by DuckDB
  'ignore:.*fetch_arrow_table\(\) is deprecated:DeprecationWarning:sqlframe',
  'ignore:.*fetch_arrow_table\(\) is deprecated:DeprecationWarning:ibis',

  # https://discuss.python.org/t/types-uniontype-was-merged-with-wrong-class-not-even-a-class/102275/31
  "ignore:.*'_UnionGenericAlias' is deprecated:DeprecationWarning",

  # This warning was temporarily raised by pandas but then reverted.
  'ignore:.*Passing a BlockManager to DataFrame:DeprecationWarning',

  # This warning was temporarily raised by Polars but then reverted.
  'ignore:.*The default coalesce behavior of left join will change:DeprecationWarning',

  'ignore: unclosed <socket.socket',
  'ignore:.*The distutils package is deprecated and slated for removal in Python 3.12:DeprecationWarning:pyspark',
  'ignore:.*distutils Version classes are deprecated. Use packaging.version instead.*:DeprecationWarning',
  'ignore:.*is_datetime64tz_dtype is deprecated and will be removed in a future version.*:DeprecationWarning:pyspark',
  'ignore:.*The copy keyword is deprecated and will be removed in a future version.*:Warning:pyspark',

  # Warning raised by PyArrow nightly just by importing pandas
  'ignore:.*Python binding for RankQuantileOptions not exposed:RuntimeWarning:pyarrow',

  'ignore:.*pandas only supports SQLAlchemy:UserWarning:sqlframe',
  'ignore:.*numpy.core is deprecated and has been renamed to numpy._core.*:DeprecationWarning:sqlframe',
  "ignore:.*__array__ implementation doesn't accept a copy keyword, so passing copy=False failed:DeprecationWarning:modin",

  # raised internally by pandas
  "ignore:.*np.find_common_type is deprecated:DeprecationWarning:pandas",

  # Warning raised when calling PandasLikeNamespace.from_arrow with old pyarrow
  "ignore:.*is_sparse is deprecated and will be removed in a future version.*:DeprecationWarning:pyarrow",

  "ignore:.*invalid value encountered in cast:RuntimeWarning:pandas",
  "ignore:.*The behavior of DataFrame concatenation with empty or all-NA entries is deprecated:FutureWarning",

  # raised internally by Dask
  "ignore:.*'generic' unit for NumPy timedelta is deprecated.*:DeprecationWarning:dask",
  "ignore:.*Downcasting behavior in Series and DataFrame methods 'where', 'mask', and 'clip' is deprecated.*:FutureWarning:dask",

  # raise internally by polars
  "ignore:.*interchange protocol is deprecated.*:DeprecationWarning"
]
xfail_strict = true
markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]
env = [
  "MODIN_ENGINE=python",
  "PYARROW_IGNORE_TIMEZONE=1",
  "TZ=UTC",
]

[tool.coverage.run]
plugins = ["covdefaults"]

[tool.coverage.report]
fail_under = 80  # This is just for local development, in CI we set it to 100
omit = [
  "src/narwhals/typing.py",
  "src/narwhals/compliant.py",
  "src/narwhals/stable/v1/typing.py",
  "src/narwhals/stable/v2/typing.py",
  "src/narwhals/this.py",
  "src/narwhals/_arrow/typing.py",
  "src/narwhals/_duckdb/typing.py",
  "src/narwhals/_spark_like/typing.py",
  # We run Ibis in a separate CI job to the coverage one, to avoid their tight dependency pins.
  "src/narwhals/_ibis/*",
  # Remove after finishing eager sub-protocols
  "src/narwhals/_compliant/namespace.py",
  "tests/ibis_test.py",
]
exclude_also = [
  "if sys.version_info() <",
  "if .* is Implementation.(CUDF|MODIN|PYSPARK|PYSPARK_CONNECT|IBIS)",
  "if .*.is_(cudf|modin|pyspark|pyspark_connect|ibis)",
  'if "(cudf|modin|pyspark|ibis)" in',
  "if not .*.is_pandas",
  "if is_ibis_table",
  "if MYPY",
  "except ModuleNotFoundError",
  'request.applymarker\(pytest.mark.xfail',
  'backend_version <',
  '.*._backend_version\(\) <',
  'BACKEND_VERSION <',
  'if ".*" in str\(constructor',
  'pytest.skip\(',
  'assert_never\(',
  'PANDAS_VERSION < \('
]

[tool.mypy]
files = ["src", "tests", "packages/test-plugin"]
pretty = true
strict = true
allow_redefinition = true  # https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-allow-redefinition

[[tool.mypy.overrides]]
module = [
  "cudf.*",
  "cupy.*",
  "dask.*",
  "dask_expr.*",
  # https://github.com/ibis-project/ibis/issues/6844
  "ibis.*",
  "joblib.*",
  "modin.*",
  "numpy.*",
  "pyspark.*",
  "sklearn.*",
  "sqlparse.*",
]
# TODO: remove follow_imports
follow_imports = "skip"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = [
  "narwhals._expression_parsing",
  "narwhals._utils",
  "narwhals._pandas_like.*",
  "narwhals._ibis.*",
  "narwhals._arrow.*",
  "narwhals._dask.*",
  "narwhals._spark_like.*",
]
warn_return_any = false

[tool.pyright]
pythonPlatform = "All"
# NOTE (`pyarrow-stubs` do unsafe `TypeAlias` and `TypeVar` imports)
# pythonVersion = "3.10"
reportMissingTypeArgument = "error"
reportIncompatibleMethodOverride = "error"
reportMissingImports = "none"
reportMissingModuleSource = "none"
reportPrivateImportUsage = "none"
reportUnusedExpression = "none"    # handled by (https://docs.astral.sh/ruff/rules/unused-variable/)
typeCheckingMode = "basic"
include = ["src", "tests", "packages/test-plugin"]
ignore = [
  "../.venv/",
  "../../../**/Lib",      # stdlib
  "../../../**/typeshed*" # typeshed-fallback
]
defineConstant = { "MYPY" = false }

[tool.pyrefly]
search-path = ["src", "."]
project-includes = ["tests"]
ignore-missing-imports = [
    "cudf.*",
    "cupy.*",
    "dask.*",
    "dask_expr.*",
    "joblib.*",
    "modin.*",
    "pyspark.*",
    "sklearn.*",
    "sqlparse.*",
]