pyproject.toml

[project]
name = "prairielearn"
version = "0.0.0"
readme = "README.md"
requires-python = ">=3.13,<3.14"
classifiers = ["Private :: Do Not Upload"]

dependencies = [
  "ansi2html==1.9.2",
  "automata-lib==9.2.0",
  "chevron==0.14.0",
  "coloraide==8.8.1",
  "faker==40.15.0",
  "jinja2==3.1.6",
  "lxml==6.1.0",
  "matplotlib==3.10.9",
  "networkx==3.6.1",
  "nltk==3.9.4",
  "numpy==2.4.4",
  "openpyxl==3.1.5",
  "pandas==2.3.3",
  "pillow==12.2.0",
  "pint==0.25.3",
  "psutil==7.2.2",
  "pulp==3.3.0",
  "pyarrow==24.0.0",
  "pycryptodome==3.23.0",
  "pygments==2.20.0",
  "pygments-ansi-color==0.3.0",
  "pygraphviz==1.14",
  "pyquaternion==0.9.9",
  "regex==2026.4.4",
  "requests==2.33.1",
  "rich==15.0.0",
  "schemdraw==0.22",
  "scikit-learn==1.8.0",
  "scipy==1.17.1",
  "seaborn==0.13.2",
  "sketchresponse==0.1.4",
  "statsmodels==0.14.6",
  "sympy==1.14.0",
  "text-unidecode==1.3",
  "typing-extensions==4.15.0",
  "tzlocal==5.3.1",
]

[dependency-groups]
dev = [
  "pandas-stubs==2.3.3.260113",
  "pytest==9.0.3",
  "pytest-cov==7.1.0",
  "pytest-github-actions-annotate-failures==0.4.0",
  "pytest-repeat==0.9.4",
  "ruff==0.15.12",
  "sqlfluff==4.1.0",
  "squawk-cli==2.49.0",
  "types-chevron==0.14.2.20260408",
  "types-lxml==2026.2.16",
  "types-pygments==2.20.0.20260408",
]

docs = [
  "jsonschema2md==1.7.0",
  "mdx-truly-sane-lists==1.3",
  "mkdocs==1.6.1",
  "mkdocs-d2-plugin==1.7.0",
  "mkdocs-exclude==1.0.2",
  "mkdocs-gen-files==0.6.1",
  "mkdocs-literate-nav==0.6.3",
  "mkdocs-material==9.7.6",
  "mkdocstrings==1.0.4",
  "mkdocstrings-python==2.0.3",
  "pymdown-extensions==10.21.2",
  # https://github.com/pygments/pygments/issues/3076
  "pygments==2.20.0",
  # mkdocstrings-python will format the docstrings using ruff
  # https://mkdocstrings.github.io/python/usage/configuration/signatures/#line_length
  "ruff==0.15.12",
]

# We only use pyproject.toml for the Python dependencies, so we don't need to
# specify any packages / source files.
[tool.setuptools]
packages = []

[tool.ruff]
include = ["**/*.py"]

extend-exclude = [
  # These files are intentionally not parseable as Python.
  "./exampleCourse/questions/demo/autograder/codeUpload/submitted_code_samples/fib_error_binary_file/fib.py",
  "./exampleCourse/questions/demo/autograder/codeUpload/submitted_code_samples/fib_error_large_text_file/fib.py",
  # Files related to the Python autograder will often intentionally appear
  # broken in isolation. We'll exclude these files from linting.
  "exampleCourse/questions/**/tests/initial_code.py",
  "exampleCourse/questions/**/tests/trailing_code.py",
]
target-version = "py313"
preview = true
[tool.ruff.lint]
select = ["ALL"]

ignore = [
  # These rules provide little value to us
  "BLE",     # flake8-blind-except
  "COM",     # flake8-commas
  "CPY001",  # missing-copyright-notice
  "C901",    # mccabe (complexity checks)
  "ERA",     # eradicate (code in comments)
  "EM",      # flake8-errmsg
  "EXE",     # flake8-executable
  "E501",    # line-too-long
  "FIX",     # flake8-fixme
  "INP001",  # implicit-namespace-package
  "S",       # flake8-bandit (security rules)
  "SLF001",  # private-member-access
  "T201",    # flake8-print
  "T100",    # flake8-debugger
  "TD",      # flake8-todos
  "PGH003",  # blanket-type-ignore
  "PLE2513", # invalid-character-esc
  "PTH",     # flake8-use-pathlib

  # These rules were discussed and disabled
  "ANN401",  # any-type
  "D107",    # undocumented-public-init
  "D203",    # incorrect-blank-line-before-class
  "D212",    # multi-line-summary-first-line
  "D205",    # missing-blank-line-after-summary (we use a multi-line description instead of summaries sometimes)
  "D400",    # missing-trailing-period
  "D415",    # missing-terminal-punctuation
  "DOC402",  # docstring-missing-yields
  "FURB101", # read-whole-file
  "FURB103", # write-whole-file
  "FURB118", # reimplemented-operator (confusing)
  "FURB140", # reimplemented-starmap (confusing)
  "ISC003",  # explicit-string-concatenation
  "NPY002",  # numpy-legacy-random (we use `np.random.*` in many places)
  "PLC0415", # import-outside-top-level
  "PLC1901", # compare-to-empty-string
  "PLC2701", # import-private-name
  "PLR1702", # too-many-nested-blocks
  "PLR0911", # too-many-return-statements
  "PLR0912", # too-many-branches
  "PLR0913", # too-many-arguments
  "PLR0914", # too-many-locals
  "PLR0915", # too-many-statements
  "PLR0916", # too-many-boolean-expressions
  "PLR0917", # too-many-positional-arguments
  "PLR6201", # literal-membership (pyright doesn't understand assert_never with sets)
  "PLR2004", # magic-value-comparison
  "PLR6301", # no-self-use
  "PLW1514", # unspecified-encoding
  "RET503",  # implicit-return
  "RET504",  # unnecessary-assign
  "RET505",  # superfluous-else-return
  "SIM108",  # if-else-block-instead-of-if-exp
  "TC006",   # runtime-cast-value
  "TRY300",  # try-consider-else (returns in try blocks)
  "TRY301",  # raise-within-try
  "TRY003",  # raise-vanilla-args (long messages in raise statements)

  # These rules need to be enabled
  # TODO: D103,D104 (https://github.com/astral-sh/ruff/issues/12434)
  "D101", # undocumented-public-class
  "D102", # undocumented-public-method
]

[tool.ruff.lint.pydocstyle]
# Default for mkdocstrings (https://mkdocstrings.github.io/python/usage/configuration/docstrings)
convention = "google"

[tool.ruff.lint.per-file-ignores]
# Files related to the Python autograder will often intentionally appear
# broken in isolation. We'll allow specific errors in these files to
# account for that.
#
# - F401: module imported but unused
# - F821: undefined name
# - F841: local variable name is assigned to but never used
# - ARG001: Unused function argument
"exampleCourse/questions/**/tests/setup_code.py" = ["F401", "F821"]
"exampleCourse/questions/**/tests/leading_code.py" = ["F401", "F821", "F841", "ARG001"]
"exampleCourse/questions/**/tests/ans.py" = ["F821"]
"exampleCourse/questions/demo/autograder/codeUpload/submitted_code_samples/**/*.py" = ["ARG001"]

# Ignore uppercase variables and function parameters (e.g. G for a graph)
"exampleCourse/questions/**/*.py" = ["N806", "N803"]
# The zygote specifically uses imports in strange places to facilitate the
# preloading of commonly-used modules.
"zygote.py" = ["E402", "F401"]
"apps/prairielearn/elements/**/*.py" = [
  # Ignore uppercase function parameters (e.g. G for a graph)
  "N803",
  # Allow boolean trap pattern in method signatures
  "FBT001",
  "FBT002",
  "FBT003",
  # ignore unused parameters in functions
  "ARG",
  "D100",
  "D103",
]
"apps/prairielearn/python/**/*.py" = ["N803"]
# Do not require self in method params
"apps/prairielearn/elements/pl-drawing/elements.py" = ["N805"]
"exampleCourse/elementExtensions/pl-drawing/example-logo/example-logo.py" = ["N805"]

"graders/**/*.py" = [
  # Boolean default positional argument
  "FBT002",
  # Avoid future changes to graders
  "C419",
  "PYI061",
  "RUF036",
  # Strict annotation linting
  "D",
  "DOC",
]

# Directories we don't want strict annotation linting or docstring linting on
# For example, code with no public API, elements with known issues, or course content.
"apps/prairielearn/python/zygote.py" = ["D100", "D101", "D103", "DOC201"]
"apps/prairielearn/python/prairielearn/internal/**/*.py" = ["D100", "D103", "DOC201"]
"docs/**/*.py" = ["D100", "DOC201"]
"apps/prairielearn/src/tests/**/*.py" = ["ANN", "D100", "D103", "DOC201"]
"apps/prairielearn/**/*_test.py" = ["ANN", "D", "PLR0904"]
"apps/prairielearn/python/test/**/*.py" = ["D"]
"contrib/**/*.py" = ["ANN", "D", "DOC201"]
"scripts/**/*.py" = ["D100", "DOC"]
"testCourse/**/*.py" = ["ANN", "D100", "D103", "DOC"]
"exampleCourse/**/*.py" = ["ANN", "D", "DOC"]
"apps/prairielearn/elements/pl-drawing/**/*.py" = ["ANN"]
"apps/prairielearn/elements/pl-prairiedraw-figure/**/*.py" = ["ANN"]
"apps/prairielearn/elements/pl-checkbox/**/*.py" = ["ANN"]
# Issues rebuilding workspace
"workspaces/jupyterlab-base/jupyter_server_config.py" = ["PLW1508"]

[tool.ruff.lint.pydoclint]
# Skip docstrings which fit on a single line.
ignore-one-line-docstrings = true

[tool.ruff.format]
exclude = [
  "./exampleCourse/questions/demo/autograder/python/leadingTrailing/tests/trailing_code.py",
  "./exampleCourse/questions/demo/autograder/python/square/tests/initial_code.py",
]

[tool.pyright]
venvPath = "."
venv = ".venv"
typeCheckingMode = "strict"
include = [
  "./apps/prairielearn/elements",
  "./apps/prairielearn/python",
  "./exampleCourse/questions/**/server.py",
  "./contrib/question_converters/canvas",
  "./graders",
  "./scripts",
]
ignore = [
  "./apps/prairielearn/elements/pl-drawing",            # requires refactor
  "./apps/prairielearn/elements/pl-prairiedraw-figure", # deprecated
  "./exampleCourse/questions/**/tests",                 # autograder tests, use different dependencies
]
extraPaths = ["./apps/prairielearn/python"]
pythonVersion = "3.13"
executionEnvironments = [
  # TODO: after https://github.com/tamasfe/taplo/issues/332, split with newlines
  { root = "./graders/python", reportUntypedNamedTuple = "none", reportUntypedFunctionDecorator = "none", reportUnnecessaryComparison = "none", reportUnnecessaryIsInstance = "none", reportMissingTypeArgument = "none", extraPaths = [
  ] },
  { root = "./graders/c", reportArgumentType = "none", reportOperatorIssue = "none", reportAttributeAccessIssue = "none", reportIndexIssue = "none", reportCallIssue = "none", reportMissingTypeArgument = "none", extraPaths = [
  ] },
  { root = "./exampleCourse/questions", reportArgumentType = "none", reportUnknownParameterType = "none", reportMissingParameterType = "none", reportOperatorIssue = "none", reportCallIssue = "none", reportConstantRedefinition = "none" },
]
reportUnnecessaryTypeIgnoreComment = "error"
# These rules would require significant changes
reportUnknownMemberType = "none"
reportUnknownArgumentType = "none"
reportUnknownVariableType = "none"
# These rules don't provide much value
reportPrivateUsage = "none"
reportUnnecessaryIsInstance = "none"
reportUnknownLambdaType = "none"
# These rules require improved upstream type annotations
reportMissingTypeStubs = "none"
reportMissingTypeArgument = "none"
reportOperatorIssue = "information"
reportUnknownParameterType = "information"

[tool.pytest]
pythonpath = ["apps/prairielearn/python"]
addopts = ["--cov=apps"]
testpaths = [
  "apps/prairielearn/elements",
  "apps/prairielearn/python/test",
  "graders/python/python_autograder/tests",
]

[tool.uv]
required-version = ">=0.9.0"
# Ensures that all dependencies are installed whenever we use `uv run`.
default-groups = "all"