invisibles-py 0.1.0

Transparent remote object proxying

Invisibles

Transparent remote method invocation. Same object, same usage, different location.

What It Does

You have an object. You want to move it to another process, another node. The code that uses it doesn't change.

# Local
result = service.add(5, 3)
data = await service.fetch("key")

# Remote - identical
result = proxy.add(5, 3)
data = await proxy.fetch("key")

Sync methods stay sync. Async methods stay async. The proxy matches the remote object's API exactly.

Architecture

Two connection channels, each doing what it's good at:

• Sync connection - reentrant serving pattern, handles sync methods and protocol operations
• Async connection - message pump with asyncio futures, handles async methods natively

Both share a Protocol instance that manages boxing, dispatch, and proxy creation. See docs/architecture.md for details.

Key Concepts

• Service - any Python object exposed remotely, no base class needed
• Connection - per-client RPC channel (sync or async), wraps netkit transport
• Proxy - client-side transparent handle, created automatically during unboxing
• Protocol - shared RPC state: boxing, dispatch, object registry, proxy caching
• Dispatcher - how sync method calls are run (inline, threaded, or shared)

Deployment Scenarios

Object type	Clients	Execution	Setup
Sync, not thread-safe	Single	Serialized	SyncServer + InlineDispatcher
Sync, not thread-safe	Multiple	Serialized	SyncServer + SharedDispatcher
Sync, thread-safe	Multiple	Parallel	SyncServer + ThreadedDispatcher
Async / Mixed	Any	Async on server loop	SyncServer + AsyncDispatcher

See docs/scenarios.md for the full matrix.

Python Protocol Support

Works transparently over RPC:

• Method calls (sync and async)
• Attribute access
• Iterators and generators (for x in proxy)
• Async iterators (async for x in proxy)
• Context managers (with proxy)
• Async context managers (async with proxy)
• Operator overloading (+, -, *, [], in, len, etc.)
• Callable objects (proxy(args))
• Exception propagation (including custom exception classes)
• Nested objects (methods returning objects that are themselves proxied)

Docs

• docs/overview.md - execution model and design rationale
• docs/architecture.md - concepts, flow diagrams, boxing
• docs/scenarios.md - deployment scenarios matrix
• docs/netkit.md - networking layer (vendored)

License

Apache-2.0 - See LICENSE.md