docs/References.md

Table Of Contents

1. References
2. Project Reference
   1. Project Paths
   2. Command Reference
   3. Dependency Surfaces
   4. Environment Variables
   5. Configuration Files
   6. Public Interfaces
   7. Figure Visual Tokens

1. References

Use this file when you need an exact path, command, environment variable, or public name. Use How-To User Guides for procedure and Explanations for concepts.

2. Project Reference

Project Paths

Core paths:

Path	Role
README.md	Short setup entry point.
CHANGELOG.md	Release history and unreleased change notes.
TODO.md	Tracked parking lot for actionable follow-up work.
AGENTS.md	Local coding and documentation guidance for agents.
pyproject.toml	Package metadata, dependencies, and tool configuration.
justfile	Development commands.
src/kscrape	Runtime package source.
src/kscrape_dev	Maintainer-only release checks.
tests	Test suite.
docs	Long-form project documentation.

Related: use Development: repository routing before adding files or moving behavior between directories.

Command Reference

Common commands:

Command	Role
just --list	Show available development recipes.
just sync	Sync the full maintainer environment from uv.lock.
python -m pip install -e "."	Install runtime package dependencies without uv.
python -m pip install -e "." --group dev	Install maintainer tools without uv.
just release-check	Run the complete local release rehearsal without changing version or publishing.
just release LEVEL	Prepare and atomically push main plus the new release tag.
just release-prepare LEVEL	Create the checked version commit and annotated tag without pushing.
just release-push TAG	Atomically push an existing prepared release commit and tag.
kscrape --help	Show the console command tree.
kscrape version	Print the installed package version.
kscrape config --help	Show AppRC's process-environment configuration commands.
kscrape config show --json	Show redacted process configuration metadata.
kscrape source list	List built-in source adapters.
kscrape posts search SOURCE TAG...	Print post records.
kscrape posts export SOURCE TAG...	Export bounded post metadata as JSON or JSONL without downloading files.
kscrape posts tag-summary SOURCE TAG...	Count categorized tags across a bounded post query.
kscrape posts download SOURCE TAG... --output DIRECTORY	Download matching raster files to DIRECTORY/posts/SOURCE/images/ and append to its manifest.jsonl.
kscrape sets download SOURCE SET --output DIRECTORY	Download set members to DIRECTORY/sets/SOURCE/SET/images/ with set-local tags, a replaced manifest, and a cumulative image-index.json. --prune removes recorded former images after a complete successful run; it cannot be used with --limit.
kscrape tags search SOURCE PATTERN	Search source tags.
python -m kscrape --help	Smoke-test the module entry point.
ruff format .	Format Python files.
ruff check .	Lint Python files.
pyright	Type-check runtime source.
python -m pytest	Run the test suite.

Related: use How-To User Guides: run tests for the command sequence.

Dependency Surfaces

Dependency locations:

Surface	File Section	Use
Runtime dependencies	[project].dependencies	Packages required by normal users.
Optional feature extras	[project.optional-dependencies]	Published extras for optional runtime features when the package adds them.
Dependency groups	[dependency-groups]	Local maintainer tools such as tests, linting, typing, docs, and profiling.
Lock file	uv.lock	Reproducible uv installs.
Exported lock	pylock.toml	Lock representation for compatible tooling.

Related: use dependency model for why optional runtime features and maintainer-only tools stay separate.

Environment Variables

Common environment variables:

Name	Role
KSCRAPE_USER_AGENT	Required descriptive User-Agent for source requests.
KSCRAPE_E621_USERNAME	Optional e621 HTTP Basic username.
KSCRAPE_E621_API_KEY	Optional e621 HTTP Basic API key.
KSCRAPE_E6AI_USERNAME	Optional e6AI HTTP Basic username.
KSCRAPE_E6AI_API_KEY	Optional e6AI HTTP Basic API key.
VIRTUAL_ENV	Active virtual environment path.
PYTHONPATH	Import-path override for local smoke tests. Prefer editable installs for normal development.
UV_PROJECT_ENVIRONMENT	Optional uv virtual environment path override.

Set a source username and API key together. kscrape reads these values only from the process. It has no storage selector, user dotenv, persistent credential file, or configuration setup command.

Related: use How-To User Guides: environment problems for the first checks when imports resolve from the wrong location.

Configuration Files

Important config files:

File	Role
pyproject.toml	Python packaging, dependencies, and tool settings.
src/kscrape/config/app.py	AppRC declaration.
src/kscrape/config/sections/network.py	Typed process-environment settings.
.envrc	direnv integration.
.gitignore	Local and generated files excluded from Git.
.github/workflows_inactive	Inactive starter CI workflows.
pylock.toml	Exported dependency lock.

kscrape does not use config/.env.shared, an AppRC storage registry, a user dotenv, or a persistent credential file.

Related: use configuration model for why the process-only configuration remains intentionally small.

Public Interfaces

Document public surfaces here as the project grows:

Surface	Current Name	Stability
Package import	kscrape	Public once README examples use it.
Console script	kscrape	Public command declared in pyproject.toml.
Module entrypoint	python -m kscrape	Public module execution path.
CLI app owner	kscrape.cli.app	Command tree implementation owner.
Entrypoint wrapper	kscrape.main	Thin wrapper for package metadata entry points.
Source registry	kscrape.sources.SourceRegistry	Built-in source adapter lookup.
Config sections	kscrape.config.sections	App-owned AppRC rc.Config field declarations.
Config bundle	kscrape.config.KscrapeConfig	Typed object that assembles config sections.
Config catalog	kscrape.config.catalog	Section metadata and CLI registration import.
Config facade	kscrape.config.APP_RC	AppRC facade used by CLI bootstrap and config commands.
Export formats	kscrape.exports.ExportFormat	JSON and JSONL serialization selection.
Tag summary row	kscrape.exports.TagSummary	Category-aware tag frequency record.

Related: use How-To User Guides: run the first command for the first user-facing smoke test.

Figure Visual Tokens

Keep figure captions and generated asset names stable here. Put repeatable figure-builder source code next to its renderer instead of duplicating visual tokens across documentation files.

Related links:

• Use static figure rules before adding docs figures.
• Use documentation authoring before changing docs structure or figure assets.