Metadata-Version: 2.4
Name: invisibles-py
Version: 0.1.0
Summary: Transparent remote object proxying
Author-email: Gor Arakelyan <gorarkln@gmail.com>
Maintainer-email: Gor Arakelyan <gorarkln@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/nustackdev/invisibles
Project-URL: Documentation, https://github.com/nustackdev/invisibles#readme
Project-URL: Repository, https://github.com/nustackdev/invisibles
Project-URL: Issues, https://github.com/nustackdev/invisibles/issues
Project-URL: Changelog, https://github.com/nustackdev/invisibles/releases
Project-URL: PyPI, https://pypi.org/project/invisibles-py/
Keywords: proxy,rpc,remote,object,networking,asynchronous,sockets
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: msgpack>=1.0.0
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=1.2.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Provides-Extra: all
Requires-Dist: invisibles[dev,test]; extra == "all"
Dynamic: license-file

# 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.

```python
# 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](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](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](docs/overview.md) - execution model and design rationale
- [docs/architecture.md](docs/architecture.md) - concepts, flow diagrams, boxing
- [docs/scenarios.md](docs/scenarios.md) - deployment scenarios matrix
- [docs/netkit.md](docs/netkit.md) - networking layer (vendored)

## License

Apache-2.0 - See [LICENSE.md](LICENSE.md)
