SciTeX Linter (`scitex-linter`)

AST-based Python linter enforcing reproducible research patterns

Full Documentation · pip install scitex-linter

Interfaces: Python ⭐ · CLI ⭐⭐ · MCP ⭐ · Skills ⭐⭐ · Hook ⭐⭐⭐ (primary) · HTTP —

Problem and Solution

#	Problem	Solution
1	Project conventions live in wiki pages -- new contributors violate them for weeks before the code review catches it	47 codified rules -- `STX-IO` (save/load), `STX-S` (session), `STX-FM` (filenames), `STX-PA` (path), etc. run pre-commit and block the PR
2	`ruff`/`flake8` don't know about scitex idioms -- `stx.io.save` usage, CONFIGS naming, matplotlib prefs, import hygiene are all invisible to standard linters	Complements ruff/flake8 -- scitex-linter is a pluggable pre-commit hook focused on ecosystem conventions; runs alongside your existing linters

Problem

SciTeX scripts follow strict patterns for reproducibility — @scitex.session decorators, scitex.io for provenance-tracked I/O, scitex.stats for complete statistical reporting, and relative paths for portability. Deviations from these patterns silently undermine reproducibility, and manual code review does not scale across large research projects or AI-generated code.

Solution

SciTeX Linter analyzes Python source code at the AST (Abstract Syntax Tree) level to detect violations of SciTeX patterns before they become irreproducible results. It provides 47 rules across 7 categories, covering structure, imports, I/O, plotting, statistics, paths, and figure layout. The linter integrates into terminal workflows, CI pipelines, and AI agent toolchains — ensuring both human researchers and AI assistants produce reproducible science.

Installation

pip install scitex-linter

Quick Start

# Lint a file
scitex-linter check script.py

# Lint then execute
scitex-linter python experiment.py --strict

# Auto-fix issues
scitex-linter format script.py

# List all 47 rules
scitex-linter rule

Four Interfaces

Python API

from scitex_linter.checker import lint_file, lint_source
from scitex_linter.formatter import format_issue

# Lint a file
issues = lint_file("script.py")
for issue in issues:
    print(format_issue(issue, "script.py"))

# Check source code directly
issues = lint_source("import argparse\npass\n")

Full API reference

scitex_linter
  list_rules(category=None) -> list[Rule]

scitex_linter.checker
  lint_file(filepath, config=None) -> list[Issue]
  lint_source(source, filepath, config=None) -> list[Issue]
  is_script(filepath, config=None) -> bool

scitex_linter.fixer
  fix_source(source, filepath, config=None) -> str
  fix_file(filepath, write=True, config=None) -> tuple

scitex_linter.formatter
  format_issue(issue, filepath, color=False) -> str
  format_summary(issues, filepath, color=False) -> str
  to_json(issues, filepath) -> list[dict]

CLI Commands

scitex-linter --help                              # Show all commands
scitex-linter --help-recursive                    # Show help for all subcommands

# Check
scitex-linter check script.py                      # Check a file
scitex-linter check ./src/                         # Check a directory
scitex-linter check script.py --severity error     # Only errors
scitex-linter check script.py --category path      # Only path rules
scitex-linter check script.py --json               # JSON output for CI

# Format (auto-fix)
scitex-linter format script.py                     # Fix in place
scitex-linter format script.py --check             # Dry run (exit 1 if changes needed)
scitex-linter format script.py --diff              # Show diff of changes

# Lint then execute
scitex-linter python experiment.py                 # Lint and run
scitex-linter python experiment.py --strict        # Abort on errors
scitex-linter python experiment.py -- --lr 0.001   # Pass script args

# Rules
scitex-linter rule                                 # List all 47 rules
scitex-linter rule --category stats                # Filter by category
scitex-linter rule --json                          # JSON output

Additional integrations

flake8 plugin — registers with the STX prefix for CI pipelines:

flake8 --select STX script.py

Claude Code hook — auto-lints every Python file Claude writes or edits:

# In ~/.claude/to_claude/hooks/post-tool-use/run_lint.sh
# Errors (exit 2) → Claude must fix
# Warnings (exit 1) → Claude sees feedback

MCP Server

Three tools for AI agents (Claude, GPT, etc.):

Tool	Description
`linter_check`	Check a Python file for SciTeX compliance
`linter_check_source`	Lint source code string
`linter_list_rules`	List all available rules

scitex-linter mcp start          # Start server (stdio)
scitex-linter mcp list-tools     # List available tools
scitex-linter mcp doctor         # Health check
scitex-linter mcp installation   # Show Claude Desktop config

Install MCP extra: pip install scitex-linter[mcp]

Skills — for AI Agent Discovery

Skills provide workflow-oriented guides that AI agents query to discover capabilities and usage patterns.

scitex-linter skills list              # List available skill pages
scitex-linter skills get SKILL         # Show main skill page
scitex-dev skills export --package scitex-linter  # Export to Claude Code

Skill	Content
`quick-start`	Basic usage
`rule-catalog`	All built-in rules
`cli-reference`	CLI commands
`mcp-tools`	MCP tools for AI agents

47 Rules Across 7 Categories

Category	Count	Severity	What It Enforces
S Structure	8	error/warning/info	`@scitex.session`, `__main__` guard, INJECTED params
I Import	7	warning/info	Use `scitex.plt`, `scitex.stats`, `scitex.io` instead of raw libs
IO I/O Calls	7	warning	Use `scitex.io.save()`/`scitex.io.load()` for provenance
P Plot	5	info	Use `scitex.plt` tracked methods, `logger` over `print()`
ST Stats	6	warning	Use `scitex.stats` for auto effect size + CI + power
PA Path	5	warning/info	Relative paths with `./`, no `open()`, no `os.chdir()`
FM Figure	9	warning/info	mm-based layout, `scitex.io.save()` for figures

_{Table 1. Rule categories. Run scitex-linter rule for the full list, or see the Rules Reference.}

Example output

script.py:1   STX-S003  [error]    argparse detected — @scitex.session auto-generates CLI
  Suggestion: Remove `import argparse` and define parameters as function arguments:
    @scitex.session
    def main(data_path: str, threshold: float = 0.5):
        # Auto-generates: --data-path, --threshold

script.py:5   STX-PA001 [warning]  Absolute path in `scitex.io` call — use relative paths
  Suggestion: Use `scitex.io.save(obj, './relative/path.ext')` — paths resolve to script_out/.

script.py: 2 issues (1 error, 1 warning)

Full rules listing

Rule	Severity	Message
`STX-S001`	error	Missing `@scitex.session` or `@scitex.module` decorator on main function
`STX-S002`	error	Missing `if __name__ == '__main__'` guard
`STX-S003`	error	argparse detected — `@scitex.session` auto-generates CLI from function signature
`STX-S004`	warning	`@scitex.session` function should return an integer exit code
`STX-S005`	warning	Missing `import scitex`
`STX-S006`	warning	`@scitex.session` function missing explicit INJECTED parameters
`STX-S007`	warning	`load_configs()` result should be assigned to an UPPER_CASE variable
`STX-S008`	info	Magic number in module scope — consider centralizing in config/
`STX-I001`	warning	Use `scitex.plt` instead of importing matplotlib.pyplot directly
`STX-I002`	warning	Use `scitex.stats` instead of importing scipy.stats directly
`STX-I003`	warning	Use `scitex.io` instead of pickle for file I/O
`STX-I004`	warning	Use `scitex.io` for CSV/DataFrame I/O instead of pandas I/O functions
`STX-I005`	warning	Use `scitex.io` for array I/O instead of numpy save/load
`STX-I006`	info	Use `rngg` (injected by `@scitex.session`) for reproducible randomness
`STX-I007`	warning	Use `logger` (injected by `@scitex.session`) instead of logging module
`STX-IO001`	warning	Use `scitex.io.save()` instead of `np.save()` / `np.savez()`
`STX-IO002`	warning	Use `scitex.io.load()` instead of `np.load()` / `np.loadtxt()`
`STX-IO003`	warning	Use `scitex.io.save()` instead of `pd.to_csv()` / `to_excel()`
`STX-IO004`	warning	Use `scitex.io.load()` instead of `pd.read_csv()` / `read_excel()`
`STX-IO005`	warning	Use `scitex.io.save()` instead of `pickle.dump()`
`STX-IO006`	warning	Use `scitex.io.load()` instead of `pickle.load()`
`STX-IO007`	warning	Use `scitex.io.save()` instead of `plt.savefig()`
`STX-P001`	info	Use `scitex.plt.subplots()` instead of `plt.subplots()`
`STX-P002`	info	Use `scitex.plt.figure()` instead of `plt.figure()`
`STX-P003`	info	Use `scitex.plt.show()` instead of `plt.show()`
`STX-P004`	info	Use `logger` instead of `print()` for output
`STX-P005`	info	Use `scitex.plt` methods for consistent plotting
`STX-ST001`	warning	Use `scitex.stats.ttest_ind()` for complete statistical reporting
`STX-ST002`	warning	Use `scitex.stats.ttest_1samp()` for complete statistical reporting
`STX-ST003`	warning	Use `scitex.stats.mannwhitneyu()` for complete statistical reporting
`STX-ST004`	warning	Use `scitex.stats.wilcoxon()` for complete statistical reporting
`STX-ST005`	warning	Use `scitex.stats.chi2_contingency()` for complete statistical reporting
`STX-ST006`	warning	Use `scitex.stats.f_oneway()` for complete statistical reporting
`STX-PA001`	warning	Absolute path in `scitex.io` call — use relative paths for reproducibility
`STX-PA002`	warning	`open()` detected — use `scitex.io.save()`/`scitex.io.load()` which includes auto-logging
`STX-PA003`	info	`os.makedirs()`/`mkdir()` detected — `scitex.io.save()` creates directories automatically
`STX-PA004`	warning	`os.chdir()` detected — scripts should be run from project root
`STX-PA005`	info	Path without `./` prefix in `scitex.io` call — use `./` for explicit relative intent
`STX-FM001`	warning	Use `scitex.io.save()` instead of `fig.savefig()`
`STX-FM002`	info	Use `scitex.plt.subplots()` for mm-based figure layout
`STX-FM003`	info	Use mm units for figure dimensions
`STX-FM004`	warning	`tight_layout()` conflicts with mm-based layout
`STX-FM005`	warning	`constrained_layout` conflicts with mm-based layout
`STX-FM006`	warning	`subplots_adjust()` conflicts with mm-based layout
`STX-FM007`	info	`rcParams` direct modification detected — hard to maintain across figures
`STX-FM008`	warning	`set_size_inches()` detected — bypasses mm-based layout control
`STX-FM009`	warning	`ax.set_position()` detected — conflicts with mm-based layout control

Additional rules are contributed by downstream packages via the scitex_linter.plugins entry point.

What a Clean Script Looks Like

import scitex

@scitex.session
def main(data_path="./data.csv", threshold=0.5):
    df = scitex.io.load(data_path)
    results = scitex.stats.ttest_ind(df["group_a"], df["group_b"])
    scitex.io.save(results, "./results.csv")
    return 0

if __name__ == "__main__":
    main()

Zero lint issues. Fully reproducible. Auto-CLI from function signature.

Configuration

Configure via pyproject.toml or environment variables

[tool.scitex-linter]
severity = "info"                    # Minimum severity: error, warning, info
disable = ["STX-P004", "STX-I003"]   # Disable specific rules
exclude-dirs = ["venv", ".venv"]     # Directories to skip
library-dirs = ["src"]               # Exempt from script-only rules

[tool.scitex-linter.per-rule-severity]
STX-S003 = "warning"                 # Downgrade argparse rule

[tool.scitex-linter.session]
required-injected = ["CONFIG", "plt", "COLORS", "rngg", "logger"]

Environment variables (highest priority):

SCITEX_LINTER_SEVERITY=error
SCITEX_LINTER_DISABLE=STX-P004,STX-I003

Priority: CLI flags > env vars > pyproject.toml > defaults

Part of SciTeX

SciTeX Linter is part of SciTeX. When used inside the orchestrator package scitex, the linter automatically enforces patterns for all SciTeX modules — scitex.io, scitex.stats, scitex.plt, and scitex.session — ensuring consistency across the entire research pipeline.

The SciTeX ecosystem follows the Four Freedoms for researchers, inspired by the Free Software Definition:

Freedom 0 — Run research for any purpose
Freedom 1 — Study and modify the research pipeline
Freedom 2 — Redistribute results and methods
Freedom 3 — Distribute modified versions to advance science

Documentation

Full Documentation on Read the Docs

AGPL-3.0

Metadata

Release files for scitex-linter 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scitex-linter 0.3.5
File	Size	Uploaded	Provenance
scitex_linter-0.3.5.tar.gz	69.5 kB	Apr 24, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for scitex-linter 0.3.5
File	Interpreter	ABI	Platform	Reset
scitex_linter-0.3.5-py3-none-any.whl 65.6 kB Apr 24, 2026 With provenance	Python 3	none	any	Details

Total release size: 135.1 kB

Release files / scitex_linter-0.3.5.tar.gz

Download URL	scitex_linter-0.3.5.tar.gz
Size	69.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`78dc7ed299e9233d11828cdf0328eb2bf5859f80c17842919fed7116804d0d67`
BLAKE2b-256 checksum How to use checksums	`be5a5b2bf6586802ce8fc6a00782c75fde3fd50f52cc3f9069851f1bdefa250a`
Upload date	Apr 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ywatanabe1989/scitex-linter
Publishing commit: github.com/ywatanabe1989/scitex-linter/tree/9b131d46d1299bcf52f027a46fa5ceb6ae65a694

Workflow

Publishing configuration: github.com/ywatanabe1989/scitex-linter/blob/9b131d46d1299bcf52f027a46fa5ceb6ae65a694/.github/workflows/publish-pypi.yml
Publishing logs: github.com/ywatanabe1989/scitex-linter/actions/runs/24869267033/attempts/1

Artifact

Subject: scitex_linter-0.3.5.tar.gz
SHA-256 checksum: 78dc7ed299e9233d11828cdf0328eb2bf5859f80c17842919fed7116804d0d67 Verifying attestations

Release files / scitex_linter-0.3.5-py3-none-any.whl

Download URL	scitex_linter-0.3.5-py3-none-any.whl
Size	65.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f4abf967ef58713571959342996fc42e16cf1294b5d4a80807364c886dc496e0`
BLAKE2b-256 checksum How to use checksums	`c5a1b5602f09a67ada686a34fd3a771ed3f97b7fb7ea8da8a8ad2bd57f032b7b`
Upload date	Apr 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ywatanabe1989/scitex-linter
Publishing commit: github.com/ywatanabe1989/scitex-linter/tree/9b131d46d1299bcf52f027a46fa5ceb6ae65a694

Workflow

Publishing configuration: github.com/ywatanabe1989/scitex-linter/blob/9b131d46d1299bcf52f027a46fa5ceb6ae65a694/.github/workflows/publish-pypi.yml
Publishing logs: github.com/ywatanabe1989/scitex-linter/actions/runs/24869267033/attempts/1

Artifact

Subject: scitex_linter-0.3.5-py3-none-any.whl
SHA-256 checksum: f4abf967ef58713571959342996fc42e16cf1294b5d4a80807364c886dc496e0 Verifying attestations

Security for scitex-linter 0.3.5

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for scitex_linter-0.3.5.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ywatanabe1989/scitex-linter
Publishing commit: github.com/ywatanabe1989/scitex-linter/tree/9b131d46d1299bcf52f027a46fa5ceb6ae65a694

Workflow

Publishing configuration: github.com/ywatanabe1989/scitex-linter/blob/9b131d46d1299bcf52f027a46fa5ceb6ae65a694/.github/workflows/publish-pypi.yml
Publishing logs: github.com/ywatanabe1989/scitex-linter/actions/runs/24869267033/attempts/1

Artifact

Subject: scitex_linter-0.3.5.tar.gz
SHA-256 checksum: 78dc7ed299e9233d11828cdf0328eb2bf5859f80c17842919fed7116804d0d67 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.