0
# Output Formats
1

2
Different ways to format and display audit results, from human-readable columnar output to machine-parseable JSON and CycloneDX SBOM formats.
3

4
## Imports
5

6
```python
7
import enum
8
from abc import ABC, abstractmethod
9
from pip_audit._service import Dependency, VulnerabilityResult
10
from pip_audit._fix import FixVersion
11
```
12

13
## Capabilities
14

15
### Base Interface
16

17
Abstract base class for all output formats.
18

19
```python { .api }
20
class VulnerabilityFormat(ABC):
21
    """
22
    Represents an abstract string representation for vulnerability results.
23
    """
24
    
25
    @property
26
    @abstractmethod
27
    def is_manifest(self) -> bool:
28
        """
29
        Is this format a "manifest" format, i.e. one that prints a summary
30
        of all results?
31

32
        Manifest formats are always rendered emitted unconditionally, even
33
        if the audit results contain nothing out of the ordinary
34
        (no vulnerabilities, skips, or fixes).
35
        """
36
    
37
    @abstractmethod
38
    def format(
39
        self,
40
        result: dict[Dependency, list[VulnerabilityResult]],
41
        fixes: list[FixVersion],
42
    ) -> str:
43
        """
44
        Convert a mapping of dependencies to vulnerabilities into a string.
45
        
46
        Parameters:
47
        - result: dict mapping Dependency objects to lists of VulnerabilityResult
48
        - fixes: list of FixVersion objects for resolved fixes
49
        
50
        Returns:
51
        Formatted string representation of the results
52
        """
53
```
54

55
### Columns Format
56

57
Human-readable columnar text output format.
58

59
```python { .api }
60
class ColumnsFormat(VulnerabilityFormat):
61
    """
62
    A columnar format for vulnerability reports.
63
    
64
    Displays results in a table format with columns for package name, version,
65
    vulnerability ID, and description.
66
    """
67
    
68
    def __init__(self, output_desc: bool, output_aliases: bool):
69
        """
70
        Create a new ColumnsFormat.
71
        
72
        Parameters:
73
        - output_desc: bool, flag to determine whether descriptions for each vulnerability should be included
74
        - output_aliases: bool, flag to determine whether aliases (such as CVEs) should be included
75
        """
76
```
77

78
### JSON Format
79

80
Machine-readable JSON output format.
81

82
```python { .api }
83
class JsonFormat(VulnerabilityFormat):
84
    """
85
    A JSON format for vulnerability reports.
86
    
87
    Outputs structured JSON data suitable for programmatic consumption.
88
    """
89
    
90
    def __init__(self, output_desc: bool, output_aliases: bool):
91
        """
92
        Create a new JsonFormat.
93
        
94
        Parameters:
95
        - output_desc: bool, flag to determine whether descriptions for each vulnerability should be included
96
        - output_aliases: bool, flag to determine whether aliases (such as CVEs) should be included
97
        """
98
```
99

100
### Markdown Format
101

102
Markdown table output format.
103

104
```python { .api }
105
class MarkdownFormat(VulnerabilityFormat):
106
    """
107
    A Markdown format for vulnerability reports.
108
    
109
    Outputs results as Markdown tables suitable for documentation.
110
    """
111
    
112
    def __init__(self, output_desc: bool, output_aliases: bool) -> None:
113
        """
114
        Create a new MarkdownFormat.
115
        
116
        Parameters:
117
        - output_desc: bool, flag to determine whether descriptions for each vulnerability should be included
118
        - output_aliases: bool, flag to determine whether aliases (such as CVEs) should be included
119
        """
120
```
121

122
### CycloneDX Format
123

124
Software Bill of Materials (SBOM) format using CycloneDX standard.
125

126
```python { .api }
127
class CycloneDxFormat(VulnerabilityFormat):
128
    """
129
    A CycloneDX format for vulnerability reports.
130
    
131
    Generates Software Bill of Materials (SBOM) in CycloneDX format,
132
    including vulnerability information.
133
    """
134
    
135
    @enum.unique
136
    class InnerFormat(enum.Enum):
137
        """
138
        Valid container formats for CycloneDX.
139
        """
140
        Json = "JSON"
141
        Xml = "XML"
142
    
143
    def __init__(self, inner_format: InnerFormat):
144
        """
145
        Create a new CycloneDxFormat.
146
        
147
        Parameters:
148
        - inner_format: InnerFormat, determines the container format used by CycloneDX
149
        """
150
```
151

152
## Usage Examples
153

154
### Columnar Output
155

156
```python
157
from pip_audit._format import ColumnsFormat
158
from pip_audit._audit import Auditor
159
from pip_audit._dependency_source import PipSource
160
from pip_audit._service import PyPIService
161

162
# Create audit components
163
service = PyPIService()
164
source = PipSource()
165
auditor = Auditor(service=service)
166

167
# Format results as columns
168
formatter = ColumnsFormat()
169
audit_results = auditor.audit(source)
170
output = formatter.format(audit_results)
171
print(output)
172
```
173

174
### JSON Output
175

176
```python
177
from pip_audit._format import JsonFormat
178
from pip_audit._audit import Auditor
179
from pip_audit._dependency_source import RequirementSource
180
from pip_audit._service import OsvService
181
import json
182

183
# Create audit components
184
service = OsvService()
185
source = RequirementSource("requirements.txt")
186
auditor = Auditor(service=service)
187

188
# Format results as JSON
189
formatter = JsonFormat()
190
audit_results = auditor.audit(source)
191
json_output = formatter.format(audit_results)
192

193
# Parse and pretty print
194
data = json.loads(json_output)
195
print(json.dumps(data, indent=2))
196
```
197

198
### CycloneDX SBOM
199

200
```python
201
from pip_audit._format import CycloneDxFormat
202
from pip_audit._audit import Auditor
203
from pip_audit._dependency_source import PyProjectSource
204
from pip_audit._service import PyPIService
205

206
# Create audit components
207
service = PyPIService()
208
source = PyProjectSource("pyproject.toml")
209
auditor = Auditor(service=service)
210

211
# Generate SBOM
212
formatter = CycloneDxFormat(spec_version="1.4", output_format="json")
213
audit_results = auditor.audit(source)
214
sbom = formatter.format(audit_results)
215

216
# Save to file
217
with open("sbom.json", "w") as f:
218
    f.write(sbom)
219
```
220

221
### Custom Output File
222

223
```python
224
from pip_audit._format import MarkdownFormat
225
from pip_audit._audit import Auditor
226
from pip_audit._dependency_source import PipSource  
227
from pip_audit._service import PyPIService
228

229
# Create audit components
230
service = PyPIService()
231
source = PipSource()
232
auditor = Auditor(service=service)
233

234
# Write markdown output to file
235
with open("audit_report.md", "w") as f:
236
    formatter = MarkdownFormat(output_file=f, skip_empty=True)
237
    audit_results = auditor.audit(source)
238
    formatter.format(audit_results)
239

240
print("Audit report written to audit_report.md")
241
```