0
# Version Management
1

2
Comprehensive version management system for installing, managing, and switching between different versions of the Solidity compiler. Supports downloading precompiled binaries, compiling from source, and pragma-based version selection.
3

4
## Capabilities
5

6
### Installing Solidity Versions
7

8
Download and install precompiled versions of the Solidity compiler from the official Ethereum release channel.
9

10
```python { .api }
11
def install_solc(
12
    version: Union[str, Version] = "latest",
13
    show_progress: bool = False,
14
    solcx_binary_path: Optional[Union[Path, str]] = None,
15
) -> Version:
16
    """
17
    Download and install a precompiled version of solc.
18

19
    Parameters:
20
    - version: Version to install ('latest' or specific version like '0.8.19')
21
    - show_progress: Show download progress bar (requires tqdm package)
22
    - solcx_binary_path: Custom installation directory path
23

24
    Returns:
25
    Version object of installed solc version
26
    
27
    Raises:
28
    SolcInstallationError: Installation failed
29
    ConnectionError: Network/download error
30
    UnsupportedVersionError: Version not supported
31
    """
32
```
33

34
Usage example:
35

36
```python
37
import solcx
38

39
# Install latest version
40
latest_version = solcx.install_solc()
41
print(f"Installed: {latest_version}")
42

43
# Install specific version
44
solcx.install_solc('0.8.19')
45

46
# Install with progress bar (requires: pip install tqdm)
47
solcx.install_solc('0.7.6', show_progress=True)
48

49
# Install to custom directory
50
solcx.install_solc('0.8.0', solcx_binary_path='/custom/path/solc')
51
```
52

53
### Compiling from Source
54

55
Install Solidity by downloading and compiling source code. Available on Linux and macOS only.
56

57
```python { .api }
58
def compile_solc(
59
    version: Optional[Union[str, Version]] = None,
60
    show_progress: bool = False,
61
    solcx_binary_path: Optional[Union[Path, str]] = None,
62
) -> Version:
63
    """
64
    Install solc by downloading and compiling source code.
65

66
    Parameters:
67
    - version: Version to compile ('latest', None, or specific version)
68
    - show_progress: Show download progress bar
69
    - solcx_binary_path: Custom installation directory path
70

71
    Returns:
72
    Version object of compiled solc version
73
    
74
    Raises:
75
    OSError: Not supported on Windows
76
    SolcInstallationError: Compilation failed
77
    ConnectionError: Network/download error
78
    """
79
```
80

81
Usage example:
82

83
```python
84
import solcx
85

86
# Compile latest version from source (Linux/macOS only)
87
try:
88
    version = solcx.compile_solc()
89
    print(f"Compiled from source: {version}")
90
except OSError as e:
91
    print("Source compilation not supported on this platform")
92

93
# Compile specific version
94
solcx.compile_solc('0.8.19')
95
```
96

97
### Version Discovery
98

99
Get lists of available, installable, and already installed Solidity versions.
100

101
```python { .api }
102
def get_installable_solc_versions() -> List[Version]:
103
    """
104
    Return list of all solc versions that can be installed.
105

106
    Returns:
107
    List of Version objects for installable versions
108
    
109
    Raises:
110
    ConnectionError: Network error fetching version list
111
    """
112

113
def get_compilable_solc_versions(
114
    headers: Optional[Dict] = None, 
115
    rate_limit_wait_time: float = 3.0
116
) -> List[Version]:
117
    """
118
    Return list of all solc versions that can be compiled from source.
119

120
    Parameters:
121
    - headers: HTTP headers for GitHub API requests
122
    - rate_limit_wait_time: Wait time for rate limiting
123

124
    Returns:
125
    List of Version objects for compilable versions
126
    
127
    Raises:
128
    OSError: Not supported on Windows
129
    ConnectionError: Network error or GitHub API issues
130
    """
131

132
def get_installed_solc_versions(
133
    solcx_binary_path: Optional[Union[Path, str]] = None
134
) -> List[Version]:
135
    """
136
    Return list of currently installed solc versions.
137

138
    Parameters:
139
    - solcx_binary_path: Custom installation directory path
140

141
    Returns:
142
    List of Version objects for installed versions
143
    """
144
```
145

146
Usage example:
147

148
```python
149
import solcx
150

151
# Get all installable versions
152
installable = solcx.get_installable_solc_versions()
153
print(f"Available versions: {installable[:5]}...")  # First 5
154

155
# Get compilable versions (Linux/macOS only)
156
try:
157
    compilable = solcx.get_compilable_solc_versions()
158
    print(f"Compilable versions: {compilable[:3]}...")
159
except OSError:
160
    print("Source compilation not supported")
161

162
# Get installed versions
163
installed = solcx.get_installed_solc_versions()
164
print(f"Installed versions: {installed}")
165

166
# Check if specific version is installed
167
if Version('0.8.19') in installed:
168
    print("Version 0.8.19 is installed")
169
```
170

171
### Version Selection
172

173
Set the active Solidity compiler version for compilation operations.
174

175
```python { .api }
176
def set_solc_version(
177
    version: Union[str, Version],
178
    silent: bool = False,
179
    solcx_binary_path: Optional[Union[Path, str]] = None,
180
) -> None:
181
    """
182
    Set the currently active solc binary.
183

184
    Parameters:
185
    - version: Version to activate
186
    - silent: Suppress logging output
187
    - solcx_binary_path: Custom installation directory path
188

189
    Raises:
190
    SolcNotInstalled: Version not installed
191
    UnsupportedVersionError: Version not supported
192
    """
193

194
def get_solcx_install_folder(
195
    solcx_binary_path: Optional[Union[Path, str]] = None
196
) -> Path:
197
    """
198
    Return directory where py-solc-x stores installed solc binaries.
199

200
    Parameters:
201
    - solcx_binary_path: Custom path override
202

203
    Returns:
204
    Path to installation directory (default: ~/.solcx)
205
    """
206
```
207

208
Usage example:
209

210
```python
211
import solcx
212

213
# Install and set version
214
solcx.install_solc('0.8.19')
215
solcx.set_solc_version('0.8.19')
216

217
# Silent mode (no logging)
218
solcx.set_solc_version('0.7.6', silent=True)
219

220
# Check install folder
221
install_path = solcx.get_solcx_install_folder()
222
print(f"Solc binaries stored in: {install_path}")
223

224
# Custom install folder
225
custom_path = solcx.get_solcx_install_folder('/custom/path')
226
print(f"Custom path: {custom_path}")
227
```
228

229
### Pragma-Based Version Management
230

231
Automatically select and install Solidity versions based on pragma statements in source code.
232

233
```python { .api }
234
def set_solc_version_pragma(
235
    pragma_string: str, 
236
    silent: bool = False, 
237
    check_new: bool = False
238
) -> Version:
239
    """
240
    Set active solc binary based on pragma statement.
241

242
    Parameters:
243
    - pragma_string: Pragma statement (e.g., "pragma solidity ^0.8.0;")
244
    - silent: Suppress logging output
245
    - check_new: Check for newer compatible versions
246

247
    Returns:
248
    Version object of selected version
249
    
250
    Raises:
251
    SolcNotInstalled: No compatible version installed
252
    """
253

254
def install_solc_pragma(
255
    pragma_string: str,
256
    install: bool = True,
257
    show_progress: bool = False,
258
    solcx_binary_path: Optional[Union[Path, str]] = None,
259
) -> Version:
260
    """
261
    Find and optionally install latest compatible solc version based on pragma.
262

263
    Parameters:
264
    - pragma_string: Pragma statement
265
    - install: Whether to install the version
266
    - show_progress: Show download progress bar
267
    - solcx_binary_path: Custom installation directory path
268

269
    Returns:
270
    Version object of compatible version
271
    
272
    Raises:
273
    UnsupportedVersionError: No compatible version exists
274
    """
275
```
276

277
Usage example:
278

279
```python
280
import solcx
281

282
# Set version based on pragma
283
pragma = "pragma solidity ^0.8.0;"
284
version = solcx.set_solc_version_pragma(pragma)
285
print(f"Selected version: {version}")
286

287
# Install latest compatible version for pragma
288
pragma = "pragma solidity >=0.7.0 <0.9.0;"
289
latest_compatible = solcx.install_solc_pragma(pragma, show_progress=True)
290
print(f"Installed: {latest_compatible}")
291

292
# Just find compatible version without installing
293
pragma = "pragma solidity ~0.8.19;"
294
compatible = solcx.install_solc_pragma(pragma, install=False)
295
print(f"Compatible version found: {compatible}")
296

297
# Complex pragma with OR conditions
298
pragma = "pragma solidity ^0.8.0 || ^0.7.0;"
299
version = solcx.install_solc_pragma(pragma)
300
print(f"Selected from multiple ranges: {version}")
301
```
302

303
### Import Existing Installations
304

305
Import and copy existing Solidity installations into py-solc-x's managed directory.
306

307
```python { .api }
308
def import_installed_solc(
309
    solcx_binary_path: Optional[Union[Path, str]] = None
310
) -> List[Version]:
311
    """
312
    Search for and copy installed solc versions into local installation folder.
313

314
    Parameters:
315
    - solcx_binary_path: Custom installation directory path
316

317
    Returns:
318
    List of Version objects for imported versions
319
    """
320
```
321

322
Usage example:
323

324
```python
325
import solcx
326

327
# Import system-installed solc versions
328
imported = solcx.import_installed_solc()
329
if imported:
330
    print(f"Imported versions: {imported}")
331
else:
332
    print("No existing installations found")
333

334
# Import to custom directory
335
imported = solcx.import_installed_solc(solcx_binary_path='/custom/path')
336
print(f"Imported to custom location: {imported}")
337
```
338

339
## Environment Variables
340

341
py-solc-x respects the following environment variables:
342

343
- `SOLCX_BINARY_PATH`: Override default installation directory (default: `~/.solcx`)
344
- `GITHUB_TOKEN`: GitHub API token for avoiding rate limits when fetching version info
345

346
```python
347
import os
348
import solcx
349

350
# Set custom binary path via environment
351
os.environ['SOLCX_BINARY_PATH'] = '/opt/solc'
352
install_path = solcx.get_solcx_install_folder()
353
print(f"Install path: {install_path}")  # /opt/solc
354

355
# Set GitHub token to avoid rate limits
356
os.environ['GITHUB_TOKEN'] = 'your_github_token_here'
357
compilable = solcx.get_compilable_solc_versions()
358
```
359

360
## Error Handling
361

362
Version management functions raise specific exceptions:
363

364
```python
365
import solcx
366
from solcx import SolcNotInstalled, SolcInstallationError, UnsupportedVersionError
367

368
try:
369
    # This might fail if version isn't installed
370
    solcx.set_solc_version('0.8.99')
371
except SolcNotInstalled as e:
372
    print(f"Version not installed: {e}")
373

374
try:
375
    # This might fail if version doesn't exist
376
    solcx.install_solc('0.99.99')
377
except SolcInstallationError as e:
378
    print(f"Installation failed: {e}")
379

380
try:
381
    # This might fail for old versions
382
    solcx.install_solc('0.3.0')
383
except UnsupportedVersionError as e:
384
    print(f"Version not supported: {e}")
385
```