ssc-codegen
Code generator for web scraping parsers. Describe HTML extraction rules in a declarative KDL 2.0 DSL, then generate ready-to-use parser code for multiple languages and libraries.
.kdl schema --> [kdl parser] --> AST --> [linter] --> [converter] --> output code
Features
- Declarative DSL based on KDL 2.0 syntax
- Static type checking and linting before code generation
- Multiple output targets: Python (bs4, lxml, parsel, selectolax), JavaScript (DOM API), Go (goquery)
- Typed user extensions with lazy target imports and runtime helpers
- Struct types:
item,list,dict,table,flat - LLM-friendly: system prompt + linter loop for AI-assisted schema generation
Install
uv tool install ssc_codegen
Quick example
books.kdl:
(list)struct Book {
@split-doc { css-all ".product-card" }
title { css ".title"; text }
price { css ".price"; text; re #"(\d+\.\d+)"#; to-float }
url { css "a[href]"; attr "href"; fallback #null }
}
Generate Python parser:
ssc-gen generate python books.kdl -L bs4 -o ./output
Usage
Generate code
# single file (Python + bs4)
ssc-gen generate python schema.kdl -L bs4 -o ./output
# all .kdl files in a directory (JavaScript)
ssc-gen generate js examples/ -o ./output
# Go (goquery + net/http)
ssc-gen generate go schema.kdl -o ./output
# Go package defaults to main; override explicitly when generating a library
ssc-gen generate go schema.kdl -o ./output --package scraper
# with custom package name
ssc-gen generate python schema.kdl -L bs4 -o ./parsers --package scraper
# with @request support (REST/HTTP codegen)
ssc-gen generate python schema.kdl -L bs4 -o ./out --http-client httpx
# extract helper functions into a separate runtime module
ssc-gen generate python schema.kdl -L bs4 -o ./out -R
Languages: generate python, generate js, generate go.
HTML libraries (--lib / -L, Python only): bs4 (default), lxml, parsel, slax.
Lint schemas
# human-readable output
ssc-gen check schema.kdl
# JSON output (for LLM pipelines)
ssc-gen check schema.kdl -f json
# check all files in a directory
ssc-gen check examples/
Test schema against HTML
# from file
ssc-gen run examples/booksToScrape.kdl:MainCatalogue -L bs4 -i page.html
# from stdin
curl https://books.toscrape.com/ | ssc-gen run examples/booksToScrape.kdl:MainCatalogue -L bs4
ssc-gen run executes generated Python in-process. Run only trusted schema files.
Health check (verify selectors match elements)
# from file
ssc-gen health examples/booksToScrape.kdl:MainCatalogue -i page.html
# from stdin
curl https://books.toscrape.com/ | ssc-gen health examples/booksToScrape.kdl:MainCatalogue
Documentation
- Quick start
- Syntax and file structure
- Type system
- Pipeline operations
- Predicates and logic
- JSON schemas and jsonify
- @request — HTTP constructor + REST clients
- LLM-compact reference -- full DSL spec in one file for LLM context
- Examples
LLM integration
LLM agents can generate and validate .kdl schemas automatically using the
linter feedback loop.
In chats (ChatGPT, Claude, etc.)
Use SYSTEM_PROMPT.md as system prompt. After generation,
run ssc-gen check -f json and send errors back to the LLM for correction.
In AI-powered IDEs (Claude Code, Cursor, opencode, etc.)
Use the skills under .agents/skills/:
sscgen-dsl— HTML scraping schemas (css,text,(item)struct,(list)struct,(table)struct, predicates,jsonify).sscgen-rest— REST/JSON API clients ((rest)struct,@request,@error, typed placeholders).sscgen-openapi— convert OpenAPI/Swagger specs into.kdl.
Development
uv sync # install dependencies
uv build --wheel # build wheel
uv run pytest # run tests
uv run ruff check ssc_codegen/
Test dependencies
Python tests require only uv sync. JS integration tests additionally need:
npm install # installs jsdom (dev dependency in package.json)
Node.js must be installed and available as node in PATH. JS tests are automatically skipped if Node.js is not found.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ssc_codegen-0.38.0.tar.gz.
File metadata
- Download URL: ssc_codegen-0.38.0.tar.gz
- Upload date:
- Size: 166.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d67ce8102c4acf7a1275337d90543d5f4f71fd5702add59f6896e2f792bc9c10
|
|
| MD5 |
3c2175408e9c27ff475e075f82c8fd4f
|
|
| BLAKE2b-256 |
7ce34cf24cd141921a694ac5a3a1379f91198c85c510415c19736048578eef9b
|
File details
Details for the file ssc_codegen-0.38.0-py3-none-any.whl.
File metadata
- Download URL: ssc_codegen-0.38.0-py3-none-any.whl
- Upload date:
- Size: 205.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.14 {"installer":{"name":"uv","version":"0.11.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
49a427db76176606f954255a021215cb74354de12c26b1e744c4f01735b3786e
|
|
| MD5 |
b726832af999f8ca64d65e813956d45e
|
|
| BLAKE2b-256 |
8d58f7bd4ddf46e5b651e033390b202214ff8241fff63d60c180657b208e5381
|
