[project]

# basic information, URLs down below because toml doesn't let you define the same table twice

name = "myproject"

version = "0.5.4"

description = "template for python projects/packages"

authors = [

{ name = "Michael Ivanitskiy", email = "[email protected]" }

]

readme = "README.md"

requires-python = ">=3.9"

# dependencies

dependencies = [

"numpy>=1.21.0",

"torch>=1.13.0",

"muutils>=0.7.0",

"ipykernel>=6.29.5",

]

[project.optional-dependencies]

# handling torch

# torch-cu124 = [ "torch>=1.13.0" ]

# for example purposes only

cli = [

"fire>=0.6.0",

]

[dependency-groups]

dev = [

# test

"pytest>=8.2.2",

# coverage

"pytest-cov>=4.1.0",

# yaml validation

"pyyaml>=6.0",

# type checking

"mypy>=1.0.1",

"ty",

"basedpyright",

# docs

'pdoc>=14.6.0',

"nbconvert>=7.16.4", # for notebooks

# lmcat -- a custom library. not exactly docs, but lets an LLM see all the code

"lmcat>=0.2.0; python_version >= '3.11'",

# tomli since no tomlib in python < 3.11

"tomli>=2.1.0; python_version < '3.11'",

# twine

"twine",

# jinja2 vuln, see

# https://github.com/mivanit/python-project-makefile-template/security/dependabot/4

"jinja2>=3.1.6",

]

lint = [

# lint

"ruff>=0.4.8",

]

# more project metadata

[project.urls]

Homepage = "https://miv.name/python-project-makefile-template"

Documentation = "https://miv.name/python-project-makefile-template"

Repository = "https://github.com/mivanit/python-project-makefile-template"

Issues = "https://github.com/mivanit/python-project-makefile-template/issues"

# uv

[tool.uv]

default-groups = ["dev", "lint"]

# [tool.uv.sources]

# torch = [ { index = "pytorch-cu124", extra = "torch-cu124" } ]

# [[tool.uv.index]]

# name = "pytorch-cu124"

# url = "https://download.pytorch.org/whl/cu124"

# explicit = true

[build-system]

requires = ["hatchling"]

build-backend = "hatchling.build"

# mypy config

[tool.mypy]

files = ["scripts/make"]

exclude = [

".*/__pycache__/.*",

"docs/.*",

"scripts/out/.*",

".meta/scripts/.*",

".venv/.*",

".mypy_cache/.*",

".ruff_cache/.*",

]

# ruff config

[tool.ruff]

exclude = [

"__pycache__",

".meta/scripts",

"scripts/out",

]

[tool.ruff.format]

indent-style = "tab"

skip-magic-trailing-comma = false

[tool.ruff.lint]

ignore = [

"COM812", # ????

"F722", # doesn't like jaxtyping

"W191", # we like tabs

"D400", # missing-trailing-period

"D415", # missing-terminal-punctuation

"E501", # line-too-long

"S101", # assert is fine

"D403", # first-word-uncapitalized

"D206", # docstring-tab-indentation

"ERA001", # commented-out-code

"T201", # print is fine lmao

"C408", # calling dict() is fine

"UP015", # we like specifying the mode even if it's the default

"D300", # we like docstrings

# boolean positional arguments are fine

"FBT001",

"FBT002",

"FBT003",

"PTH123", # opening files is fine

"RET505", # else return is fine

"FIX002", # `make todo` will give us the TODO comments

"PIE790", # be explicit about when we pass

"EM101", # fine to have string literal exceptions

"FURB129", # .readlines() is fine

"SIM108", # ternary operators can be hard to read, choose on a case-by-case basis

"PLR5501", # nested if else is fine, for readability

"D203", # docstring right after the class

"D213", # docstring on first line

"NPY002", # legacy numpy generator is fine

"D401", # dont care about imperative mood

# todos:

"TD001", # we allow tags besides "TODO"

"TD002", # dont care about author

"TD003", # `make todo` will give us a table where we can create issues

"FIX001", # FIXME comments are ok since `make todo` handles them

"PLR0913", # sometimes you have to have a lot of args

"B028", # fine to omit stacklevel on warnings

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# only for old version compatibility

"UP007", # `Optional` is ok, we might not want to use `|` for compatibility

# old style hints `Tuple`, `List`, etc. are fine

"UP006",

"UP035",

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# delete this section!

"INP001", # this isn't a package, just some scripts

"PGH003", # bare type ignore is fine

"SLF001", # private member access is fine

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

]

select = ["ALL"]

# select = ["ICN001"]

[tool.ruff.lint.per-file-ignores]

"scripts/make/*" = [

"PLR2004", # magic values (coverage thresholds are self-documenting)

"RET504", # unnecessary assignment before return

"TRY003", # long exception messages

"TRY300", # return in else block

"BLE001", # blind exception catch (appropriate for CLI main())

"D103", # missing docstring in main()

"PTH109", # os.getcwd() vs Path.cwd()

"PTH100", # os.path.abspath() vs Path.resolve()

]

"tests/*" = [

# dont need docstrings in test functions, methods, or modules

"D103",

"D100",

"D102",

"INP001", # dont need __init__ either

# dont need type annotations in test functions

"ANN001",

"ANN201",

"ANN202",

"TRY003", # long exception messages in tests are fine

# subprocess calls in tests use trusted inputs and partial paths

"S603",

"S607",

]

"docs/*" = ["ALL"] # not our problem

"**/*.ipynb" = [

"D103", # dont need docstrings

"PLR2004", # magic variables are fine

"N806", # uppercase vars are fine

]

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# delete this!

# we use trailing whitespace intentionally in the markdown template

"scripts/make/get_todos.py" = ["W291"]

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# basedpyright config

[tool.basedpyright]

include = ["scripts/make"]

exclude = [

".meta/scripts",

"scripts/out",

".venv",

"docs",

".mypy_cache",

".ruff_cache",

]

reportAny = "none"

reportUnusedCallResult = "none"

reportUnnecessaryIsInstance = "none"

reportExplicitAny = "none"

reportUnnecessaryTypeIgnoreComment = "none"

# ty config

[tool.ty.src]

include = ["scripts/make"]

exclude = [

".meta/scripts",

"scripts/out",

".venv",

"docs",

".mypy_cache",

".ruff_cache",

]

[tool.ty.rules]

unused-type-ignore-comment = "ignore"

unused-ignore-comment = "ignore"

# `make lmcat` depends on the lmcat and can be configured here

[tool.lmcat]

output = "docs/other/lmcat.txt" # changing this might mean it wont be accessible from the docs

ignore_patterns = [

"docs/**",

".venv/**",

".git/**",

".meta/**",

"uv.lock",

"LICENSE",

"scripts/out/",

]

# for configuring this tool (makefile, make_docs.py)

# ============================================================

[tool.makefile]

# documentation configuration, for `make docs` and `make docs-clean`

[tool.makefile.docs]

# Output directory for generated documentation

# MUST match DOCS_DIR in makefile

output_dir = "docs"

# List of files/directories in docs/ that should not be cleaned by `make docs-clean`

# These paths are relative to output_dir

no_clean = [

".nojekyll", # For GitHub Pages

# "resources/", # Templates, CSS, etc. this, or whatever is specified as DOCS_RESOURCES_DIR in makefile will always be preserved

]

# Increment level of markdown headings in generated documentation

# e.g. if 2, then h1 -> h3, h2 -> h4, etc.

markdown_headings_increment = 2

# Warnings to ignore during documentation generation

warnings_ignore = [

".*No docstring.*",

".*Private member.*",

]

# optional generation of notebooks as html pages

[tool.makefile.docs.notebooks]

# Enable notebook processing in documentation

# disabled by default

enabled = true

# Source directory containing .ipynb files

source_path = "notebooks"

# Output path relative to docs directory [tool.makefile.docs.output_dir]

output_path_relative = "notebooks"

# Custom template for notebooks index page

# Available variables: notebook_url, notebooks (list of dicts with ipynb, html, desc)

# index_template = ...

# Descriptions for notebooks, shown in index

[tool.makefile.docs.notebooks.descriptions]

"example" = "Example notebook showing basic usage"

"advanced" = "Advanced usage patterns and techniques"

# Dependency export configurations for `make dep`

# Generates requirements files in .meta/requirements/

# See README.md "Configuration Reference" for full documentation

[tool.makefile.uv-exports]

# Global args passed to ALL uv export commands

args = ["--no-hashes"]

# Each entry generates a requirements file

# Fields:

# name (required): alphanumeric identifier, generates "requirements-{name}.txt"

# groups: true=all, false=none, ["dev"]=specific groups from [dependency-groups]

# extras: true=all, false/[]=none, ["cli"]=specific from [project.optional-dependencies]

# filename: override output filename

# options: raw args passed to uv export

exports = [

# Base dependencies only (from [project.dependencies])

{ name = "base", groups = false, extras = false },

# All dependency groups (dev, lint), no extras

{ name = "groups", groups = true, extras = false },

# Only the lint group using raw uv options

{ name = "lint", options = ["--only-group", "lint"] },

# Everything with custom filename

{ name = "all", filename="requirements.txt", groups = true, extras=true },

# Alternative way to get all extras

{ name = "allalt", groups = true, options = ["--all-extras"] },

]

# TODO extraction settings for `make todo`

# Finds TODO/FIXME/BUG comments and generates reports

# See README.md "Configuration Reference" for full documentation

[tool.makefile.inline-todo]

# Root directory to search

search_dir = "."

# Base path for output files (without extension)

# Generates: .jsonl, -standard.md, -table.md, .html

out_file_base = "docs/other/todo-inline"

# Lines of context before/after each TODO

context_lines = 2

# File extensions to scan (without dots)

extensions = ["py", "md"]

# Comment tags to search for (case-sensitive)

# Must be surrounded by boundary chars (space, colon, brackets, etc.)

tags = ["CRIT", "TODO", "FIXME", "HACK", "BUG", "DOC"]

# Glob patterns to exclude

exclude = [

"docs/**",

".venv/**",

"scripts/get_todos.py",

]

# Git branch for GitHub code links

branch = "main"

# Repository URL (auto-detected from [project.urls.Repository])

# repo_url = "https://github.com/user/repo"

# Map tags to GitHub issue labels

# Tags not listed use the tag name as label

# Defaults: CRIT/FIXME/BUG → "bug", TODO/HACK → "enhancement"

[tool.makefile.inline-todo.tag_label_map]

"CRIT" = "bug"

"BUG" = "bug"

"FIXME" = "bug"

"TODO" = "enhancement"

"HACK" = "enhancement"

"DOC" = "documentation"

# ============================================================