0
# RPyC
1

2
Remote Python Call (RPyC) is a transparent and symmetric distributed computing library that enables distributed computing across processes and computers. It uses object-proxying techniques to leverage Python's dynamic nature, allowing remote objects to be manipulated as if they were local.
3

4
## Package Information
5

6
- **Package Name**: rpyc
7
- **Language**: Python
8
- **Installation**: `pip install rpyc`
9
- **Dependencies**: plumbum
10

11
## Core Imports
12

13
```python
14
import rpyc
15
```
16

17
Common patterns for different use cases:
18

19
```python
20
# For general connections
21
from rpyc import connect, connect_by_service, ssl_connect
22

23
# For classic mode
24
from rpyc import classic
25

26
# For services
27
from rpyc import Service, exposed
28

29
# For servers
30
from rpyc.utils.server import ThreadedServer, ThreadPoolServer, ForkingServer
31

32
# For registry and discovery
33
from rpyc.utils.registry import UDPRegistryServer, UDPRegistryClient
34

35
# For authentication
36
from rpyc.utils.authenticators import SSLAuthenticator
37

38
# For streams and channels
39
from rpyc.core import SocketStream, Channel
40
```
41

42
## Basic Usage
43

44
### Simple Connection
45

46
```python
47
import rpyc
48

49
# Connect to an RPyC server
50
conn = rpyc.connect('hostname', 12345)
51

52
# Access remote objects through the root namespace
53
result = conn.root.some_remote_function('argument')
54

55
# Close the connection
56
conn.close()
57
```
58

59
### Classic Mode
60

61
```python
62
import rpyc
63

64
# Connect in classic mode for direct Python execution
65
conn = rpyc.classic.connect('hostname')
66

67
# Execute Python code remotely
68
conn.execute('x = 5 + 3')
69

70
# Evaluate expressions
71
result = conn.eval('x * 2')  # Returns 16
72

73
# Access remote modules
74
files = conn.modules.os.listdir('/tmp')
75

76
# Access remote builtins
77
remote_file = conn.builtin.open('/path/to/file', 'r')
78
content = remote_file.read()
79

80
conn.close()
81
```
82

83
### Creating Services
84

85
```python
86
import rpyc
87
from rpyc import exposed
88

89
class MyService(rpyc.Service):
90
    @exposed
91
    def get_data(self, key):
92
        return f"Data for {key}"
93
    
94
    @exposed
95
    def process_list(self, items):
96
        return [item.upper() for item in items]
97

98
# Run a server with the service
99
from rpyc.utils.server import ThreadedServer
100
server = ThreadedServer(MyService, port=12345)
101
server.start()
102
```
103

104
## Architecture
105

106
RPyC's architecture is built around several key components:
107

108
- **Connection**: Protocol-level communication channel with automatic object proxying
109
- **Services**: Define what remote objects and methods are exposed across the connection
110
- **Netrefs**: Transparent proxy objects that represent remote objects locally
111
- **Streams**: Low-level transport mechanisms (TCP, SSL, pipes, SSH tunnels, etc.)
112
- **Servers**: Multi-threaded, forking, or single-shot server implementations
113

114
The symmetric design means both sides of a connection can expose services to each other, enabling bidirectional remote procedure calls and distributed computing patterns.
115

116
## Capabilities
117

118
### Connection and Factory Functions
119

120
Core connection functionality including TCP, SSL, Unix socket, SSH tunnel, subprocess, and service discovery connections. These functions provide the primary ways to establish RPyC connections.
121

122
```python { .api }
123
def connect(host, port, service=VoidService, config={}, ipv6=False, keepalive=False): ...
124
def ssl_connect(host, port, keyfile=None, certfile=None, ca_certs=None, **kwargs): ...
125
def connect_by_service(service_name, host=None, registrar=None, timeout=2, **kwargs): ...
126
def discover(service_name, host=None, registrar=None, timeout=2): ...
127
```
128

129
[Connection and Factory Functions](./connection-factory.md)
130

131
### Services and Protocols
132

133
Service classes for defining remote interfaces and protocol management for handling connections. Includes base service classes, specialized service types, and connection management.
134

135
```python { .api }
136
class Service: ...
137
class VoidService(Service): ...
138
class SlaveService(Service): ...
139
class MasterService(Service): ...
140
class ClassicService(MasterService, SlaveService): ...
141
class Connection: ...
142
```
143

144
[Services and Protocols](./services-protocols.md)
145

146
### Classic Mode
147

148
Classic RPyC functionality providing direct remote Python execution, module access, and file transfer capabilities. This mode allows transparent remote code execution and filesystem operations.
149

150
```python { .api }
151
def connect(host, port=18812, ipv6=False, keepalive=False): ...
152
def execute(code): ...
153
def eval(expression): ...
154
def upload(conn, localpath, remotepath, filter=None, **kwargs): ...
155
def download(conn, remotepath, localpath, filter=None, **kwargs): ...
156
```
157

158
[Classic Mode](./classic-mode.md)
159

160
### Server Implementations
161

162
Multi-threaded, forking, and specialized server implementations for hosting RPyC services. Includes configuration options for different deployment scenarios.
163

164
```python { .api }
165
class ThreadedServer(Server): ...
166
class ThreadPoolServer(Server): ...
167
class ForkingServer(Server): ...
168
class OneShotServer(Server): ...
169
```
170

171
[Server Implementations](./servers.md)
172

173
### Utilities and Helpers
174

175
Additional utilities including asynchronous operations, timeouts, background threads, decorators, and low-level helpers for advanced RPyC usage.
176

177
```python { .api }
178
def async_(proxy): ...
179
def timed(timeout, func): ...
180
class BgServingThread: ...
181
def exposed(func): ...
182
def restricted(obj, attrs, wattrs=None): ...
183
```
184

185
[Utilities and Helpers](./utilities.md)
186

187
### Registry and Service Discovery
188

189
Service registry and discovery system for automatic service location and management. Enables services to advertise availability and clients to discover services by name.
190

191
```python { .api }
192
class UDPRegistryServer: ...
193
class TCPRegistryServer: ...
194
class UDPRegistryClient: ...
195
class TCPRegistryClient: ...
196
def discover(service_name): ...
197
def list_services(): ...
198
```
199

200
[Registry and Service Discovery](./registry-and-discovery.md)
201

202
### Authentication and Security
203

204
Authentication mechanisms and security features for securing RPyC connections and services. Includes SSL/TLS authentication, custom authenticators, and security configuration.
205

206
```python { .api }
207
class SSLAuthenticator: ...
208
class Authenticator: ...
209
def create_secure_config(): ...
210
def restricted_service(): ...
211
```
212

213
[Authentication and Security](./authentication-and-security.md)
214

215
### CLI Tools
216

217
Command-line utilities for running RPyC servers and registries. Ready-to-use server implementations and registry services for deployment without custom code.
218

219
```python { .api }
220
# Command-line tools:
221
# rpyc_classic [OPTIONS]     - Classic RPyC server
222
# rpyc_registry [OPTIONS]    - Registry server
223

224
# Server modes: stdio, threaded, forking, oneshot
225
# Registry modes: UDP, TCP
226
```
227

228
[CLI Tools](./cli-tools.md)
229

230
### Streams and Channels
231

232
Low-level transport mechanisms and communication channels for RPyC connections. Provides underlying transport layer for different communication methods.
233

234
```python { .api }
235
class SocketStream: ...
236
class TunneledSocketStream: ...
237
class PipeStream: ...
238
class Channel: ...
239
class CompressedChannel: ...
240
```
241

242
[Streams and Channels](./streams-and-channels.md)
243

244
## Types
245

246
```python { .api }
247
class BaseNetref:
248
    """Base class for network references (remote object proxies)"""
249

250
class AsyncResult:
251
    """Container for asynchronous operation results"""
252
    def ready(self) -> bool: ...
253
    def wait(self, timeout=None): ...
254
    def value(self): ...
255

256
class AsyncResultTimeout(Exception):
257
    """Raised when async operations timeout"""
258

259
class GenericException(Exception):
260
    """Wrapper for remote exceptions"""
261

262
# Stream and Channel classes
263
class SocketStream: ...
264
class TunneledSocketStream: ...  
265
class PipeStream: ...
266
class Channel: ...
267
class CompressedChannel: ...
268
class EncryptedChannel: ...
269

270
# Registry classes
271
class UDPRegistryServer: ...
272
class TCPRegistryServer: ...
273
class UDPRegistryClient: ...
274
class TCPRegistryClient: ...
275

276
# Authentication classes
277
class SSLAuthenticator: ...
278
class AuthenticationError(Exception): ...
279

280
# Configuration constants
281
DEFAULT_CONFIG: dict
282
SECURE_DEFAULT_CONFIG: dict
283
REGISTRY_PORT: int
284
DEFAULT_SSL_PORT: int
285
```