diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 0000000..d091310 --- /dev/null +++ b/.coveragerc @@ -0,0 +1,23 @@ +[run] +branch = True +source = paperspec +relative_files = True + +[report] +fail_under = 90 +precision = 1 +show_missing = True +skip_covered = True +skip_empty = True +exclude_also = + if TYPE_CHECKING: + raise NotImplementedError + @(abc\.)?abstractmethod + if __name__ == .__main__.: + \.\.\.$ + +[html] +directory = htmlcov + +[xml] +output = coverage.xml diff --git a/.editorconfig b/.editorconfig index 5609304..61d52f9 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,81 +1,20 @@ -# EditorConfig: https://editorconfig.org -# In VS Code, install the "EditorConfig for VS Code" extension (EditorConfig.EditorConfig). - +# https://editorconfig.org root = true [*] charset = utf-8 end_of_line = lf -indent_style = space -indent_size = 4 insert_final_newline = true trim_trailing_whitespace = true - -[*.{py,pyi}] -indent_size = 4 -max_line_length = 88 - -[*.{mojo,🔥}] -indent_size = 4 -max_line_length = 88 - -[*.rs] -indent_size = 4 -max_line_length = 100 - -[{Cargo.toml,Cargo.lock,rustfmt.toml,.rustfmt.toml,clippy.toml}] -indent_size = 4 - -[{mojoproject.toml,pixi.toml,pixi.lock}] -indent_size = 4 - -[*.{yml,yaml}] -indent_size = 2 - -[*.{json,jsonc,json5}] -indent_size = 2 - -[*.sql] indent_style = space -indent_size = 2 - -[*.{js,jsx,mjs,cjs,ts,tsx,css,scss,less,html,vue,svelte}] -indent_size = 2 - -[*.{toml,ini,cfg}] indent_size = 4 -[*.xml] +[*.{yml,yaml,json,toml,md}] indent_size = 2 -[*.{md,markdown}] -indent_size = 2 +[*.md] trim_trailing_whitespace = false -[*.{sh,bash,zsh}] -indent_size = 2 - -[{Makefile,makefile,*.mk}] -indent_style = tab - -[*.go] -indent_style = tab - -[*.{bat,cmd,ps1}] -end_of_line = crlf - -[{Dockerfile,Dockerfile.*,*.dockerfile}] -indent_size = 4 - -[*.{tf,tfvars,hcl}] -indent_size = 2 - -[LICENSE*] +[*.{csv,tsv}] +trim_trailing_whitespace = false insert_final_newline = false - -[*.{diff,patch}] -trim_trailing_whitespace = false - -[*.min.{js,css}] -insert_final_newline = unset -trim_trailing_whitespace = unset diff --git a/.gitattributes b/.gitattributes index 7d23aca..2c3e1b3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,7 +1,14 @@ +# Normalize line endings; keep data files byte-for-byte. * text=auto eol=lf -# Generated data: exact bytes matter, and diffs are by line. +*.csv -text +*.tsv -text +*.gz binary +# Scripts must keep LF endings to run. +*.sh text eol=lf +# Gitea (and GitHub): collapse generated files in diffs, keep pixi.lock out of language stats. +pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff +# paperspec-specific: generated data whose exact bytes matter (the broken packages include CRLF and +# empty files on purpose), diffed by line. vectors/** -text diff fixtures/** -text diff fixtures/**/*.png binary -# The pixi lock file: generated, highlighted as YAML, never merged line by line. -pixi.lock merge=binary linguist-language=YAML linguist-generated=true diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml deleted file mode 100644 index 7d34f8e..0000000 --- a/.gitea/workflows/check.yml +++ /dev/null @@ -1,21 +0,0 @@ -# Forgejo and Gitea Actions both read .github/workflows when their own folder is absent. -# On Forgejo, if the runner's default action mirror lacks setup-pixi, write it as -# https://github.com/prefix-dev/setup-pixi@v0.9.4. -# The tools need Python 3.14, which pixi.toml pins, so one environment covers every supported Python. -name: check -on: - push: - branches: [main] - pull_request: - -jobs: - check: - runs-on: linux-base - container: - image: git.scient.ing/infra/linux-base:26.10.7 - steps: - - uses: actions/checkout@v4 - - name: Check the repository - run: pixi run check - - name: Stress the reference implementation - run: pixi run stress diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..94e9b89 --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,50 @@ +# Continuous integration on Gitea Actions. +# +# Runner labels: `linux-base` is the label of this studio's runner. If your +# runner registers different labels, change the `os` matrix. +# Forgejo and Gitea Actions both read .github/workflows when their own folder is absent. +# On Forgejo, if the runner's default action mirror lacks setup-pixi, write it as +# https://github.com/prefix-dev/setup-pixi@v0.9.4. +# The checks need Python 3.14, which pixi.toml pins, so one environment covers every supported Python. +name: ci +on: + push: + branches: [main, dev] + pull_request: + workflow_dispatch: + +# Cancels superseded runs on the same branch (Gitea 1.26+; older versions do +# not cancel). +concurrency: + group: ${{ gitea.workflow }}-${{ gitea.event_name }}-${{ gitea.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + check: + strategy: + fail-fast: false + matrix: + os: [linux-base] + runs-on: ${{ matrix.os }} + # pixi comes with the job image, as in the site and publish workflows. + container: + image: git.scient.ing/infra/linux-base:26.10.7 + timeout-minutes: 30 + env: + PYTEST_ADDOPTS: --maxfail=0 # report every failure in CI + steps: + - uses: actions/checkout@v4 + - run: pixi run fmt-check + - run: pixi run lint + - run: pixi run typecheck + - run: pixi run cov + # paperspec-specific: the repository checks the oracle exists to run. + - name: Lint the Markdown + run: pixi run lint-md + - name: Check the repository + run: pixi run verify + - name: Stress the reference implementation + run: pixi run stress diff --git a/.gitignore b/.gitignore index 580ba05..bea8c5f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,17 +1,18 @@ -__pycache__/ -*.pyc -*.db -*.db.assets/ - -# the package version, written by setuptools-scm when the package is built or installed -/src/paperspec/_version.py - -# the website, built by `paperspec site` -/_site/ - -# pixi environments +# Project +.venv/ .pixi/* !.pixi/config.toml +.hypothesis/ +.coverage +htmlcov/ +dist/ +coverage.xml +*.egg-info/ +logs/ +.env +!.env.example +# Claude Code personal settings (sandbox, hooks) +.claude/settings.local.json # Created by https://www.toptal.com/developers/gitignore/api/osx,python,pycharm,windows,visualstudio,visualstudiocode,zsh,jetbrains,jupyternotebooks @@ -255,7 +256,6 @@ venv/ ENV/ env.bak/ venv.bak/ -.claude # Spyder project settings .spyderproject @@ -761,7 +761,19 @@ FodyWeavers.xsd # End of https://www.toptal.com/developers/gitignore/api/osx,python,pycharm,windows,visualstudio,visualstudiocode,zsh,jetbrains,jupyternotebooks -# The Visual Studio rules above ignore every packages/ and log/ folder; these hold fixtures that `paperspec check` -# compares byte for byte, so keep them. +# paperspec-specific + +# SQLite databases that `paperspec load` writes, and the folder of asset files beside each +*.db +*.db.assets/ + +# the package version, written by setuptools-scm when the package is built or installed +/src/paperspec/_version.py + +# the website, built by `paperspec site` +/_site/ + +# the Visual Studio rules above ignore every packages/ and log/ folder; these hold fixtures that +# `paperspec check` compares byte for byte, so keep them !/fixtures/packages/* !/fixtures/records/log/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a033876 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,45 @@ +# Install once with `pixi run hooks`. Ruff and ty run through pixi so hooks use +# exactly the same versions and settings as `pixi run check`. +# Test fixtures are deliberately messy inputs, so hooks leave them alone. +exclude: ^tests/fixtures/ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: check-added-large-files + args: [--maxkb=1000] + - id: check-merge-conflict + - id: check-toml + - id: check-yaml + exclude: ^src/.*\.ya?ml$ + - id: end-of-file-fixer + exclude: \.(csv|tsv)$ + - id: trailing-whitespace + exclude: \.(csv|tsv|md)$ + - id: mixed-line-ending + args: [--fix=lf] + + - repo: https://github.com/python-jsonschema/check-jsonschema + rev: 0.38.2 + hooks: + - id: check-github-workflows + files: ^\.gitea/workflows/.+\.ya?ml$ + + - repo: local + hooks: + - id: ruff-format + name: ruff format + entry: pixi run ruff format + language: system + types_or: [python, pyi] + - id: ruff-check + name: ruff check + entry: pixi run ruff check --fix --exit-non-zero-on-fix + language: system + types_or: [python, pyi] + - id: ty + name: ty check + entry: pixi run ty check + language: system + types: [python] + pass_filenames: false diff --git a/.pytest.ini b/.pytest.ini new file mode 100644 index 0000000..77fc60b --- /dev/null +++ b/.pytest.ini @@ -0,0 +1,51 @@ +[pytest] +minversion = 8.4 +required_plugins = pytest-cov hypothesis +testpaths = + tests + src +# Lets tests import shared helpers (conftest constants, fakes) directly. +pythonpath = tests +norecursedirs = + *.egg + .eggs + dist + build + docs + .tox + .git + .pixi + .venv + node_modules + __pycache__ + .hypothesis + .pytest_cache + .ruff_cache + htmlcov +python_files = test_*.py +doctest_optionflags = + NUMBER + NORMALIZE_WHITESPACE + IGNORE_EXCEPTION_DETAIL + ELLIPSIS +# The default run skips the slow and networked suites; `-m live` on the +# command line replaces this selection. +addopts = + --strict-markers + --strict-config + --import-mode=importlib + --tb=short + --doctest-modules + --doctest-continue-on-failure + --maxfail=2 + -ra + -m "not live" +markers = + live: hits real public services; needs network (and any API keys it names) +xfail_strict = true +empty_parameter_set_mark = fail_at_collect +# Turn every warning into an error so deprecations surface immediately. +filterwarnings = + error +# Dump tracebacks of all threads if a single test hangs this long. +faulthandler_timeout = 300 diff --git a/.ruff.toml b/.ruff.toml new file mode 100644 index 0000000..c54b9f2 --- /dev/null +++ b/.ruff.toml @@ -0,0 +1,120 @@ +# Ruff linter + formatter. https://docs.astral.sh/ruff/settings/ +target-version = "py314" +line-length = 88 +indent-width = 4 +src = ["src", "tests"] +required-version = ">=0.14" + +# Ruff already skips .git, .venv, venv, build, dist, caches, node_modules, +# site-packages, and the other usual suspects (`ruff check --show-settings`), +# and respects .gitignore. Only list what is specific to this project. +extend-exclude = [".pixi", "htmlcov"] + +[lint] +preview = true +# Preview *behavior* is on, but preview-only rules must be selected by code, +# so upgrading ruff never silently turns on unstable rules. +explicit-preview-rules = true +select = [ + "F", # pyflakes + "E", # pycodestyle errors + "W", # pycodestyle warnings + "I", # isort + "N", # pep8-naming + "D", # pydocstyle + "UP", # pyupgrade + "ANN", # annotations + "S", # bandit (security) + "BLE", # blind except + "FBT", # boolean traps + "B", # bugbear + "C4", # comprehensions + "DTZ", # timezone-aware datetimes + "T20", # print statements + "PT", # pytest style + "RET", # return statements + "SIM", # simplify + "TID", # tidy imports + "ARG", # unused arguments + "PTH", # prefer pathlib + "ERA", # commented-out code + "PGH", # pygrep hooks (specific noqa / type: ignore codes) + "PL", # pylint + "TRY", # tryceratops + "PERF", # performance + "LOG", # logging + "G", # logging format strings + "PIE", # misc lints + "INP", # implicit namespace packages + "RUF", # ruff-specific +] +ignore = [ + "D105", # magic-method docstrings + "D107", # __init__ docstrings (documented on the class) + "PLR0911", # too many returns: decision tables read best flat + "PLR0912", # too many branches: same + "PLR0913", # too many arguments: config-driven constructors + "PLR0915", # too many statements: same + "PLR0917", # too many positional arguments + "PLR2004", # magic values: thresholds live in config + "TRY003", # long exception messages are deliberate + "ANN401", # Any is used for raw API payloads + "FBT001", # boolean positional args in small helpers + "FBT002", +] +fixable = ["ALL"] +dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" + +[lint.per-file-ignores] +"tests/**/*.py" = [ + "S101", # assert is the point of tests + "D", # test docstrings are optional + "ANN", # fixtures and tests need no annotations + "INP001", # tests are not a package + "ARG", # fixtures are often requested only for side effects + "FBT", + "PLR2004", + "PLC0415", # local imports keep heavy fixtures lazy + "S105", + "S106", + "S311", # pseudo-random data is fine in tests + "S603", # tests drive git with fixed argument lists + "S607", + "DTZ", + "E501", # dense fixtures + "PT018", + "BLE001", # deliberate fault injection + "T20", +] +"src/paperspec/cli.py" = ["T201"] # the CLI prints by design +"**/__init__.py" = ["F401"] # re-exports +"src/paperspec/cli/*.py" = ["T201"] # paperspec-specific: the commands are a package, and they print by design + +[lint.pycodestyle] +# The formatter wraps code at 88; allow unbreakable strings/URLs up to 100. +max-line-length = 100 + +[lint.pydocstyle] +convention = "google" + +[lint.isort] +known-first-party = ["paperspec"] +combine-as-imports = true + +[lint.flake8-tidy-imports] +ban-relative-imports = "all" + +[lint.flake8-pytest-style] +fixture-parentheses = false +mark-parentheses = false + +[lint.flake8-annotations] +allow-star-arg-any = true + +[format] +quote-style = "double" +indent-style = "space" +skip-magic-trailing-comma = false +line-ending = "lf" +docstring-code-format = true +docstring-code-line-length = "dynamic" diff --git a/pyproject.toml b/pyproject.toml index 77e6ff1..cf55f23 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,10 @@ +# Package metadata only, and the build mapping setuptools needs. Tool settings live in their own files: +# pixi.toml (environments + tasks), .ruff.toml (lint/format), ty.toml (types), .pytest.ini (tests), +# .coveragerc (coverage). +# Deviation from the studio standard: setuptools with setuptools-scm instead of hatchling with hatch.toml. +# The package maps schemas/, sql/ and vectors/ from the repository root as data subpackages, and takes its +# version from git tags. + [build-system] requires = ["setuptools>=80", "setuptools-scm>=8"] build-backend = "setuptools.build_meta" @@ -40,6 +47,19 @@ Homepage = "https://paperspec.scient.ing" Repository = "https://git.scient.ing/infra/paperspec" Documentation = "https://paperspec.scient.ing/docs/" +# PEP 735 dependency groups (pip >= 25.1: `pip install -e ".[tools]" --group dev`). +# pixi.toml mirrors these for conda-forge environments. The tests need the `tools` extra as well. +[dependency-groups] +test = ["pytest>=8.4", "pytest-cov>=6", "hypothesis>=6.130"] +lint = ["ruff>=0.17.1,<0.18", "ty>=0.0.89,<0.0.90"] +dev = [ + { include-group = "test" }, + { include-group = "lint" }, + "pre-commit>=4", + "build>=1.2", + "twine>=6.1", +] + # The code is `src/paperspec`. The schemas, SQL and vectors stay at the repository root, where the # specification links to them and the website serves the schemas at their `$id` URLs, and travel with the # package as data subpackages, so a consumer reads them with importlib.resources. That mapping is why the diff --git a/ty.toml b/ty.toml new file mode 100644 index 0000000..a451f30 --- /dev/null +++ b/ty.toml @@ -0,0 +1,17 @@ +# ty type checker. https://docs.astral.sh/ty/reference/configuration/ +[environment] +python-version = "3.14" +python-platform = "all" + +[src] +include = ["src"] + +[rules] +possibly-unresolved-reference = "error" +possibly-missing-attribute = "error" +possibly-missing-import = "error" +unused-ignore-comment = "error" +redundant-cast = "error" + +[terminal] +error-on-warning = true