Pywayne Cross Comm
pywayne.cross_comm.CrossCommService provides WebSocket-based real-time communication between Python and other languages, with built-in file transfer via Aliyun OSS.
Prerequisites
OSS Configuration (required for file/image/folder transfer):
File transfers use Aliyun OSS. Set these environment variables:
# .env file
OSS_ENDPOINT=your-oss-endpoint
OSS_BUCKET_NAME=your-bucket-name
OSS_ACCESS_KEY_ID=your-access-key
OSS_ACCESS_KEY_SECRET=your-access-secret
For more OSS details, see pywayne-aliyun-oss skill.
Quick Start
import asyncio
from pywayne.cross_comm import CrossCommService, CommMsgType
# Server
server = CrossCommService(role='server', ip='0.0.0.0', port=9898)
await server.start_server()
# Client
client = CrossCommService(role='client', ip='localhost', port=9898, client_id='my_client')
await client.login()
Server
Initialize server
server = CrossCommService(
role='server',
ip='0.0.0.0', # Listen on all interfaces
port=9898,
heartbeat_interval=30, # Seconds between heartbeats
heartbeat_timeout=60 # Seconds before marking offline
)
Register message listeners
@server.message_listener(msg_type=CommMsgType.TEXT)
async def handle_text(message):
print(f"From {message.from_client_id}: {message.content}")
@server.message_listener(msg_type=CommMsgType.FILE, download_directory="./downloads")
async def handle_file(message):
print(f"File downloaded: {message.content}")
Start server
await server.start_server() # Blocks until server stops
Get online clients
online_clients = server.get_online_clients() # Returns list of client IDs
Client
Initialize client
client = CrossCommService(
role='client',
ip='localhost', # Server address
port=9898,
client_id='my_client', # Optional: auto-generated if omitted
heartbeat_interval=30,
heartbeat_timeout=60
)
Login and logout
success = await client.login()
if success:
print("Connected!")
# ... communicate ...
await client.logout()
Send messages
# Broadcast to all
await client.send_message("Hello!", CommMsgType.TEXT)
# Send to specific client
await client.send_message("Private", CommMsgType.TEXT, to_client_id='target_id')
# JSON message
await client.send_message('{"key": "value"}', CommMsgType.JSON)
# Dict message
await client.send_message({"type": "data", "value": 123}, CommMsgType.DICT)
# Bytes (auto base64 encoded)
await client.send_message(b"binary", CommMsgType.BYTES)
# File (auto uploads to OSS)
await client.send_message("/path/to/file.txt", CommMsgType.FILE)
# Image (auto uploads to OSS)
await client.send_message("/path/to/image.jpg", CommMsgType.IMAGE)
# Folder (auto uploads to OSS)
await client.send_message("/path/to/folder", CommMsgType.FOLDER)
Get client list
# All clients (online + offline)
all_clients = await client.list_clients(only_show_online=False)
# Returns: {'clients': [...], 'total_count': N, 'only_show_online': False}
# Online only
online = await client.list_clients(only_show_online=True)
Message Types
CommMsgType enum (use these, not strings):
| Type | Description |
|---|
CommMsgType.TEXT | Plain text |
CommMsgType.JSON | JSON string |
CommMsgType.DICT | Python dict |
CommMsgType.BYTES | Binary data |
CommMsgType.IMAGE | Image file |
CommMsgType.FILE | Regular file |
CommMsgType.FOLDER | Folder |
Internal types (auto-handled): HEARTBEAT, LOGIN, LOGOUT, LIST_CLIENTS, LIST_CLIENTS_RESPONSE, LOGIN_RESPONSE
Message Listener Decorator
# Listen to specific type
@service.message_listener(msg_type=CommMsgType.TEXT)
async def handler(message):
pass
# Listen from specific sender
@service.message_listener(msg_type=CommMsgType.FILE, from_client_id='specific_client')
async def handler(message):
pass
# Listen to all types
@service.message_listener()
async def handler(message):
pass
Note: Listeners automatically filter out messages sent by yourself.
File Download Control
File downloads are controlled via the listener's download_directory parameter:
# Auto-download files to ./downloads
@client.message_listener(msg_type=CommMsgType.FILE, download_directory="./downloads")
async def handle_file(message):
# message.content contains downloaded file path
print(f"Downloaded: {message.content}")
# No auto-download - saves bandwidth
@client.message_listener(msg_type=CommMsgType.FILE, from_client_id='low_priority')
async def handle_file(message):
# message.content contains OSS key, not downloaded
print(f"File available: {message.oss_key}")
# Optionally: client.download_file_manually(message.oss_key, "./manual_downloads/")
Manual download
success = client.download_file_manually(
oss_key="cross_comm/sender_id/123456_file.txt",
save_directory="./downloads"
)
Message Object
@dataclass
class Message:
msg_id: str # Unique message ID
from_client_id: str # Sender ID
to_client_id: str # 'all' or specific client ID
msg_type: CommMsgType # Message type enum
content: Any # Message content
timestamp: float # Unix timestamp
oss_key: Optional[str] # OSS key for file transfers
def to_dict(self) -> Dict: # Convert to dict
@classmethod
def from_dict(cls, data) -> 'Message': # Create from dict
Client ID Generation
If client_id is not specified, it's auto-generated using MAC address + UUID:
- Format:
{mac_address}_{uuid_suffix}
- Example:
a1b2c3d4e5f6_abc12345
Command Line
# Run server
python -m pywayne.cross_comm server
# Run client
python -m pywayne.cross_comm client
Important Notes
- File transfer: Requires OSS environment variables; files auto-upload on send
- Async required: All operations are async; use
asyncio.run() or await in async context
- Heartbeat: Auto-managed; adjust intervals for network conditions
- Message filtering: Use
download_directory to control auto-downloads and save bandwidth
- State persistence: Server saves client status to
cross_comm_clients.yaml
- Role-specific methods: Server has
start_server(), get_online_clients(); client has login(), logout(), send_message(), list_clients()
