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
```