Add examples and continue docs

collegamento/__init__.py

@@ -9,8 +9,11 @@
     FileServer,
 )
 
-# xyz module level imports go here
-from .ipc import USER_FUNCTION  # noqa: F401, E402
-from .ipc import Client as SimpleClient  # noqa: F401, E402
-from .ipc import Notification, Request, Response  # noqa: F401, E402
-from .ipc import Server as SimpleServer  # noqa: F401, E402
+from .simple_client_server import (  # noqa: F401, E402
+    USER_FUNCTION,
+    Notification,
+    Request,
+    Response,
+    SimpleClient,
+    SimpleServer,
+)

collegamento/files_variant.py

@@ -2,7 +2,13 @@
 from multiprocessing.queues import Queue as GenericQueueClass
 from typing import NotRequired
 
-from .ipc import USER_FUNCTION, Client, Notification, Request, Server
+from .simple_client_server import (
+    USER_FUNCTION,
+    SimpleClient,
+    Notification,
+    Request,
+    SimpleServer,
+)
 
 
 class FileRequest(Request):
@@ -16,7 +22,11 @@ class FileNotification(Notification):
     contents: NotRequired[str]
 
 
-class FileClient(Client):
+class FileClient(SimpleClient):
+    """File handling variant of SImpleClient. Extra methods:
+     - FileClient.update_file()
+     - FileClient.remove_file()
+    """
     def __init__(
         self, commands: dict[str, USER_FUNCTION], id_max: int = 15_000
     ) -> None:
@@ -76,7 +86,8 @@ def remove_file(self, file: str) -> None:
         super().notify_server(notification)
 
 
-class FileServer(Server):
+class FileServer(SimpleServer):
+    """File handling variant of SimpleServer"""
     def __init__(
         self,
         commands: dict[str, USER_FUNCTION],

collegamento/ipc/__init__.py → collegamento/simple_client_server/__init__.py

@@ -1,4 +1,4 @@
-from .client import Client  # noqa: F401, E402
+from .client import SimpleClient  # noqa: F401, E402
 from .misc import (  # noqa: F401, E402
     USER_FUNCTION,
     Notification,
@@ -7,4 +7,4 @@
     Response,
     ResponseQueueType,
 )
-from .server import Server  # noqa: F401, E402
+from .server import SimpleServer  # noqa: F401, E402

collegamento/ipc/client.py → collegamento/simple_client_server/client.py

@@ -10,10 +10,10 @@
     Response,
     ResponseQueueType,
 )
-from .server import Server
+from .server import SimpleServer
 
 
-class Client:
+class SimpleClient:
     """The IPC class is used to talk to the server and run commands. The public API includes the following methods:
     - Client.notify_server()
     - Client.request()
@@ -26,13 +26,13 @@ def __init__(
         self,
         commands: dict[str, USER_FUNCTION],
         id_max: int = 15_000,
-        server_type: type = Server,
+        server_type: type = SimpleServer,
     ) -> None:
         self.all_ids: list[int] = []
         self.id_max = id_max
         self.current_ids: dict[str, int] = {}
         self.newest_responses: dict[str, Response | None] = {}
-        self.server_type: type[Server] = server_type
+        self.server_type: type[SimpleServer] = server_type
 
         self.commands = commands
         for command in self.commands:

collegamento/ipc/server.py → collegamento/simple_client_server/server.py

@@ -13,7 +13,7 @@
 )
 
 
-class Server:
+class SimpleServer:
     """Handles input from the user and returns output from special functions. Not an external API."""
 
     def __init__(

docs/source/classes.rst

@@ -2,11 +2,42 @@
 Classes
 =======
 
-.. _Example Class Overview:
+.. _Notification Overview:
 
-``Example_Class``
-*****************
+``Notification``
+****************
 
-``Exampmle_class`` can do:
+The ``Notification`` class is for xyz.
 
- - xyz
+.. _Request Overview:
+
+``Request``
+***********
+
+The ``Request`` class is for xyz.
+
+.. _Response Overview:
+
+``Response``
+************
+
+The ``Response`` class is for xyz.
+
+.. _SimpleClient Overview:
+
+``SimpleClient``
+****************
+
+The ``SimpleClient`` class can do:
+
+- ``SimpleClient.xyz``
+- ``SimpleClient.yippee``
+
+.. _FileClient Overview:
+
+``FileClient``
+**************
+
+``FileClient`` can do:
+
+- ``xyz``

docs/source/example-usage.rst

@@ -2,8 +2,36 @@
 Example Usage
 =============
 
-Now that you have ``collegamento`` installed, let's try running a simple example that does xyz:
+Now that you have ``Collegamento`` installed, let's try running a simple example that should print out ``"Yippee! It worked!"``:
 
 .. code-block:: python
 
-    xyz
+    from time import sleep
+
+    from collegamento import USER_FUNCTION, Request, Response, SimpleClient
+
+
+    def foo(bar: Request) -> bool:
+        if bar["command"] == "test":
+            return True
+        return False
+
+
+    def main():
+        commands: dict[str, USER_FUNCTION] = {"test": foo}
+        context = SimpleClient(commands)
+
+        context.request({"command": "test"})
+
+        sleep(1)
+
+        output: Response | None = context.get_response("test")
+        if output is not None and output["result"] == True:  # type: ignore
+            print("Yippee! It worked!")
+        else:
+            print("Aww, maybe your compute is just a little slow?")
+
+        context.kill_IPC()
+
+    if __name__ == "__main__":
+        main()

docs/source/examples/class_example.rst

@@ -0,0 +1,49 @@
+=============
+Class Example
+=============
+
+.. code-block:: python
+
+    from time import sleep
+    
+    from collegamento import FileClient, Request
+    
+    
+    class MyClient:
+        def __init__(self):
+            self.context = FileClient({"MyClientFunc": self.split_str})
+    
+            self.context.update_file("user_file", "")
+    
+        def change_file(self, new_contents: str) -> None:
+            self.context.update_file("user_file", new_contents)
+    
+        def request_split(self) -> None:
+            self.context.request({"command": "MyClientFunc", "file": "user_file"})
+    
+        def check_split(self) -> list[str] | None:
+            output = self.context.get_response("MyClientFunc")
+            if output is not None:
+                return output["result"]  # type: ignore
+            return output
+    
+        def split_str(self, arg: Request) -> list[str]:
+            file = arg["file"]  # type: ignore
+            return file.split(" ")
+    
+    
+    def main():
+        mc = MyClient()
+        mc.change_file("Test File")
+        mc.request_split()
+    
+        sleep(1)
+    
+        output = mc.check_split()
+        print(output)
+    
+    
+    if __name__ == "__main__":
+        main()
+
+See the file example file `here <https://github.com/salve-org/albero/blob/master/examples/class_example.py>`_.

docs/source/examples/file_example.rst

@@ -0,0 +1,35 @@
+============
+File Example
+============
+
+.. code-block:: python
+
+    from time import sleep
+    
+    from collegamento import USER_FUNCTION, FileClient, Request, Response
+    
+    
+    def split_str(arg: Request) -> list[str]:
+        file = arg["file"]  # type: ignore
+        return file.split(" ")
+    
+    
+    def main():
+        commands: dict[str, USER_FUNCTION] = {"test": split_str}
+        context = FileClient(commands)
+    
+        context.update_file("test", "test contents")
+        context.request({"command": "test", "file": "test"})
+    
+        sleep(1)
+    
+        output: Response | None = context.get_response("test")
+        print(output)
+    
+        context.kill_IPC()
+    
+    
+    if __name__ == "__main__":
+        main()
+
+See the file example file `here <https://github.com/salve-org/albero/blob/master/examples/file_example.py>`_.

docs/source/examples/simple_example.rst

@@ -0,0 +1,37 @@
+==============
+Simple Example
+==============
+
+.. code-block:: python
+
+    from time import sleep
+    
+    from collegamento import USER_FUNCTION, Request, Response, SimpleClient
+    
+    
+    def foo(bar: Request) -> bool:
+        if bar["command"] == "test":
+            return True
+        return False
+    
+    
+    def main():
+        commands: dict[str, USER_FUNCTION] = {"test": foo}
+        context = SimpleClient(commands)
+    
+        context.request({"command": "test"})
+    
+        sleep(1)
+    
+        output: Response | None = context.get_response("test")
+        if output is not None and output["result"] == True:  # type: ignore
+            print("Yippee! It worked!")
+        else:
+            print("Aww, maybe your compute is just a little slow?")
+    
+        context.kill_IPC()
+    
+    if __name__ == "__main__":
+        main()
+
+See the file example file `here <https://github.com/salve-org/albero/blob/master/examples/simple_example.py>`_.

docs/source/index.rst

@@ -15,6 +15,4 @@ Welcome to ``Collegamento``'s Documentation! ``Collegamento`` is a library that
    installation
    example-usage
    classes
-   variables
-   functions
    examples

docs/source/installation.rst

@@ -8,6 +8,6 @@ To start using ``Collegamento``, first install it using pip:
 
     $ pip install collegamento
 
-And it's installed! Congratulations on xyz!
+And it's installed! Congratulations on freeing up your main thread!
 
 Let's move on to the :doc:`example-usage` page to give ``Collegamento`` a try!

docs/source/variables.rst

@@ -2,9 +2,9 @@
 Variables
 =========
 
-.. _Example Variable Overview:
+.. _USER_FUNCTION Overview:
 
-``Example variable``
-********************
+``USER_FUNCTION``
+*****************
 
-Example variable does xyz
+USER_FUNCTION does xyz