0
# Factory Functions
1

2
Factory functions provide convenient ways to create preconfigured Licensing instances with built-in license databases. These functions eliminate the need to manually load and configure license data, offering ready-to-use instances for SPDX and ScanCode license databases.
3

4
## Capabilities
5

6
### SPDX Licensing Factory
7

8
Create a Licensing instance configured with SPDX license database.
9

10
```python { .api }
11
def get_spdx_licensing(license_index_location=None) -> Licensing:
12
    """
13
    Create a Licensing instance configured with SPDX license database.
14
    
15
    Parameters:
16
    - license_index_location: Path to license index JSON file (optional, uses bundled database)
17
    
18
    Returns:
19
    Licensing instance with SPDX license symbols and compatibility rules
20
    """
21
```
22

23
### ScanCode Licensing Factory
24

25
Create a Licensing instance configured with ScanCode license database.
26

27
```python { .api }
28
def get_scancode_licensing(license_index_location=None) -> Licensing:
29
    """
30
    Create a Licensing instance configured with ScanCode license database.
31
    
32
    Parameters:
33
    - license_index_location: Path to license index JSON file (optional, uses bundled database)
34
    
35
    Returns:
36
    Licensing instance with ScanCode license symbols and extended database
37
    """
38
```
39

40
### License Index Loading
41

42
Load license index data from JSON files.
43

44
```python { .api }
45
def get_license_index(license_index_location=None) -> dict:
46
    """
47
    Load license index from JSON file.
48
    
49
    Parameters:
50
    - license_index_location: Path to license index JSON file (optional, uses bundled database)
51
    
52
    Returns:
53
    Dictionary containing license index data with symbols, aliases, and metadata
54
    """
55
```
56

57
### Builder Functions
58

59
Lower-level functions for creating Licensing instances from license index data.
60

61
```python { .api }
62
def build_licensing(license_index: dict) -> Licensing:
63
    """
64
    Build a Licensing instance from license index data.
65
    
66
    Parameters:
67
    - license_index: Dictionary containing license data
68
    
69
    Returns:
70
    Licensing instance with symbols from the index
71
    """
72

73
def build_spdx_licensing(license_index: dict) -> Licensing:
74
    """
75
    Build SPDX-compatible Licensing instance from license index data.
76
    
77
    Parameters:
78
    - license_index: Dictionary containing license data
79
    
80
    Returns:
81
    Licensing instance configured for SPDX compatibility
82
    """
83

84
def load_licensing_from_license_index(license_index: dict) -> Licensing:
85
    """
86
    Load Licensing instance from license index data.
87
    
88
    Parameters:
89
    - license_index: Dictionary containing license data
90
    
91
    Returns:
92
    Configured Licensing instance
93
    """
94
```
95

96
## Usage Examples
97

98
### Basic SPDX Usage
99

100
```python
101
from license_expression import get_spdx_licensing
102

103
# Create SPDX-compatible licensing instance
104
licensing = get_spdx_licensing()
105

106
# Parse SPDX expressions with automatic normalization
107
expression = 'GPL-2.0 or LGPL-2.1+'
108
parsed = licensing.parse(expression)
109
print(str(parsed))  # 'GPL-2.0-only OR LGPL-2.1-or-later'
110

111
# Validate against SPDX license list
112
result = licensing.validate('MIT and Apache-2.0')
113
print(result.errors)  # [] - both are valid SPDX licenses
114

115
# Test with deprecated SPDX identifiers
116
deprecated = licensing.parse('GPL-2.0+')  # Old format
117
print(str(deprecated))  # 'GPL-2.0-or-later' - normalized to current SPDX
118
```
119

120
### Basic ScanCode Usage
121

122
```python
123
from license_expression import get_scancode_licensing
124

125
# Create ScanCode licensing instance (more comprehensive database)
126
licensing = get_scancode_licensing()
127

128
# ScanCode includes additional license identifiers beyond SPDX
129
expression = 'proprietary-license or commercial-license'
130
parsed = licensing.parse(expression)
131
print(str(parsed))
132

133
# Access extended license database
134
result = licensing.validate('scancode-specific-license')
135
print(result.errors)  # May be empty if license exists in ScanCode DB
136
```
137

138
### Custom License Index
139

140
```python
141
from license_expression import get_license_index, build_licensing
142

143
# Load custom license index
144
custom_index = get_license_index('/path/to/custom/licenses.json')
145

146
# Build licensing from custom index
147
custom_licensing = build_licensing(custom_index)
148

149
# Use custom licensing instance
150
expr = custom_licensing.parse('CustomLicense1 or CustomLicense2')
151
```
152

153
### Comparing Factory Outputs
154

155
```python
156
from license_expression import get_spdx_licensing, get_scancode_licensing
157

158
spdx_licensing = get_spdx_licensing()
159
scancode_licensing = get_scancode_licensing()
160

161
# Test expression with both instances
162
test_expr = 'MIT and (Apache-2.0 or GPL-2.0+)'
163

164
spdx_result = spdx_licensing.parse(test_expr)
165
scancode_result = scancode_licensing.parse(test_expr)
166

167
print("SPDX result:", str(spdx_result))
168
print("ScanCode result:", str(scancode_result))
169

170
# Check license symbol counts
171
spdx_symbols = spdx_licensing.license_symbols(spdx_result)
172
scancode_symbols = scancode_licensing.license_symbols(scancode_result)
173

174
print(f"SPDX symbols found: {len(spdx_symbols)}")
175
print(f"ScanCode symbols found: {len(scancode_symbols)}")
176
```
177

178
### Working with License Index Data
179

180
```python
181
from license_expression import get_license_index
182

183
# Load and examine license index
184
index = get_license_index()
185

186
# Explore index structure
187
print("Index keys:", list(index.keys()))
188

189
# Access license data (structure depends on index format)
190
if 'licenses' in index:
191
    licenses = index['licenses']
192
    print(f"Total licenses in index: {len(licenses)}")
193
    
194
    # Show first few licenses
195
    for i, license_data in enumerate(licenses[:3]):
196
        print(f"License {i+1}: {license_data}")
197
```
198

199
### Custom Index Location
200

201
```python
202
from license_expression import get_spdx_licensing, get_scancode_licensing
203

204
# Use custom license index file
205
custom_spdx = get_spdx_licensing('/path/to/custom-spdx-index.json')
206
custom_scancode = get_scancode_licensing('/path/to/custom-scancode-index.json')
207

208
# These instances will use the custom license data instead of bundled data
209
```
210

211
### Building from Index Step-by-Step
212

213
```python
214
from license_expression import (
215
    get_license_index, 
216
    build_licensing, 
217
    build_spdx_licensing
218
)
219

220
# Load license index
221
index = get_license_index()
222

223
# Build different types of licensing instances
224
general_licensing = build_licensing(index)
225
spdx_licensing = build_spdx_licensing(index)
226

227
# Compare behavior
228
test_expr = 'MIT or GPL-2.0+'
229

230
general_result = general_licensing.parse(test_expr)
231
spdx_result = spdx_licensing.parse(test_expr)
232

233
print("General:", str(general_result))
234
print("SPDX:", str(spdx_result))
235
```
236

237
## Default License Database
238

239
The library includes a comprehensive license database:
240

241
- **Location**: Bundled within the package at `data/scancode-licensedb-index.json`
242
- **Size**: ~971KB containing extensive license metadata
243
- **Content**: SPDX license list (v3.26) + ScanCode LicenseDB
244
- **Update**: Based on ScanCode toolkit v32.3.1
245
- **Coverage**: Hundreds of license identifiers with aliases and metadata
246

247
### Accessing Bundled Database
248

249
```python
250
from license_expression import get_license_index
251
import json
252

253
# Load the bundled database
254
index = get_license_index()
255

256
# Save for examination (if needed)
257
with open('license_database.json', 'w') as f:
258
    json.dump(index, f, indent=2)
259

260
print(f"Database contains {len(index.get('licenses', []))} licenses")
261
```
262

263
## Error Handling
264

265
Factory functions include error handling for missing or invalid license data:
266

267
```python
268
from license_expression import get_spdx_licensing
269

270
try:
271
    # This will work with bundled database
272
    licensing = get_spdx_licensing()
273
except Exception as e:
274
    print(f"Error loading SPDX licensing: {e}")
275

276
try:
277
    # This may fail if custom file doesn't exist
278
    licensing = get_spdx_licensing('/nonexistent/path/licenses.json')
279
except Exception as e:
280
    print(f"Error loading custom licensing: {e}")
281
```