Initial draft rsocket python guide (for future version 0.3) (#64)

Author: Gabriel Shaar

content-docs/guides/index.mdx

@@ -9,3 +9,4 @@ In this section you will find guides related to working with and consuming the v
 ## Language Specific Guides
 
 - [`rsocket-js`](./rsocket-js/index.mdx)
+- [`rsocket-py`](./rsocket-py/index.mdx)

content-docs/guides/rsocket-py/client/introduction.mdx

@@ -0,0 +1,147 @@
+---
+slug: /guides/rsocket-py/client
+title: RSocketClient - rsocket-py
+sidebar_label: Introduction
+---
+
+An `rsocket-py` client can be used to communicate with any RSocket Server implemented against the same protocol version as the client,
+and which implements the same transport as the client.
+
+Available network transports for `rsocket-py` client include:
+
+- TCP - available by default
+- Websocket (aiohttp)
+
+The `RSocketClient` class should be passed an instance of one of the available transports.
+
+To get started creating an RSocket client, you will need to install the [rsocket](https://pypi.org/project/rsocket/) package,
+and at least one transport protocol implementation (TCP available by default).
+
+### Client Quick Start Example
+
+```
+npm install rsocket-core rsocket-websocket-client
+```
+
+```py
+import asyncio
+from rsocket.rsocket_client import RSocketClient
+from rsocket.transports.tcp import TransportTCP
+
+async def main():
+    connection = await asyncio.open_connection('localhost', 6565)
+
+    async with RSocketClient(TransportTCP(*connection)) as client:
+        ... # Execute requests
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## Client API
+
+The `rsocket-py` package exposes the following types:
+
+## RSocketClient (class)
+
+`RSocketClient` is used to create an instance of a client. The clients' connection does not initialize until
+the `connect` method is invoked, or it is used as a context-manager.
+
+### constructor (function)
+
+
+#### serializers (property)
+
+The `data` and `metadata` of each payload are passed through to the
+transport layer as-is. This is appropriate for sending/receiving strings/binary.
+
+
+#### transport (property)
+
+This will typically be an instance conforming to the API of the `Transport` class.
+
+
+### connect() (method)
+
+This method opens the connection to the peer. Internally this calls `connect()` on the
+transport client. See below for the `RSocket` interface.
+
+## RSocket (interface)
+
+This interface represents an instance of a rsocket peer-to-peer connection, providing the five
+core interactions (fire/forget, request/response, etc.):
+
+### fire_and_forget() (method)
+
+This method sends data/metadata to the server without waiting for a response. The data is
+sent immediately.
+
+```py
+from rsocket.payload import Payload
+
+def fire_and_forget(self, payload: Payload):
+    ...
+```
+
+### request_response() (method)
+
+This method sends data/metadata to the server, which returns a single response. The data is
+sent lazily when the returned `Future` is resolved.
+
+```py
+from rsocket.payload import Payload
+from asyncio import Future
+
+def request_response(self, payload: Payload) -> Future:
+    ...
+```
+
+### request_stream() (method)
+
+This method sends data/metadata to the server, which returns a stream of responses. The semantics
+of the stream are application-specific. For example, the stream may represent
+updates to a single conceptual value over time, items in an incrementally loaded
+list, events, etc. The data is sent to the peer lazily when the returned
+`Publisher` is subscribed to and `request(n)` is called to signal demand.
+
+```py
+from typing import Union
+
+from reactivestreams.publisher import Publisher
+from rsocket.payload import Payload
+from rsocket.streams.stream import Stream
+
+def request_stream(self, payload: Payload) -> Union[Stream, Publisher]:
+    ...
+```
+
+### requestChannel() (method)
+
+This method establishes an understanding between a client and a server where each intends to send and receive streams
+of data from the other. Each actor in this relationship is responsible for signaling to the other that they are ready
+to receive data by invoking `request(n)`, where `n` is the max number of payloads the actor is comfortable handling.
+Conceptually, `request_channel` can be thought of as two entities 'polling' from each other by signaling to the others
+that they are ready to accept `n` number of messages. Inversely, `request_channel` can be leveraged to facilitate
+a consistent stream of data transfer payloads between client and server by each (or either)
+invoking `request(0x7fffffff)`, where `0x7fffffff` is the max integer value for `int32`.
+
+```py
+from typing import Union, Optional
+
+from reactivestreams.publisher import Publisher
+from rsocket.payload import Payload
+from rsocket.streams.stream import Stream
+
+def request_channel(self, payload: Payload, publisher: Optional[Publisher] = None) -> Union[Stream, Publisher]:
+    ...
+```
+
+### metadata_push() (method)
+
+This method sends metadata only to the server without waiting for a response. The payload is
+sent immediately. This method is not for the direct application usage and should be used to exchange some service level information
+
+```python
+def metadata_push(self, metadata: bytes):
+    ...
+```

content-docs/guides/rsocket-py/client/rsocket-tcp-client.mdx

@@ -0,0 +1,30 @@
+---
+slug: /guides/rsocket-py/client/rsocket-tcp-client
+title: RSocketTCPClient - rsocket-py
+sidebar_label: TCP Client
+---
+
+The `TransportTCP` implements the RSocket protocol using the TCP network transport protocol,
+and is suitable for Server to Server, and other scenarios where raw TCP is available.
+
+
+### TCP Client Quick Start Example
+
+```
+npm install rsocket-core rsocket-tcp-client
+```
+
+```py
+import asyncio
+from rsocket.rsocket_client import RSocketClient
+from rsocket.transports.tcp import TransportTCP
+
+async def main():
+    connection = await asyncio.open_connection('localhost', 6565)
+
+    async with RSocketClient(TransportTCP(*connection)) as client:
+        ... # Execute requests
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```

content-docs/guides/rsocket-py/client/rsocket-websocket-client.mdx

@@ -0,0 +1,27 @@
+---
+slug: /guides/rsocket-py/client/rsocket-websocket-client
+title: RSocketWebsocketClient - rsocket-py
+sidebar_label: WebSocket Client
+---
+
+The `RSocketWebsocketClient` implements the RSocket protocol using the WebSocket network transport protocol, and is suitable for Server to Server, and Client to Server scenarios where raw TCP is not available, such as in a web browser.
+
+### WebSocket Client Quick Start Example
+
+
+```py
+import asyncio
+
+from rsocket.payload import Payload
+from rsocket.transports.aiohttp_websocket import websocket_client
+
+
+async def application():
+    async with websocket_client('http://localhost:6565') as client:
+        result = await client.request_response(Payload(b'ping'))
+        print(result)
+
+
+if __name__ == '__main__':
+    asyncio.run(application())
+```

content-docs/guides/rsocket-py/index.mdx

@@ -0,0 +1,128 @@
+---
+slug: /guides/rsocket-py
+title: rsocket-py
+sidebar_label: Introduction
+---
+
+:::important
+This documentation is for version 0.3.0 of `rsocket` (currently only available via git-hub)
+:::
+
+:::caution
+The python package API is not stable. There may be changes until version 1.0.0
+:::
+
+The python `rsocket` package implements the 1.0 version of the [RSocket protocol](https://rsocket.io/about/protocol)
+and is designed for use in python >= 3.8 using asyncio.
+
+## Packages
+
+A pypi package is available at [rsocket](https://pypi.org/project/rsocket/)
+
+## Status
+
+The following are currently implemented:
+
+- RSocketClient / RSocketServer
+- TCP/WebSocket server/client transport (Websocket integration with Quart and aiohttp)
+- Minimal integration with RxPy >= 3.x
+
+## WebSocket Client & Server example
+
+### Client Example
+
+The client sends a `request/response` message to the server on an interval, with the requested date-time format, and exits after a certain amount of time has elapsed.
+
+```py
+# client.py
+import asyncio
+import logging
+
+from reactivestreams.subscriber import Subscriber
+from rsocket.payload import Payload
+from rsocket.rsocket_client import RSocketClient
+from rsocket.transports.tcp import TransportTCP
+
+
+class StreamSubscriber(Subscriber):
+
+    async def on_next(self, value, is_complete=False):
+        await self.subscription.request(1)
+
+    def on_subscribe(self, subscription):
+        self.subscription = subscription
+
+
+async def main():
+    connection = await asyncio.open_connection('localhost', 6565)
+
+    async with RSocketClient(TransportTCP(*connection)) as client:
+        payload = Payload(b'%Y-%m-%d %H:%M:%S')
+
+        async def run_request_response():
+            try:
+                while True:
+                    result = await client.request_response(payload)
+                    logging.info('Response: {}'.format(result.data))
+                    await asyncio.sleep(1)
+            except asyncio.CancelledError:
+                pass
+
+        task = asyncio.create_task(run_request_response())
+
+        await asyncio.sleep(5)
+        task.cancel()
+        await task
+
+
+if __name__ == '__main__':
+    logging.basicConfig(level=logging.DEBUG)
+    asyncio.run(main())
+```
+
+### Server Example
+
+The server responds to `request/response` messages with the current formatted date-time.
+
+```py
+# server.py
+import asyncio
+import logging
+from datetime import datetime
+
+from rsocket.payload import Payload
+from rsocket.request_handler import BaseRequestHandler
+from rsocket.rsocket_server import RSocketServer
+from rsocket.transports.tcp import TransportTCP
+
+
+class Handler(BaseRequestHandler):
+    async def request_response(self, payload: Payload) -> asyncio.Future:
+        await asyncio.sleep(0.1)  # Simulate not immediate process
+        future = asyncio.Future()
+        date_time_format = payload.data.decode('utf-8')
+        formatted_date_time = datetime.now().strftime(date_time_format)
+        future.set_result(Payload(formatted_date_time.encode('utf-8')))
+        return future
+
+
+async def run_server():
+    def session(*connection):
+        RSocketServer(TransportTCP(*connection), handler_factory=Handler)
+
+    server = await asyncio.start_server(session, 'localhost', 6565)
+
+    async with server:
+        await server.serve_forever()
+
+
+if __name__ == '__main__':
+    logging.basicConfig(level=logging.DEBUG)
+    asyncio.run(run_server())
+```
+
+## More Examples
+
+Browse the following repositories for more `rsocket-py` examples:
+
+- [rsocket-py/examples](https://github.com/rsocket/rsocket-py/tree/master/examples)

content-docs/guides/rsocket-py/rxpy/introduction.mdx

@@ -0,0 +1,11 @@
+---
+slug: /guides/rsocket-py/rxpy
+title: RxPy integration
+sidebar_label: Introduction
+---
+
+## Reactive Streams
+
+The `rsocket-py` implementation doesn't use [RxPy](https://pypi.org/project/Rx/) by default. A wrapper class `RxRSocketClient`
+can be used to interact with [RxPy](https://pypi.org/project/Rx/) (>= 3.2.0) entities (`Observable`, `Observer`)
+