Add API Doc

Author: JE-Chen

docs/source/API/api_index.rst

@@ -0,0 +1,19 @@
+====================================
+AutoControl API Documentation
+====================================
+
+.. toctree::
+   :maxdepth: 4
+
+   wrapper/image.rst
+   wrapper/keyboard.rst
+   wrapper/mouse.rst
+   wrapper/record.rst
+   wrapper/screen.rst
+   utils/callback.rst
+   utils/critical_exit.rst
+   utils/executor.rst
+   utils/file.rst
+   utils/generate_report.rst
+   utils/package_manager.rst
+   utils/socket_server.rst

docs/source/API/utils/callback.rst

@@ -0,0 +1,21 @@
+Callback Function API
+----
+
+.. code-block:: python
+
+    def callback_function(
+            self,
+            trigger_function_name: str,
+            callback_function: typing.Callable,
+            callback_function_param: [dict, None] = None,
+            callback_param_method: str = "kwargs",
+            **kwargs
+    ):
+        """
+        :param trigger_function_name: what function we want to trigger only accept function in event_dict
+        :param callback_function: what function we want to callback
+        :param callback_function_param: callback function's param only accept dict
+        :param callback_param_method: what type param will use on callback function only accept kwargs and args
+        :param kwargs: trigger_function's param
+        :return: trigger_function_name return value
+        """

docs/source/API/utils/critical_exit.rst

@@ -0,0 +1,47 @@
+Critical Exit API
+----
+
+.. code-block:: python
+
+    class CriticalExit(Thread):
+        """
+        use to make program interrupt
+        """
+
+        def __init__(self, default_daemon: bool = True):
+            """
+            default interrupt is keyboard F7 key
+            :param default_daemon bool thread setDaemon
+            """
+            super().__init__()
+            self.daemon = default_daemon
+            self._exit_check_key: int = keyboard_keys_table.get("f7")
+
+        def set_critical_key(self, keycode: [int, str] = None) -> None:
+            """
+            set interrupt key
+            :param keycode interrupt key
+            """
+            if isinstance(keycode, int):
+                self._exit_check_key = keycode
+            else:
+                self._exit_check_key = keyboard_keys_table.get(keycode)
+
+        def run(self) -> None:
+            """
+            listener keycode _exit_check_key to interrupt
+            """
+            try:
+                while True:
+                    if keyboard_check.check_key_is_press(self._exit_check_key):
+                        _thread.interrupt_main()
+            except Exception as error:
+                print(repr(error), file=sys.stderr)
+
+        def init_critical_exit(self) -> None:
+            """
+            should only use this to start critical exit
+            may this function will add more
+            """
+            critical_thread = self
+            critical_thread.start()

docs/source/API/utils/executor.rst

@@ -0,0 +1,26 @@
+Executor API
+----
+
+.. code-block:: python
+
+    def execute_action(self, action_list: [list, dict]) -> dict:
+        """
+        use to execute all action on action list(action file or program list)
+        :param action_list the list include action
+        for loop the list and execute action
+        """
+
+.. code-block:: python
+
+    def execute_files(self, execute_files_list: list) -> list:
+        """
+        :param execute_files_list: list include execute files path
+        :return: every execute detail as list
+        """
+
+.. code-block:: python
+
+    def add_command_to_executor(command_dict: dict):
+        """
+        :param command_dict: dict include command we want to add to event_dict
+        """

docs/source/API/utils/file.rst

@@ -0,0 +1,14 @@
+File process API
+----
+
+.. code-block:: python
+
+    def get_dir_files_as_list(
+            dir_path: str = getcwd(),
+            default_search_file_extension: str = ".json") -> List[str]:
+        """
+        get dir file when end with default_search_file_extension
+        :param dir_path: which dir we want to walk and get file list
+        :param default_search_file_extension: which extension we want to search
+        :return: [] if nothing searched or [file1, file2.... files] file was searched
+        """

docs/source/API/utils/generate_report.rst

@@ -0,0 +1,47 @@
+Generate Report API
+----
+
+.. code-block:: python
+
+    def generate_html() -> str:
+        """
+        this function will create html string
+        :return: html_string
+        """
+
+.. code-block:: python
+
+    def generate_html_report(html_name: str = "default_name"):
+        """
+        Output html report file
+        :param html_name: save html file name
+        """
+
+.. code-block:: python
+
+    def generate_json():
+        """
+        :return: two dict {success_dict}, {failure_dict}
+        """
+
+.. code-block:: python
+
+    def generate_json_report(json_file_name: str = "default_name"):
+        """
+        Output json report file
+        :param json_file_name: save json file's name
+        """
+
+.. code-block:: python
+
+    def generate_xml():
+        """
+        :return: two dict {success_dict}, {failure_dict}
+        """
+
+.. code-block:: python
+
+    def generate_xml_report(xml_file_name: str = "default_name"):
+        """
+        :param xml_file_name: save xml file name
+        """

docs/source/API/utils/package_manager.rst

@@ -0,0 +1,101 @@
+Package Manager API
+----
+
+.. code-block:: python
+
+    from importlib import import_module
+    from importlib.util import find_spec
+    from inspect import getmembers, isfunction, isbuiltin, isclass
+    from sys import stderr
+
+
+    class PackageManager(object):
+
+        def __init__(self):
+            self.installed_package_dict = {
+            }
+            self.executor = None
+            self.callback_executor = None
+
+        def check_package(self, package: str):
+            """
+            :param package: package to check exists or not
+            :return: package if find else None
+            """
+            if self.installed_package_dict.get(package, None) is None:
+                found_spec = find_spec(package)
+                if found_spec is not None:
+                    try:
+                        installed_package = import_module(found_spec.name)
+                        self.installed_package_dict.update(
+                            {found_spec.name: installed_package})
+                    except ModuleNotFoundError as error:
+                        print(repr(error), file=stderr)
+            return self.installed_package_dict.get(package, None)
+
+        def add_package_to_executor(self, package):
+            """
+            :param package: package's function will add to executor
+            """
+            self.add_package_to_target(
+                package=package,
+                target=self.executor
+            )
+
+        def add_package_to_callback_executor(self, package):
+            """
+            :param package: package's function will add to callback_executor
+            """
+            self.add_package_to_target(
+                package=package,
+                target=self.callback_executor
+            )
+
+        def get_member(self, package, predicate, target):
+            """
+            :param package: package we want to get member
+            :param predicate: predicate
+            :param target: which event_dict will be added
+            """
+            installed_package = self.check_package(package)
+            if installed_package is not None and target is not None:
+                for member in getmembers(installed_package, predicate):
+                    target.event_dict.update(
+                        {str(package) + "_" + str(member[0]): member[1]})
+            elif installed_package is None:
+                print(repr(ModuleNotFoundError(f"Can't find package {package}")),
+                      file=stderr)
+            else:
+                print(f"Executor error {self.executor}", file=stderr)
+
+        def add_package_to_target(self, package, target):
+            """
+            :param package: package we want to get member
+            :param target: which event_dict will be added
+            """
+            try:
+                self.get_member(
+                    package=package,
+                    predicate=isfunction,
+                    target=target
+                )
+                self.get_member(
+                    package=package,
+                    predicate=isbuiltin,
+                    target=target
+                )
+                self.get_member(
+                    package=package,
+                    predicate=isfunction,
+                    target=target
+                )
+                self.get_member(
+                    package=package,
+                    predicate=isclass,
+                    target=target
+                )
+            except Exception as error:
+                print(repr(error), file=stderr)
+
+
+    package_manager = PackageManager()

docs/source/API/utils/socket_server.rst

@@ -0,0 +1,60 @@
+Socket Server API
+----
+
+.. code-block:: python
+
+    import json
+    import socketserver
+    import sys
+    import threading
+
+    from je_auto_control.utils.executor.action_executor import execute_action
+
+
+    class TCPServerHandler(socketserver.BaseRequestHandler):
+
+        def handle(self):
+            command_string = str(self.request.recv(8192).strip(), encoding="utf-8")
+            socket = self.request
+            print("command is: " + command_string, flush=True)
+            if command_string == "quit_server":
+                self.server.shutdown()
+                self.server.close_flag = True
+                print("Now quit server", flush=True)
+            else:
+                try:
+                    execute_str = json.loads(command_string)
+                    for execute_function, execute_return in execute_action(execute_str).items():
+                        socket.sendto(str(execute_return).encode("utf-8"), self.client_address)
+                        socket.sendto("\n".encode("utf-8"), self.client_address)
+                    socket.sendto("Return_Data_Over_JE".encode("utf-8"), self.client_address)
+                    socket.sendto("\n".encode("utf-8"), self.client_address)
+                except Exception as error:
+                    print(repr(error), file=sys.stderr)
+                    try:
+                        socket.sendto(str(error).encode("utf-8"), self.client_address)
+                        socket.sendto("\n".encode("utf-8"), self.client_address)
+                        socket.sendto("Return_Data_Over_JE".encode("utf-8"), self.client_address)
+                        socket.sendto("\n".encode("utf-8"), self.client_address)
+                    except Exception as error:
+                        print(repr(error))
+
+
+    class TCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+
+        def __init__(self, server_address, RequestHandlerClass):
+            super().__init__(server_address, RequestHandlerClass)
+            self.close_flag: bool = False
+
+
+    def start_autocontrol_socket_server(host: str = "localhost", port: int = 9938):
+        if len(sys.argv) == 2:
+            host = sys.argv[1]
+        elif len(sys.argv) == 3:
+            host = sys.argv[1]
+            port = int(sys.argv[2])
+        server = TCPServer((host, port), TCPServerHandler)
+        server_thread = threading.Thread(target=server.serve_forever)
+        server_thread.daemon = True
+        server_thread.start()
+        return server

docs/source/API/wrapper/image.rst

@@ -0,0 +1,47 @@
+Image API
+----
+
+.. code-block:: python
+
+    def locate_all_image(image, detect_threshold: [float, int] = 1,
+                         draw_image: bool = False) -> List[int]:
+        """
+         use to locate all image that detected and then return detected images list
+        :param image which image we want to find on screen (png or PIL ImageGrab.grab())
+        :param detect_threshold detect precision 0.0 ~ 1.0; 1 is absolute equal (float or int)
+        :param draw_image draw detect tag on return image (bool)
+        """
+
+
+.. code-block:: python
+
+    def locate_image_center(image, detect_threshold: [float, int] = 1, draw_image: bool = False) -> List[Union[int, int]]:
+        """
+        use to locate image and return image center position
+        :param image which image we want to find on screen (png or PIL ImageGrab.grab())
+        :param detect_threshold detect precision 0.0 ~ 1.0; 1 is absolute equal (float or int)
+        :param draw_image draw detect tag on return image (bool)
+        """
+
+.. code-block:: python
+
+    def locate_and_click(
+        image, mouse_keycode: [int, str],
+        detect_threshold: [float, int] = 1,
+        draw_image: bool = False) -> List[Union[int, int]]:
+        """
+        use to locate image and click image center position and the return image center position
+        :param image which image we want to find on screen (png or PIL ImageGrab.grab())
+        :param mouse_keycode which mouse keycode we want to click
+        :param detect_threshold detect precision 0.0 ~ 1.0; 1 is absolute equal (float or int)
+        :param draw_image draw detect tag on return image (bool)
+        """
+
+.. code-block:: python
+
+    def screenshot(file_path: str = None, region: list = None) -> List[Union[int, int]]:
+        """
+        use to get now screen image return image
+        :param file_path save screenshot path (None is no save)
+        :param region screenshot screen_region (screenshot screen_region on screen)
+        """