0
# py-solc-x
1

2
A comprehensive Python wrapper and version management tool for the Solidity compiler (solc). py-solc-x enables developers to programmatically install, manage, and use multiple versions of the Solidity compiler with full cross-platform support for Linux, macOS, and Windows.
3

4
## Package Information
5

6
- **Package Name**: py-solc-x
7
- **Language**: Python
8
- **Installation**: `pip install py-solc-x`
9
- **Minimum Python Version**: 3.8
10
- **Supported Solidity Versions**: >=0.4.11
11

12
## Core Imports
13

14
```python
15
import solcx
16
```
17

18
Common usage patterns:
19

20
```python
21
from solcx import compile_source, compile_files, install_solc, set_solc_version
22
```
23

24
Specific imports:
25

26
```python
27
from solcx import (
28
    compile_source,
29
    compile_files, 
30
    compile_standard,
31
    get_solc_version,
32
    install_solc,
33
    get_installed_solc_versions,
34
    set_solc_version
35
)
36
```
37

38
## Basic Usage
39

40
```python
41
import solcx
42

43
# Install solc if not already installed
44
solcx.install_solc('0.8.19')
45
solcx.set_solc_version('0.8.19')
46

47
# Compile Solidity source code
48
source_code = '''
49
pragma solidity ^0.8.0;
50

51
contract SimpleStorage {
52
    uint256 public storedData;
53
    
54
    constructor(uint256 _initialData) {
55
        storedData = _initialData;
56
    }
57
    
58
    function set(uint256 _data) public {
59
        storedData = _data;
60
    }
61
    
62
    function get() public view returns (uint256) {
63
        return storedData;
64
    }
65
}
66
'''
67

68
# Compile from source string
69
compiled_sol = solcx.compile_source(source_code)
70
contract_interface = compiled_sol['<stdin>:SimpleStorage']
71

72
print("ABI:", contract_interface['abi'])
73
print("Bytecode:", contract_interface['bin'])
74

75
# Compile from files
76
# compiled_sol = solcx.compile_files(['contracts/MyContract.sol'])
77
```
78

79
## Architecture
80

81
py-solc-x provides three main layers of functionality:
82

83
- **High-level compilation API**: Functions like `compile_source()`, `compile_files()`, and `compile_standard()` that handle common compilation workflows
84
- **Version management system**: Install, manage, and switch between multiple solc versions with automatic binary management  
85
- **Low-level wrapper API**: Direct access to solc binary execution with full command-line argument support
86

87
The package automatically handles cross-platform differences, binary path management, and version resolution, making it simple to integrate Solidity compilation into Python applications and development workflows.
88

89
## Capabilities
90

91
### Solidity Compilation
92

93
Core compilation functions for compiling Solidity source code from strings, files, or using the standard JSON input/output interface. Supports all major solc compilation options including optimization, EVM target versions, and output customization.
94

95
```python { .api }
96
def compile_source(source: str, **kwargs) -> dict: ...
97
def compile_files(source_files: Union[List, Path, str], **kwargs) -> dict: ...
98
def compile_standard(input_data: dict, **kwargs) -> dict: ...
99
def link_code(unlinked_bytecode: str, libraries: dict, **kwargs) -> str: ...
100
def get_solc_version(with_commit_hash: bool = False) -> Version: ...
101
```
102

103
[Compilation](./compilation.md)
104

105
### Version Management
106

107
Install, manage, and switch between different versions of the Solidity compiler. Supports downloading precompiled binaries and compiling from source on Linux/macOS. Includes pragma-based version selection and automatic version resolution.
108

109
```python { .api }
110
def install_solc(version: Union[str, Version] = "latest", **kwargs) -> Version: ...
111
def compile_solc(version: Optional[Union[str, Version]] = None, **kwargs) -> Version: ...
112
def get_installable_solc_versions() -> List[Version]: ...
113
def get_compilable_solc_versions(**kwargs) -> List[Version]: ...
114
def get_installed_solc_versions(**kwargs) -> List[Version]: ...
115
def get_solcx_install_folder(**kwargs) -> Path: ...
116
def import_installed_solc(**kwargs) -> List[Version]: ...
117
def set_solc_version(version: Union[str, Version], **kwargs) -> None: ...
118
def set_solc_version_pragma(pragma_string: str, **kwargs) -> Version: ...
119
def install_solc_pragma(pragma_string: str, **kwargs) -> Version: ...
120
```
121

122
[Version Management](./version-management.md)
123

124
### Exception Handling
125

126
Comprehensive exception hierarchy for handling compilation errors, installation failures, version mismatches, and configuration issues. Provides detailed error information including command output and diagnostic data.
127

128
```python { .api }
129
class SolcError(Exception): ...
130
class ContractsNotFound(SolcError): ...
131
class SolcInstallationError(Exception): ...
132
class SolcNotInstalled(Exception): ...
133
class UnknownOption(AttributeError): ...
134
class UnknownValue(ValueError): ...
135
class UnexpectedVersionError(Exception): ...
136
class UnsupportedVersionError(ValueError): ...
137
class DownloadError(Exception): ...
138
class UnexpectedVersionWarning(Warning): ...
139
```
140

141
[Exception Handling](./exceptions.md)
142

143
### Low-Level Wrapper
144

145
Direct access to the Solidity compiler binary with full command-line argument support. Provides low-level control over solc execution for advanced use cases and custom compilation workflows.
146

147
```python { .api }
148
import solcx.wrapper
149
def solc_wrapper(**kwargs) -> Tuple[str, str, List, subprocess.Popen]: ...
150
def get_solc_version(solc_binary: Union[Path, str], **kwargs) -> Version: ...
151
def get_version_str_from_solc_binary(solc_binary: Union[Path, str]) -> str: ...
152
```
153

154
The wrapper module is available as `solcx.wrapper` and provides direct access to solc binary execution.
155

156
## Types
157

158
```python { .api }
159
from typing import Union, List, Dict, Optional, Any
160
from pathlib import Path
161
from packaging.version import Version
162

163
# Common type aliases used throughout the API
164
VersionType = Union[str, Version]
165
PathType = Union[Path, str]
166
SourceFiles = Union[List, Path, str]
167
ImportRemappings = Optional[Union[Dict, List, str]]
168
CompilerOutput = Dict[str, Any]
169
```