Set up repo (v0.1.0) (#1)

* First commit

Still need to:
- finsh docs
- add examples
- refactor and prettify
- Update readme to remove bottom text

* Add examples and continue docs

* Formatting

* Ruff check fix

* Fix bugs and improve tests marginally

* Custom error class and continue docs

* Fix TODO's

* Finish up docs

.github/workflows/pypi.yml

@@ -1,4 +1,4 @@
-name: Upload PROJECT_NAME to Pypi
+name: Upload collegamento to Pypi
 
 on:
   release:

.gitignore

@@ -7,7 +7,7 @@ dist/
 build/
 .ruff_cache/
 .pytest_cache/
-PROJECT_NAME.egg-info/
+collegamento.egg-info/
 
 # Pycharm
 .idea

README.md

@@ -1,14 +1,14 @@
-<h1 align="center">PROJECT_NAME v0.1.0</h1>
+<h1 align="center">collegamento v0.1.0</h1>
 
-A tool that makes it much easier to do xyz.
+A tool that makes it much easier to make offload work when asyncio isn't an option.
 
 # Installation
 
-In the Command Line, paste the following: `pip install PROJECT_NAME`
+In the Command Line, paste the following: `pip install collegamento`
 
 ## Description
 
-PROJECT_NAME is a library that can be used for xyz. Docs are listed on this [ReadTheDocs page](https://PROJECT_NAME.readthedocs.io/en/master/)
+Collegamento is a library that can be used for Client/Server IPC's with the goal of offloading major workloads to a second process. Docs are listed on this [ReadTheDocs page](https://collegamento.readthedocs.io/en/master/)
 
 ## Contributing
 
@@ -22,5 +22,3 @@ Currently 3.11 is the minimum (instead of 3.10) as this was developed under 3.12
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](./LICENSE).
-
-Keywords to `git grep` for when using template are `xyz` and `PROJECT_NAME`

collegamento/__init__.py

@@ -0,0 +1,14 @@
+from beartype.claw import beartype_this_package
+
+beartype_this_package()
+
+from .files_variant import FileClient, FileServer  # noqa: F401, E402
+from .simple_client_server import (  # noqa: F401, E402
+    USER_FUNCTION,
+    CollegamentoError,
+    Notification,
+    Request,
+    Response,
+    SimpleClient,
+    SimpleServer,
+)

collegamento/files_variant.py

@@ -0,0 +1,130 @@
+from logging import Logger
+from multiprocessing.queues import Queue as GenericQueueClass
+from typing import NotRequired
+
+from .simple_client_server import (
+    USER_FUNCTION,
+    CollegamentoError,
+    Notification,
+    Request,
+    SimpleClient,
+    SimpleServer,
+)
+
+
+class FileRequest(Request):
+    # There may be commands that don't require a file but some might
+    file: NotRequired[str]
+
+
+class FileNotification(Notification):
+    file: str
+    remove: bool
+    contents: NotRequired[str]
+
+
+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:
+        self.files: dict[str, str] = {}
+
+        super().__init__(commands, id_max, FileServer)
+
+    def create_server(self) -> None:
+        """Creates the main_server through a subprocess - internal API"""
+
+        super().create_server()
+
+        self.logger.info("Copying files to server")
+        files_copy = self.files.copy()
+        self.files = {}
+        for file, data in files_copy.items():
+            self.update_file(file, data)
+        self.logger.debug("Finished copying files to server")
+
+    def update_file(self, file: str, current_state: str) -> None:
+        """Updates files in the system - external API"""
+
+        self.logger.info(f"Updating file: {file}")
+        self.files[file] = current_state
+
+        self.logger.debug("Creating notification dict")
+        notification: dict = {
+            "file": file,
+            "remove": False,
+            "contents": self.files[file],
+        }
+
+        self.logger.debug("Notifying server of file update")
+        super().notify_server(notification)
+
+    def remove_file(self, file: str) -> None:
+        """Removes a file from the main_server - external API"""
+        if file not in list(self.files.keys()):
+            self.logger.exception(
+                f"Cannot remove file {file} as file is not in file database!"
+            )
+            raise CollegamentoError(
+                f"Cannot remove file {file} as file is not in file database!"
+            )
+
+        self.logger.info("Notifying server of file deletion")
+        notification: dict = {
+            "file": file,
+            "remove": True,
+        }
+        self.logger.debug("Notifying server of file removal")
+        super().notify_server(notification)
+
+
+class FileServer(SimpleServer):
+    """File handling variant of SimpleServer"""
+
+    def __init__(
+        self,
+        commands: dict[str, USER_FUNCTION],
+        response_queue: GenericQueueClass,
+        requests_queue: GenericQueueClass,
+        logger: Logger,
+    ) -> None:
+        self.files: dict[str, str] = {}
+
+        super().__init__(commands, response_queue, requests_queue, logger)
+
+    def parse_line(self, message: Request | Notification) -> None:
+        self.logger.debug("Parsing Message from user - pre-super")
+        id: int = message["id"]
+
+        if message["type"] == "notification":
+            self.logger.debug("Mesage is of type notification")
+
+            file: str = message["file"]  # type: ignore
+
+            if message["remove"]:  # type: ignore
+                self.logger.info(f"File {file} was requested for removal")
+                self.files.pop(file)
+                self.logger.info(f"File {file} has been removed")
+            else:
+                contents: str = message["contents"]  # type: ignore
+                self.files[file] = contents
+                self.logger.info(
+                    f"File {file} has been updated with new contents"
+                )
+
+            self.simple_id_response(id, False)
+            return
+
+        super().parse_line(message)
+
+    def handle_request(self, request: Request) -> None:
+        if "file" in request:
+            file = request["file"]
+            request["file"] = self.files[file]
+
+        super().handle_request(request)

collegamento/simple_client_server/__init__.py

@@ -0,0 +1,11 @@
+from .client import SimpleClient  # noqa: F401, E402
+from .misc import (  # noqa: F401, E402
+    USER_FUNCTION,
+    CollegamentoError,
+    Notification,
+    Request,
+    RequestQueueType,
+    Response,
+    ResponseQueueType,
+)
+from .server import SimpleServer  # noqa: F401, E402