Install & Compatibility
Where this runs
tested against v1.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.194s · 19.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.172s · 20MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SarifLog
✓ from sarif_om import SarifLog, Run, Tool, ToolComponent, Result, Location, PhysicalLocation, ArtifactLocation, Message, ReportingDescriptor
This quickstart demonstrates how to programmatically construct a SARIF 2.1.0 log using the `sarif-om` classes. It creates a simple log with one run, one tool, one rule, and one result. Note that `sarif-om` itself only provides the object model; users must use standard Python JSON libraries (like `json`) to serialize the object model to a SARIF JSON string.
import json
from sarif_om import SarifLog, Run, Tool, ToolComponent, Result, Location, PhysicalLocation, ArtifactLocation, Message, ReportingDescriptor
# Create a SARIF log object
log = SarifLog(version='2.1.0', runs=[])
# Create a Tool component
tool_component = ToolComponent(name='Example Tool', version='1.0.0')
# Create a Tool
tool = Tool(driver=tool_component)
# Create a Run
run = Run(tool=tool, results=[])
# Create a ReportingDescriptor (rule definition)
rule = ReportingDescriptor(id='EX1001', name='Example Rule', short_description=Message(text='This is an example rule.'))
# Add the rule to the tool's driver rules
tool.driver.rules = [rule]
# Create a Result
result = Result(
rule_id='EX1001',
message=Message(text='Found a potential issue.'),
locations=[
Location(
physical_location=PhysicalLocation(
artifact_location=ArtifactLocation(uri='src/main.py'),
region={'startLine': 10, 'startColumn': 5}
)
)
]
)
# Add the result to the run
run.results.append(result)
# Add the run to the log
log.runs.append(run)
# Serialize the SARIF log to JSON (sarif-om does not provide a direct save method)
sarif_json = json.dumps(log.to_dict(), indent=2)
print(sarif_json)
Debug
Known issues
gotchaThe `sarif-om` library provides only the object model classes. It does not include functionality to directly load existing SARIF files from disk or to serialize the in-memory object model to a file. Users must implement their own JSON parsing (e.g., using `json.load`/`json.loads`) and serialization (e.g., using `json.dump`/`json.dumps`) to work with actual SARIF files. Other libraries like `pysarif` or `sarif-tools` offer file I/O capabilities for SARIF.fixManually handle JSON serialization/deserialization using Python's `json` module or consider `pysarif` for simplified file I/O.
affects: All versions
gotchaDocumentation for programmatic usage of `sarif-om` can be sparse, particularly for constructing complex SARIF logs from scratch. Most public examples or tutorials tend to focus on the `sarif-tools` command-line utility or `pysarif` library for interacting with SARIF files.fixRefer to the SARIF 2.1.0 specification for the object model structure and property requirements when constructing objects. Examine the source code for class definitions and available properties if specific usage patterns are unclear.
affects: All versions
breakingThe related `sarif-tools` library (a separate project that *uses* `sarif-om`) introduced breaking changes in its 2.0.0 release. Specifically, CSV output columns ('Code' and 'Description' are now separate) and the `--blame-filter` argument (replaced by `--filter` with a new YAML-based format) were changed. This directly impacts users interacting with `sarif-tools` for reporting or filtering.fixIf using `sarif-tools`, update scripts to reflect the new CSV output structure and adapt filter files to the new YAML format, potentially using the `upgrade-filter` command. This warning is specific to `sarif-tools`, not `sarif-om` itself.
affects: sarif-tools >= 2.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sarif'
Developers often try to import classes from `sarif.om` assuming a package structure that separates 'sarif' and 'om', instead of using the correct package name `sarif_om`.
fixUse `from sarif_om import ...` to import classes from the `sarif-om` library, ensuring the underscore `_` in the module name.
TypeError: Object of type SarifLog is not JSON serializable
The `sarif-om` objects are custom Python objects and cannot be directly serialized to JSON. They must first be converted into a dictionary representation.
fixConvert the SARIF object to a dictionary using its `.to_dict()` method before passing it to `json.dumps()`, e.g., `json.dumps(log.to_dict(), indent=2)`.
ValidationError: 1 validation error for ToolComponent (field required)
SARIF objects like `ToolComponent` have mandatory fields according to the SARIF specification. This error occurs when a required field (e.g., `name`) is omitted during object instantiation.
fixEnsure all mandatory fields are provided during the object's instantiation, for example, `ToolComponent(name="MyTool", semantic_version="1.0.0")`.
ValidationError: 1 validation error for Run (value is not a valid list)
Many fields in the SARIF object model expect a list of objects (e.g., `results` in a `Run` object, or `runs` in a `SarifLog`). This error occurs when a single object is provided instead of a list containing that object.
fixWrap the single object in a list, for example, `Run(tool=tool, results=[result])` instead of `Run(tool=tool, results=result)`.
Upgrade
Version history
1.0.4latest on PyPI · released Oct 5, 2019
Audit
Dependencies
No dependency data recorded yet.