# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """The `paperspec` command: parsing, help, usage errors, exit statuses and `python -m paperspec`.""" import runpy import sys import pytest from conftest import ROOT from paperspec import UNICODE_VERSION, __version__, cli from paperspec.cli import main as cli_main from paperspec.package import ZIP_LIMIT COMMANDS = ["validate", "correct", "load", "check", "build", "stress", "site"] def run_main(argv, capsys): """Run `paperspec ARGV`, returning its exit status and the text it printed.""" try: status = cli_main.main(argv) except SystemExit as stop: status = stop.code captured = capsys.readouterr() return status, captured.out, captured.err class TestParser: def test_knows_every_command(self): _, subs = cli_main.parser() assert list(subs) == COMMANDS assert list(cli_main.COMMANDS) == COMMANDS def test_validate_takes_packages_a_proposal_file_and_a_size_limit(self): top, _ = cli_main.parser() args = top.parse_args( [ "validate", "--correction", "fix.json", "--max-size", "9", "a", "b.sct.zip", ] ) assert args.command == "validate" assert args.correction == "fix.json" assert args.max_size == 9 assert args.packages == ["a", "b.sct.zip"] def test_the_size_limit_defaults_to_the_zip_limit(self): top, _ = cli_main.parser() assert top.parse_args(["validate", "a"]).max_size == ZIP_LIMIT assert top.parse_args(["load", "--sqlite", "x.db", "a"]).max_size == ZIP_LIMIT def test_load_takes_the_bundle_options(self): top, _ = cli_main.parser() args = top.parse_args( [ "load", "--sqlite", "x.db", "--bundle", "--built-from", "4fa326d", "--store", "lab", "p", ] ) assert (args.sqlite, args.bundle, args.built_from, args.store) == ( "x.db", True, "4fa326d", "lab", ) def test_check_has_a_quick_flag(self): top, _ = cli_main.parser() assert top.parse_args(["check"]).quick is False assert top.parse_args(["check", "--quick"]).quick is True def test_build_and_site_take_an_output_folder(self): top, _ = cli_main.parser() assert top.parse_args(["build"]).out is None assert top.parse_args(["build", "--out", "o"]).out == "o" args = top.parse_args(["site", "--out", "o", "--base-url", "http://x"]) assert (args.out, args.base_url) == ("o", "http://x") def test_stress_takes_a_seed_and_a_round_count(self): top, _ = cli_main.parser() args = top.parse_args(["stress"]) assert (args.seed, args.rounds) == (20261014, 200) args = top.parse_args(["stress", "--seed", "7", "--rounds", "5"]) assert (args.seed, args.rounds) == (7, 5) class TestHelp: def test_the_top_help_lists_the_commands_and_where_they_work(self, capsys): status, out, _ = run_main(["--help"], capsys) assert status == 0 for name in COMMANDS: assert name in out assert "where each command works" in out assert cli_main.SITE in out @pytest.mark.parametrize("command", COMMANDS) def test_every_command_prints_its_own_help(self, command, capsys): status, out, _ = run_main([command, "--help"], capsys) assert status == 0 assert out.startswith(f"usage: paperspec {command}") assert "examples:" in out def test_validate_help_names_the_exit_statuses(self, capsys): _, out, _ = run_main(["validate", "--help"], capsys) assert "Exit status: 0 when everything is valid" in out assert str(ZIP_LIMIT) in out def test_the_version_names_the_package_and_unicode(self, capsys): status, out, _ = run_main(["--version"], capsys) assert status == 0 assert out.strip() == f"paperspec {__version__} (Unicode {UNICODE_VERSION})" def test_no_command_prints_the_help_and_exits_2(self, capsys): status, out, _ = run_main([], capsys) assert status == 2 assert "usage: paperspec" in out assert "examples:" in out class TestUsageErrors: def test_an_unknown_command_is_refused(self, capsys): status, _, err = run_main(["frobnicate"], capsys) assert status == 2 assert "invalid choice: 'frobnicate'" in err def test_a_misspelled_command_is_suggested(self, capsys): _, _, err = run_main(["validat", "x"], capsys) assert "validate" in err def test_an_unknown_option_is_refused(self, capsys): status, _, err = run_main(["check", "--fast"], capsys) assert status == 2 assert "unrecognized arguments: --fast" in err @pytest.mark.parametrize( ("argv", "missing"), [ (["validate"], "PACKAGE"), (["load", "x"], "--sqlite"), (["load", "--sqlite", "x.db"], "PACKAGE"), ], ) def test_a_missing_argument_is_refused(self, argv, missing, capsys): status, _, err = run_main(argv, capsys) assert status == 2 assert missing in err def test_a_size_limit_must_be_a_number(self, capsys): status, _, err = run_main(["validate", "--max-size", "big", "x"], capsys) assert status == 2 assert "invalid int value: 'big'" in err def test_a_usage_error_of_a_command_prints_its_usage_and_exits_2(self, capsys): status, _, err = run_main( ["validate", "--correction", "c.json", "a", "b"], capsys ) assert status == 2 assert err.startswith("usage: paperspec validate") assert "--correction checks proposals against exactly one package" in err class TestRun: def test_a_command_that_returns_nothing_exits_0(self, monkeypatch, capsys): monkeypatch.setattr("paperspec.cli.validate.run", lambda args: None) assert run_main(["validate", "x"], capsys)[0] == 0 def test_a_command_returns_its_own_status(self, monkeypatch, capsys): monkeypatch.setattr("paperspec.cli.validate.run", lambda args: 1) assert run_main(["validate", "x"], capsys)[0] == 1 def test_an_interrupt_exits_130(self, monkeypatch, capsys): def interrupted(args): raise KeyboardInterrupt monkeypatch.setattr("paperspec.cli.validate.run", interrupted) assert run_main(["validate", "x"], capsys)[0] == 130 def test_python_dash_m_runs_the_same_program(self, monkeypatch, capsys): monkeypatch.setattr(sys, "argv", ["paperspec", "--version"]) with pytest.raises(SystemExit) as stop: runpy.run_module("paperspec", run_name="__main__") assert stop.value.code == 0 assert capsys.readouterr().out.startswith(f"paperspec {__version__}") def test_python_dash_m_exits_with_the_status_of_main(self, monkeypatch, capsys): monkeypatch.setattr(sys, "argv", ["paperspec"]) with pytest.raises(SystemExit) as stop: runpy.run_module("paperspec", run_name="__main__") assert stop.value.code == 2 assert "usage: paperspec" in capsys.readouterr().out class TestRequire: def test_installed_packages_pass(self): assert cli.require("json", "os") is None def test_one_missing_package_is_named_with_what_to_install(self): with pytest.raises(SystemExit) as stop: cli.require("json", "no_such_package_here") message = str(stop.value.code) assert "needs the package no_such_package_here" in message assert "paperspec[tools]" in message assert cli.INSTALL in message def test_several_missing_packages_are_listed(self): with pytest.raises(SystemExit) as stop: cli.require("no_such_a", "no_such_b") assert "the packages no_such_a and no_such_b" in str(stop.value.code) class FakeCheckout: """A folder with the four marks of a paperspec checkout.""" def __init__(self, root): self.root = root (root / "spec").mkdir(parents=True) (root / "registry").mkdir() (root / "fixtures" / "src").mkdir(parents=True) (root / "pyproject.toml").write_text("") class TestCheckout: def test_an_editable_install_uses_the_checkout_it_is_in(self): assert cli.checkout() == str(ROOT) def test_an_installed_wheel_uses_the_nearest_checkout_above_the_current_folder( self, tmp_path, monkeypatch ): site = tmp_path / "site-packages" / "paperspec" / "cli" site.mkdir(parents=True) monkeypatch.setattr(cli, "__file__", str(site / "__init__.py")) repo = tmp_path / "repo" FakeCheckout(repo) inner = repo / "docs" / "deep" inner.mkdir(parents=True) monkeypatch.chdir(inner) assert cli.checkout() == str(repo.resolve()) def test_outside_any_checkout_it_says_what_to_do(self, tmp_path, monkeypatch): site = tmp_path / "site-packages" / "paperspec" / "cli" site.mkdir(parents=True) monkeypatch.setattr(cli, "__file__", str(site / "__init__.py")) elsewhere = tmp_path / "elsewhere" elsewhere.mkdir() monkeypatch.chdir(elsewhere) with pytest.raises(SystemExit) as stop: cli.checkout() message = str(stop.value.code) assert "is not inside one" in message assert cli.REPOSITORY in message assert "paperspec validate and paperspec load work anywhere" in message def test_a_folder_missing_one_mark_is_not_a_checkout(self, tmp_path, monkeypatch): site = tmp_path / "site-packages" / "paperspec" / "cli" site.mkdir(parents=True) monkeypatch.setattr(cli, "__file__", str(site / "__init__.py")) whole = tmp_path / "whole" FakeCheckout(whole) partial = whole / "partial" FakeCheckout(partial) (partial / "registry").rmdir() monkeypatch.chdir(partial) assert cli.checkout() == str(whole.resolve())