From d6594928d95f22d52364f85c56a851f448047b22 Mon Sep 17 00:00:00 2001
From: cschen <cschen@codemp.dev>
Date: Sat, 17 Aug 2024 23:47:28 +0200
Subject: [PATCH] chore: updated type hints with some sliver of documentation

---
 dist/py/codemp.pyi | 53 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 39 insertions(+), 14 deletions(-)

diff --git a/dist/py/codemp.pyi b/dist/py/codemp.pyi
index cd3da2d..e36cf6d 100644
--- a/dist/py/codemp.pyi
+++ b/dist/py/codemp.pyi
@@ -1,48 +1,69 @@
-from typing import Tuple
+from typing import Tuple, Optional
 
 class PyLogger:
+	"""
+	A python wrapper for the tracing subscriber so that we can
+	receive logging messages from the library.
+	"""
 	def __init__(self, debug) -> None: ...
-	async def listen(self) -> str | None: ...
+	async def listen(self) -> Optional[str]: ...
 
 
 class TextChange:
+	"""
+	Editor agnostic representation of a text change, it translate between internal
+	codemp text operations and editor operations
+	"""
 	start: int
 	end: int
 	content: str
 
-	def is_deletion(self) -> bool: ...
-	def is_addition(self) -> bool: ...
+	def is_delete(self) -> bool: ...
+	def is_insert(self) -> bool: ...
 	def is_empty(self) -> bool: ...
 	def apply(self, txt: str) -> str: ...
-	def from_diff(self, before: str, after: str) -> TextChange: ...
-	def index_to_rowcol(self, txt: str, index: int) -> Tuple[int, int]: ...
 
 
 class BufferController:
-	def content(self) -> str: ...
-	def send(self, start: int, end: int, txt: str) -> None: ...
-	async def try_recv(self) -> TextChange | None: ...
+	"""
+	Handle to the controller for a specific buffer, which manages the back and forth
+	of operations to and from other peers.
+	"""
+	async def content(self) -> str: ...
+	async def send(self, start: int, end: int, txt: str) -> None: ...
+	async def try_recv(self) -> Optional[TextChange]: ...
 	async def recv(self) -> TextChange: ...
 	async def poll(self) -> None: ...
 
 
 
 class Cursor:
+	"""
+	An Editor agnostic cursor position representation
+	"""
 	start: Tuple[int, int]
 	end: Tuple[int, int]
 	buffer: str
-	user: str # can be an empty string
+	user: Optional[str] # can be an empty string
 
 
 class CursorController:
-	def send(self, path: str, start: Tuple[int, int], end: Tuple[int, int]) -> None: ...
-	def try_recv(self) -> Cursor | None: ...
+	"""
+	Handle to the controller for a workspace, which manages the back and forth of
+	cursor movements to and from other peers
+	"""
+	async def send(self, path: str, start: Tuple[int, int], end: Tuple[int, int]) -> None: ...
+	async def try_recv(self) -> Optional[Cursor]: ...
 	async def recv(self) -> Cursor: ...
 	async def poll(self) -> None: ...
 	def stop(self) -> bool: ...
 
 
 class Workspace:
+	"""
+	Handle to a workspace inside codemp. It manages buffers.
+	A cursor is tied to the single workspace.
+	"""
 	async def create(self, path: str) -> None: ...
 	async def attach(self, path: str) -> BufferController: ...
 	def detach(self, path: str) -> bool: ...
@@ -52,13 +73,17 @@ class Workspace:
 	async def delete(self, path: str) -> None: ...
 	def id(self) -> str: ...
 	def cursor(self) -> CursorController: ...
-	def buffer_by_name(self, path: str) -> BufferController | None: ...
+	def buffer_by_name(self, path: str) -> Optional[BufferController]: ...
 	def buffer_list(self) -> list[str]: ...
 	def filetree(self) -> list[str]: ...
 
 
 class Client:
-	def __init__(self, host: str, username: str, password: str) -> None: ...
+	"""
+	Handle to the actual client that manages the session. It manages the connection
+	to a server and joining/creating new workspaces
+	"""
+	def __new__(cls, host: str, username: str, password: str) -> None: ...
 	async def join_workspace(self, workspace: str) -> Workspace: ...
 	def leave_workspace(self, workspace: str) -> bool: ...
 	def get_workspace(self, id: str) -> Workspace: ...