pyproject.toml

[build-system]
requires = ["uv_build>=0.10.11,<0.11.0"]
build-backend = "uv_build"

[project]
name = "modmail.py"
description = "A Discord Modmail bot."
version = "5.0a1"
authors = [
    {name = "Taaku18", email = "taku@modmail.dev"},
]
readme = "README.md"
requires-python = "==3.14.*"
license = "AGPL-3.0-or-later"
license-files = ["LICEN[CS]E*"]

keywords = ["discord", "discord-bot", "modmail", "python", "discord.py", "discord-modmail"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Framework :: AsyncIO",
    "Environment :: Console",
    "Natural Language :: English",
    "Intended Audience :: End Users/Desktop",
    "Intended Audience :: Developers",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.14",
    "Topic :: Communications :: Chat",
    "Topic :: Communications :: Conferencing",
    "Typing :: Typed",
]

dependencies = [
    "discord.py==2.7.1",  # Ensure to keep in sync with [project.optional-dependencies.speed]
    "rich~=14.3.0",
    "pydantic~=2.12.0",
    "pydantic-settings~=2.13.0",
    "python-dotenv~=1.2.2",
    "packaging",  # For version parsing, should be installed by default but just in case
    "pyyaml~=6.0.3",
    "fluent-runtime~=0.4.0",
]

[project.optional-dependencies]
speed = [
    "discord.py[speed]==2.7.1",
    "uvloop>=0.22.1; platform_system != \"Windows\"",  # NOTE: uvloop 0.22.1 has known issues on Python 3.14 (debug mode crash), fallback to asyncio is handled in bot.py
]
sqlite = [
    "sqlalchemy[asyncio,aiosqlite]~=2.0.49",
    "alembic~=1.18.0",
]
postgresql = [
    "sqlalchemy[asyncio,postgresql-asyncpg]~=2.0.49",
    "alembic~=1.18.0",
]
mysql = [
    "sqlalchemy[asyncio,asyncmy]~=2.0.49",
    "alembic~=1.18.0",
]
mariadb = [
    "sqlalchemy[asyncio,asyncmy]~=2.0.49",
    "alembic~=1.18.0",
]
mongodb = [
    "beanie[zstd]~=2.0.1",
]

[dependency-groups]
dev = [
    "ruff==0.15.9",  # When updating ruff version, update it in .pre-commit-config.yaml too
    "pyright==1.1.408",
    "pre-commit<5,>=4.5.1",  # When updating pre-commit version, update it in the tox "lint" section too
    "python-dotenv>=1.2.2",  # TODO: .env isn't supported/tested yet
    # When updating pytest plugins, update it below in the pytest "required_plugins" section too
    # TODO: unit testing and tox are currently disabled
    "tox<5,>=4.52.0",  # When updating tox version, update it below in the [tool.tox] section too
    "pytest==9.0.2",
    "pytest-mock==3.15.1",
    "pytest-asyncio==1.3.0",
    "pytest-cov==7.1.0",
    "pip",  # For IDE detecting installed packages
]
docs = [
    "zensical==0.0.31",
    "mkdocstrings[python]==1.0.3",
    "griffe-pydantic==1.3.1",
]
debug = [
    "jishaku~=2.6.3",
]
packaging = [
    "pyinstaller~=6.19.0",
]
# TODO: set up git hooks and configure pyinstaller
# this command kind of works: uv run pyinstaller --onefile --nowindow --clean --name modmail --copy-metadata modmail.py --collect-all modmail --hidden-import=logging.config start.py

[project.urls]
Documentation = "https://docs.modmail.dev"
Repository = "https://github.com/modmail-dev/modmail"
Issues = "https://github.com/modmail-dev/modmail/issues"
Changelog = "https://github.com/modmail-dev/Modmail/blob/master/CHANGELOG.md"
Funding = "https://buymeacoffee.com/modmaildev"

[tool.uv]
default-groups = []  # Don't install any optional dependencies by default

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

[tool.uv.build-backend]
module-name = "modmail"
module-root = ""  # default expects src/, we have everything in the root

[tool.ruff]
line-length = 115
preview = true
namespace-packages = ["modmail", "modmail/cogs"]

[tool.ruff.format]
docstring-code-format = true
docstring-code-line-length = 105
line-ending = "lf"

[tool.ruff.lint]
select = [
    "E", "W",  # pycodestyle
    "F",       # pyflakes
    "ANN",     # flake8-annotations
    "ASYNC",   # flake8-async
    "S",       # flake8-bandit
    "B",       # flake8-bugbear
    "A",       # flake8-builtins
    "C4",      # flake8-comprehensions
    "DTZ",     # flake8-datetimez
    "T10",     # flake8-debugger
    "ISC",     # flake8-implicit-str-concat
    "LOG",     # flake8-logging
    "G",       # flake8-logging-format
    "PIE",     # flake8-pie
    "T20",     # flake8-print
    "PT",      # flake8-pytest-style
    "RSE",     # flake8-raise
    "RET",     # flake8-return
    "SIM",     # flake8-simplify
    "TC",      # flake8-type-checking
    "PTH",     # flake8-use-pathlib
    "I",       # isort
    "N",       # pep8-naming
    "PERF",    # Perflint
    "DOC",     # pydoclint (preview)
    "D",       # pydocstyle
    "PGH",     # pygrep-hooks
    "PL",      # pylint
    "UP",      # pyupgrade
    "FURB",    # refurb (preview)
    "RUF",     # Ruff-specific rules
]

ignore = [
    # The following 6 rules conflicts with ruff formatter: https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
    "W191",
    "E111",
    "E114",
    "E117",
    "D206",
    "D300",
    "ANN401",  # Disallow `Any` type
    "S101",    # Use of assert detected
    "SIM102",  # Single `if` instead of nested `if`
    "SIM108",  # Use of ternary instead of `if`-`else`
    "DOC502",  # Raised exception is not explicitly raised (preview)
    "PLC0415", # `import` should be at the top-level of a file (preview)
    "PLR0915", # Too many statements in function
    "PLR0913", # Too many arguments
    "PLR0912", # Too many branches
    "PLR0911", # Too many return statements
    "PLR0904", # Too many public methods
    "PLR1702", # Too many nested blocks (preview)
    "PLR5501", # Use `elif` instead of `else` then `if`
    "PLW2901", # `for` loop variable `value` overwritten by assignment target
    "PLR6301", # Method could be a function, class method, or static method (preview)
    "RUF012",  # Mutable class attributes should be annotated with `typing.ClassVar`
    "RUF067", # `__init__` module should only contain docstrings and re-exports
]

[tool.ruff.lint.flake8-type-checking]
# These base classes evaluate annotations at runtime (via Pydantic model construction /
# SQLAlchemy mapper configuration), so imports used only in their subclasses' field
# annotations must remain as runtime imports, not be moved to TYPE_CHECKING blocks.
runtime-evaluated-base-classes = [
    "pydantic.BaseModel",
    "pydantic_settings.BaseSettings",
    "beanie.Document",
    "sqlalchemy.orm.DeclarativeBase",
    "modmail.backends.sql.models.base.SQLBase",
]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F403"]  # F403: 'from module import *' used; unable to detect undefined names
"ftl_finder.py" = ["T201"]  # T201: Use of print
"tests/*" = ["D107", "D101", "D100", "D105", "D202", "D102", "D104", "D103", "PLR2004", "PLR0917", "PLC2701"]  # D*: Missing doc strings, PLR2004: Compare magic number, PLC2701: Private name import from external module
"modmail/backends/sql/migrations/versions/*" = ["D415", "UP"]  # D415:  First line should end with a period, question mark, or exclamation point
"modmail/cogs/*/commands/*.py" = ["TC002"]  # discord and commands are always kept as runtime imports in cogs
"modmail/cogs/*/listeners/*.py" = ["TC002"]  # discord and commands are always kept as runtime imports in cogs
"scripts/*.py" = ["S404", "S603", "S607"]  # Scripts intentionally use subprocess to invoke CLI tools

[tool.ruff.lint.isort]
required-imports = ["from __future__ import annotations"]
combine-as-imports = true

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

[tool.ruff.lint.pycodestyle]
max-doc-length = 105
max-line-length = 115

[tool.ruff.lint.pylint]
allow-dunder-method-names = ["__locale_str__"]

[tool.pyright]
exclude = [
    "**/__pycache__",
    "**/.tox",
    "**/venv",
    "**/env",
    "**/.venv",
    "**/.env",
    "dist",
    "docs",
    "tests",  # Tests are disabled for now
]
reportUnnecessaryTypeIgnoreComment = "warning"
reportPropertyTypeMismatch = "error"
pythonVersion = "3.14"
pythonPlatform = "All"
typeCheckingMode = "strict"
executionEnvironments = [
  { root = "tests", reportPrivateUsage = "none", reportFunctionMemberAccess = "none", reportWildcardImportFromLibrary = "none" },
]
venvPath = "."
venv = ".venv"

[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "module"
asyncio_default_test_loop_scope = "module"
addopts = "--cov=modmail --cov=modmail/cogs --cov-report html"
testpaths = ["tests"]
required_plugins = ["pytest-mock==3.15.1", "pytest-asyncio==1.3.0", "pytest-cov==7.0.0"]
filterwarnings = [
    "ignore:.*'audioop' is deprecated.*:DeprecationWarning", # discord.py uses audioop, which is deprecated
]

[tool.coverage.run]
omit = [
    "*/migrations/*",
]

[tool.coverage.report]
exclude_also = [  # Exclude files from coverage report, regex patterns
    "if TYPE_CHECKING:",
    "if os\\.environ\\.get\\(\"PYTEST_VERSION\"\\) is None:",
    "if __name__ == \"__main__\":",
    "raise NotImplementedError",
    "raise AssertionError",
]

[tool.tox]
requires = ["tox<5,>=4.52.0"]
envlist = ["3.14", "lint", "type"]

[tool.tox.env_run_base]
description = "Run test under {base_python}"
groups = ["all", "dev"]
commands = [["pytest"]]

[tool.tox.env.lint]
description = "run linters (pre-commit)"
skip_install = true
deps = ["pre-commit<5,>=4.5.1"]
commands = [["pre-commit", { replace = "posargs", default = ["run", "--all-files"], extend = true} ]]

[tool.tox.env.type]
description = "run type check (pyright)"
groups = ["all"]
commands = [
    ["pyright", { replace = "posargs", extend = true}],
]

[tool.alembic]
script_location = "modmail/backends/sql/migrations"
prepend_sys_path = ["."]

[[tool.alembic.post_write_hooks]]
name = "ruff-format"
type = "module"
module = "ruff"
options = "format REVISION_SCRIPT_FILENAME"

[[tool.alembic.post_write_hooks]]
name = "ruff-check"
type = "module"
module = "ruff"
options = "check --fix REVISION_SCRIPT_FILENAME"