CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

tensors is a Python CLI tool (tsr) for reading safetensor file metadata and interacting with the CivitAI API (search, fetch, download models). Built with Typer, Rich, and httpx.

Commands

# Install dependencies
uv sync --group dev

# Run everything (fix, check, test)
just

# Individual tasks
just check          # ruff check + mypy
just test           # pytest with coverage
just fix            # auto-fix lint + format
just types          # mypy only

# Run a single test
uv run pytest tests/test_tensors.py::TestClassName::test_name -v

Architecture

Five modules with clean separation:

cli.py — Typer CLI with commands: info, search, get, dl, config. Legacy mode auto-converts bare tsr file.safetensors to tsr info.
api.py — CivitAI REST API wrapper using httpx. Search, fetch model/version/by-hash, download with resume support and Rich progress bars.
config.py — XDG-compliant paths (~/.config/tensors/config.toml, ~/.local/share/tensors/). Enums with to_api() methods for CivitAI parameter mapping. API key resolution: env var → config file → legacy ~/.sftrc.
safetensor.py — Binary safetensor header parsing (8-byte u64 LE header size → JSON metadata). SHA256 streaming hash computation.
display.py — Rich table formatting for all output types. All major commands support --json output.

Entry point: tsr = "tensors:main" (pyproject.toml [project.scripts]).

Code Standards

Python 3.12+, strict mypy, line length 130
Ruff with extended rule set (E, W, F, I, B, C4, UP, ARG, SIM, TCH, PTH, PL, RUF)
PLR0913 (too many arguments) is intentionally ignored for CLI commands
Tests use respx for HTTP mocking and a temp_safetensor fixture from conftest.py

Release

Tags trigger PyPI publish: git tag v0.1.x && git push origin v0.1.x. See RELEASE.md for binary builds (Nuitka).

2.0 KiB Raw Blame History