Metadata-Version: 2.4
Name: vastlint
Version: 0.6.1
Summary: In-process Python bindings for vastlint VAST XML validation
Project-URL: Homepage, https://vastlint.org
Project-URL: Documentation, https://vastlint.org/docs/rules
Project-URL: Source, https://github.com/aleksUIX/vastlint-python
Project-URL: Changelog, https://github.com/aleksUIX/vastlint-python/releases
Author-email: Alex Sekowski <alex@vastlint.org>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: adtech,iab,linter,validation,vast,video,xml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# vastlint (Python)

High-performance, in-process VAST XML validation for Python backends.

**Rule reference:** [vastlint.org/docs/rules](https://vastlint.org/docs/rules/) · **Web validator:** [vastlint.org/validate](https://vastlint.org/validate)

This package wraps the stable `vastlint-ffi` C API, backed by the same Rust core used by the CLI, Go binding, Ruby gem, Erlang NIF, MCP server, and web validator. The intended use case is a DSP, SSP, ad server, or trafficking backend that needs to validate VAST XML and return structured linting results to a frontend.

## Why this shape

- No subprocess management in your Python app
- No network hop to an external validation service
- Stable JSON-compatible result shape for backend-to-frontend responses
- Same rule coverage and behavior as the rest of the vastlint ecosystem

## Install

The package bundles a platform-matched `libvastlint` shared library inside the wheel, so no compiler or Rust toolchain is needed at install time.

```sh
pip install vastlint
```

You can also point the package at an explicit shared library with `VASTLINT_LIB_PATH`:

```sh
export VASTLINT_LIB_PATH=/absolute/path/to/libvastlint.dylib
```

For development in this monorepo, it automatically falls back to the sibling `vastlint/target/debug` and `vastlint/target/release` outputs.

## Usage

```python
import vastlint

result = vastlint.validate(vast_xml)

if result.valid:
    print("clean tag")
else:
    print(result.summary.errors)
    print(result.issues[0].message)

print(result.to_json())
```

### FastAPI / Flask example

```python
from fastapi import FastAPI
from pydantic import BaseModel
import vastlint

app = FastAPI()


class ValidateRequest(BaseModel):
    xml: str
    wrapper_depth: int = 0
    max_wrapper_depth: int = 5
    rule_overrides: dict[str, str] | None = None


@app.post("/validate")
def validate(req: ValidateRequest):
    result = vastlint.validate(
        req.xml,
        wrapper_depth=req.wrapper_depth,
        max_wrapper_depth=req.max_wrapper_depth,
        rule_overrides=req.rule_overrides,
    )
    return result.to_dict()
```

The response shape is stable and frontend-friendly:

```json
{
  "version": "4.2",
  "issues": [
    {
      "id": "VAST-2.0-inline-impression",
      "severity": "error",
      "message": "<InLine> must contain at least one <Impression>",
      "path": "/VAST/Ad[0]/InLine",
      "spec_ref": "IAB VAST 2.0 §2.2.1",
      "line": 4,
      "col": 3
    }
  ],
  "summary": { "errors": 1, "warnings": 0, "infos": 0, "valid": false }
}
```

## API

```python
vastlint.validate(xml, *, wrapper_depth=0, max_wrapper_depth=5, rule_overrides=None) -> Result
vastlint.version() -> str
```

`xml` accepts `str` or `bytes`. `rule_overrides` maps rule IDs to severity levels:

```python
result = vastlint.validate(
    vast_xml,
    rule_overrides={
        "VAST-2.0-mediafile-https": "error",
        "VAST-4.1-mezzanine-recommended": "off",
    },
)
```

`Result` exposes `.version`, `.issues` (list of `Issue`), `.summary` (`Summary`), `.valid`, `.to_dict()`, and `.to_json()`. All result types are frozen dataclasses.

## Performance

Validation runs in-process against the Rust core, so per-tag cost is dominated by the core, not by Python. Numbers below are single-core, single-threaded, and include the full Python round trip (FFI call, JSON result, parse into dataclasses), so they reflect what a caller actually sees.

| Tag size | Median latency | Throughput (1 core) |
| --- | --- | --- |
| 7 KB | 86 µs | ~11,000 tags/sec |
| 17 KB | 0.36 ms | ~2,800 tags/sec |
| 23 KB | 0.57 ms | ~1,700 tags/sec |
| 44 KB | 2.1 ms | ~470 tags/sec |
| 347 KB | 4.7 ms | ~210 tags/sec |

Measured on an Apple M4, single core, 200 tags per size bucket, warm. Production tags typically run 17 to 44 KB. Each validation is independent and holds no shared state, so throughput scales close to linearly across cores with a process pool. Reproduce with `scripts/bench.py`.

## Native library layout

Vendored release libraries live at:

- `src/vastlint/native/darwin_arm64/libvastlint.dylib`
- `src/vastlint/native/darwin_amd64/libvastlint.dylib`
- `src/vastlint/native/linux_arm64/libvastlint.so`
- `src/vastlint/native/linux_amd64/libvastlint.so`

They come from the `vastlint-ffi-*` tarballs attached to each `vastlint` GitHub Release. Refresh them with:

```sh
./scripts/fetch-libs.sh v0.4.14
```

## License

Apache 2.0.
