diff --git a/collegamento/__init__.py b/collegamento/__init__.py index a05f1d3..cb44f5a 100644 --- a/collegamento/__init__.py +++ b/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, +) diff --git a/collegamento/files_variant.py b/collegamento/files_variant.py index 336aaf3..1921eed 100644 --- a/collegamento/files_variant.py +++ b/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], diff --git a/collegamento/ipc/__init__.py b/collegamento/simple_client_server/__init__.py similarity index 58% rename from collegamento/ipc/__init__.py rename to collegamento/simple_client_server/__init__.py index 416b173..ca06316 100644 --- a/collegamento/ipc/__init__.py +++ b/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 diff --git a/collegamento/ipc/client.py b/collegamento/simple_client_server/client.py similarity index 98% rename from collegamento/ipc/client.py rename to collegamento/simple_client_server/client.py index 7951b9e..5b97211 100644 --- a/collegamento/ipc/client.py +++ b/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: diff --git a/collegamento/ipc/misc.py b/collegamento/simple_client_server/misc.py similarity index 100% rename from collegamento/ipc/misc.py rename to collegamento/simple_client_server/misc.py diff --git a/collegamento/ipc/server.py b/collegamento/simple_client_server/server.py similarity index 99% rename from collegamento/ipc/server.py rename to collegamento/simple_client_server/server.py index 386c2f7..e4e1acd 100644 --- a/collegamento/ipc/server.py +++ b/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__( diff --git a/docs/source/classes.rst b/docs/source/classes.rst index 9fa76fc..4cf0b43 100644 --- a/docs/source/classes.rst +++ b/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`` diff --git a/docs/source/example-usage.rst b/docs/source/example-usage.rst index 5e07c6a..7864c5c 100644 --- a/docs/source/example-usage.rst +++ b/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() diff --git a/docs/source/examples/class_example.rst b/docs/source/examples/class_example.rst new file mode 100644 index 0000000..c35833f --- /dev/null +++ b/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 `_. \ No newline at end of file diff --git a/docs/source/examples/file_example.rst b/docs/source/examples/file_example.rst new file mode 100644 index 0000000..33c3fee --- /dev/null +++ b/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 `_. \ No newline at end of file diff --git a/docs/source/examples/simple_example.rst b/docs/source/examples/simple_example.rst new file mode 100644 index 0000000..08f6ad9 --- /dev/null +++ b/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 `_. \ No newline at end of file diff --git a/docs/source/functions.rst b/docs/source/functions.rst deleted file mode 100644 index c112dee..0000000 --- a/docs/source/functions.rst +++ /dev/null @@ -1,10 +0,0 @@ -========= -Functions -========= - -.. _Example Function Overview: - -``Example_Function()`` -********************** - -Example_Function() does xyz diff --git a/docs/source/index.rst b/docs/source/index.rst index a385bdc..71d6f2c 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/installation.rst b/docs/source/installation.rst index d53ee05..c81d838 100644 --- a/docs/source/installation.rst +++ b/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! diff --git a/docs/source/variables.rst b/docs/source/variables.rst index 299e57c..eada3c8 100644 --- a/docs/source/variables.rst +++ b/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 diff --git a/examples/class_example.py b/examples/class_example.py new file mode 100644 index 0000000..02d55b9 --- /dev/null +++ b/examples/class_example.py @@ -0,0 +1,41 @@ +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() diff --git a/examples/file_example.py b/examples/file_example.py new file mode 100644 index 0000000..a60e993 --- /dev/null +++ b/examples/file_example.py @@ -0,0 +1,27 @@ +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() diff --git a/examples/simple_example.py b/examples/simple_example.py new file mode 100644 index 0000000..98fd1e8 --- /dev/null +++ b/examples/simple_example.py @@ -0,0 +1,29 @@ +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() diff --git a/setup.py b/setup.py index 013565e..5d852d2 100644 --- a/setup.py +++ b/setup.py @@ -27,5 +27,5 @@ "License :: OSI Approved :: MIT License", "Typing :: Typed", ], - packages=["collegamento", "collegamento.ipc"], + packages=["collegamento", "collegamento.simple_client_server"], )