0
# py-solc
1

2
A comprehensive Python wrapper around the solc Solidity compiler, enabling developers to compile Solidity smart contracts directly from Python applications. Provides both standard JSON compilation and legacy combined JSON compilation methods, supports various solc versions (>=0.4.2), includes functionality for linking compiled code, and features an experimental solc binary installation system.
3

4
## Package Information
5

6
- **Package Name**: py-solc
7
- **Language**: Python  
8
- **Installation**: `pip install py-solc`
9
- **Dependencies**: 
10
  - `semantic_version>=2.6.0`
11
  - `solc` executable (>=0.4.2)
12

13
## Core Imports
14

15
```python
16
import solc
17
```
18

19
For specific functionality:
20

21
```python
22
from solc import (
23
    compile_source,
24
    compile_files,
25
    compile_standard,
26
    link_code,
27
    get_solc_version,
28
    get_solc_version_string,
29
    install_solc
30
)
31
```
32

33
## Basic Usage
34

35
### Standard JSON Compilation (Recommended)
36

37
```python
38
from solc import compile_standard
39

40
# Standard JSON compilation
41
result = compile_standard({
42
    'language': 'Solidity',
43
    'sources': {
44
        'Foo.sol': {
45
            'content': '''
46
                pragma solidity ^0.4.24;
47
                contract Foo {
48
                    function foo() public pure returns (uint) {
49
                        return 42;
50
                    }
51
                }
52
            '''
53
        }
54
    },
55
    'settings': {
56
        'outputSelection': {
57
            '*': {
58
                '*': ['abi', 'metadata', 'evm.bytecode', 'evm.bytecode.sourceMap']
59
            }
60
        }
61
    }
62
})
63

64
print(result['contracts']['Foo.sol']['Foo']['abi'])
65
```
66

67
### Legacy Combined JSON Compilation
68

69
```python
70
from solc import compile_source, compile_files
71

72
# Compile from source string
73
result = compile_source('''
74
    pragma solidity ^0.4.24;
75
    contract Foo {
76
        function foo() public pure returns (uint) {
77
            return 42;
78
        }
79
    }
80
''')
81

82
print(result['Foo']['abi'])
83

84
# Compile from files
85
result = compile_files(['/path/to/contract.sol'])
86
```
87

88
### Version Management and Installation
89

90
```python
91
from solc import get_solc_version, install_solc
92

93
# Check current solc version
94
version = get_solc_version()
95
print(f"Solc version: {version}")
96

97
# Install specific version
98
install_solc('v0.4.24')
99
```
100

101
## Capabilities
102

103
### Standard JSON Compilation
104

105
Modern compilation interface providing comprehensive control over compilation settings and outputs, supporting the Solidity standard JSON format.
106

107
```python { .api }
108
def compile_standard(input_data, allow_empty=False, **kwargs):
109
    """
110
    Compile using Solidity standard JSON interface.
111

112
    Args:
113
        input_data (dict): Standard JSON input data for compilation
114
        allow_empty (bool): Whether to allow compilation with no contracts found
115
        **kwargs: Additional arguments passed to solc wrapper
116

117
    Returns:
118
        dict: Standard JSON compilation output
119

120
    Raises:
121
        ContractsNotFound: When no contracts found and allow_empty=False
122
        SolcError: When compilation fails
123
    """
124
```
125

126
[Standard JSON Compilation](./standard-json-compilation.md)
127

128
### Legacy Combined JSON Compilation
129

130
Legacy compilation methods using the combined JSON output format, supporting older workflows and integrations.
131

132
```python { .api }
133
def compile_source(source, allow_empty=False, output_values=ALL_OUTPUT_VALUES, **kwargs):
134
    """Compile Solidity source code from a string."""
135

136
def compile_files(source_files, allow_empty=False, output_values=ALL_OUTPUT_VALUES, **kwargs):
137
    """Compile Solidity source files."""
138
```
139

140
[Legacy Compilation](./legacy-compilation.md)
141

142
### Bytecode Linking
143

144
Links compiled bytecode with library addresses to resolve library dependencies.
145

146
```python { .api }
147
def link_code(unlinked_data, libraries):
148
    """
149
    Link compiled bytecode with library addresses.
150

151
    Args:
152
        unlinked_data (str): Unlinked bytecode containing library placeholders
153
        libraries (dict): Dictionary mapping library names to addresses
154

155
    Returns:
156
        str: Linked bytecode with library placeholders replaced by actual addresses
157
    """
158
```
159

160
### Version Information
161

162
Gets version information from the solc compiler binary for compatibility checking and debugging.
163

164
```python { .api }
165
def get_solc_version_string(**kwargs):
166
    """Get the solc version string."""
167

168
def get_solc_version(**kwargs):
169
    """Get the solc version as semantic version object."""
170
```
171

172
### Solc Installation
173

174
Experimental functionality for installing specific versions of the solc compiler binary across different platforms.
175

176
```python { .api }
177
def install_solc(identifier, platform=None):
178
    """
179
    Install specified version of solc compiler.
180

181
    Args:
182
        identifier (str): Version identifier (e.g., 'v0.4.24')
183
        platform (str): Target platform ('linux', 'darwin', 'win32')
184

185
    Note:
186
        This is experimental functionality. Installed binary location:
187
        $HOME/.py-solc/solc-{version}/bin/solc
188
    """
189
```
190

191
[Installation](./installation.md)
192

193
### Exception Handling
194

195
Comprehensive error handling for compilation failures and system issues.
196

197
```python { .api }
198
class SolcError(Exception):
199
    """Base exception for solc compilation errors."""
200

201
class ContractsNotFound(SolcError):
202
    """Raised when no contracts are found during compilation."""
203
```
204

205
[Exceptions](./exceptions.md)
206

207
## Environment Configuration
208

209
### Environment Variables
210

211
- **SOLC_BINARY**: Path to solc executable (default: 'solc' from PATH)
212

213
### Import Path Remappings
214

215
All compilation functions support import remappings for cleaner project organization:
216

217
```python
218
from solc import compile_files
219

220
result = compile_files(
221
    ['contract.sol'],
222
    import_remappings=["zeppelin=/path/to/zeppelin-solidity"]
223
)
224
```
225

226
### Compilation Options
227

228
The `**kwargs` parameter in compilation functions supports solc command-line options:
229

230
```python
231
from solc import compile_source
232

233
result = compile_source(
234
    source_code,
235
    allow_paths="/path/to/imports",
236
    optimize=True,
237
    optimize_runs=200
238
)
239
```