From 3e0fb188e24e582b42a12ba840ee2639d5a1dd87 Mon Sep 17 00:00:00 2001 From: El Mau Date: Thu, 24 Feb 2022 23:59:04 -0600 Subject: [PATCH] Start doc for API --- .gitignore | 1 + .../{01_install_01.png => install_01.png} | Bin docs/source/api.rst | 7 + docs/source/conf.py | 9 +- docs/source/easymacro.rst | 7 + docs/source/generated/easymacro.rst | 52 ++++ docs/source/index.rst | 3 +- docs/source/{01_install.rst => install.rst} | 2 +- docs/source/modules.rst | 7 + source/easymacro.py | 278 ++++++++++++++---- 10 files changed, 300 insertions(+), 66 deletions(-) rename docs/source/_static/images/{01_install_01.png => install_01.png} (100%) create mode 100644 docs/source/api.rst create mode 100644 docs/source/easymacro.rst create mode 100644 docs/source/generated/easymacro.rst rename docs/source/{01_install.rst => install.rst} (94%) create mode 100644 docs/source/modules.rst diff --git a/.gitignore b/.gitignore index 7064943..90f74f1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ __pycache__ *.pyc build/ +*.bk diff --git a/docs/source/_static/images/01_install_01.png b/docs/source/_static/images/install_01.png similarity index 100% rename from docs/source/_static/images/01_install_01.png rename to docs/source/_static/images/install_01.png diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..8ce5113 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,7 @@ +API +=== + +.. autosummary:: + :toctree: generated + + easymacro diff --git a/docs/source/conf.py b/docs/source/conf.py index c8c3b17..40ae94e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,9 +10,9 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('../../source')) # -- Project information ----------------------------------------------------- @@ -20,6 +20,7 @@ project = 'easymacro' copyright = '2022, El Mau' author = 'El Mau' +release = '0.1.0' # -- General configuration --------------------------------------------------- @@ -28,6 +29,8 @@ author = 'El Mau' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/easymacro.rst b/docs/source/easymacro.rst new file mode 100644 index 0000000..9085ce0 --- /dev/null +++ b/docs/source/easymacro.rst @@ -0,0 +1,7 @@ +easymacro module +================ + +.. automodule:: easymacro + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/generated/easymacro.rst b/docs/source/generated/easymacro.rst new file mode 100644 index 0000000..90fbd13 --- /dev/null +++ b/docs/source/generated/easymacro.rst @@ -0,0 +1,52 @@ +easymacro +========= + +.. automodule:: easymacro + + + + + + + + .. rubric:: Functions + + .. autosummary:: + + catch_exception + create_instance + debug + error + errorbox + get_app_config + info + mri + msgbox + now + question + save_log + set_app_config + today + warning + + + + + + .. rubric:: Classes + + .. autosummary:: + + LOServer + MBT + MessageBoxType + commands + + + + + + + + + diff --git a/docs/source/index.rst b/docs/source/index.rst index b8d156d..d9aa8fb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,7 +21,8 @@ You can used **easymacro** with any extension or directly in your macros. :maxdepth: 2 :caption: Contents: - 01_install + install + api Indices and tables diff --git a/docs/source/01_install.rst b/docs/source/install.rst similarity index 94% rename from docs/source/01_install.rst rename to docs/source/install.rst index a96dc13..740c210 100644 --- a/docs/source/01_install.rst +++ b/docs/source/install.rst @@ -38,7 +38,7 @@ copy this code: and execute from LibreOffice, if you see similar next info, great! -.. image:: _static/images/01_install_01.png +.. image:: _static/images/install_01.png | diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..eb51112 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +source +====== + +.. toctree:: + :maxdepth: 4 + + easymacro diff --git a/source/easymacro.py b/source/easymacro.py index 0ab42d8..fe72a2b 100644 --- a/source/easymacro.py +++ b/source/easymacro.py @@ -38,6 +38,7 @@ from com.sun.star.awt import MessageBoxButtons as MSG_BUTTONS from com.sun.star.awt.MessageBoxResults import YES from com.sun.star.beans import PropertyValue + LOG_FORMAT = '%(asctime)s - %(levelname)s - %(message)s' LOG_DATE = '%d/%m/%Y %H:%M:%S' logging.addLevelName(logging.ERROR, '\033[1;41mERROR\033[1;0m') @@ -66,51 +67,55 @@ CTX = uno.getComponentContext() SM = CTX.getServiceManager() -def debug(*args) -> None: - """ - Show messages debug +# UNO Enum +class MessageBoxType(): + from com.sun.star.awt.MessageBoxType \ + import MESSAGEBOX, INFOBOX, WARNINGBOX, ERRORBOX, QUERYBOX +MBT = MessageBoxType - Parameters: - args (list): iterable messages for show + +def debug(*messages) -> None: + """Show messages debug + + :param messages: List of messages to debug + :type messages: list[Any] """ - data = [str(a) for a in args] + data = [str(m) for m in messages] log.debug('\t'.join(data)) return def error(message: Any) -> None: - """ - Show message error + """Show message error - Parameters: - message (Any): message show error + :param message: The message error + :type message: Any """ log.error(message) return -def info(*args) -> None: - """ - Show messages info +def info(*messages) -> None: + """Show messages info - Parameters: - args (list): iterable messages for show + :param messages: List of messages to debug + :type messages: list[Any] """ - data = [str(a) for a in args] + data = [str(m) for m in messages] log.info('\t'.join(data)) return def save_log(path: str, data: Any) -> None: - """ - Save data in file, data append to end + """Save data in file, data append to end and automatic add current time. - Parameters: - path (str): path to save - data (Any): any info data + :param path: Path to save log + :type path: str + :param data: Data to save in file log + :type data: Any """ with open(path, 'a') as f: @@ -119,32 +124,111 @@ def save_log(path: str, data: Any) -> None: return -def create_instance(name: str, with_context: bool=False, args: Any=None) -> Any: +def create_instance(name: str, with_context: bool=False, argument: Any=None) -> Any: + """Create a service instance + + :param name: Name of service + :type name: str + :param with_context: If used context + :type with_context: bool + :param argument: If needed some argument + :type argument: Any + :return: PyUno instance + :rtype: PyUno Object + """ + if with_context: instance = SM.createInstanceWithContext(name, CTX) - elif args: - instance = SM.createInstanceWithArguments(name, (args,)) + elif argument: + instance = SM.createInstanceWithArguments(name, (argument,)) else: instance = SM.createInstance(name) + return instance -def get_app_config(node_name: str, key: str='', update: bool=False): +def get_app_config(node_name: str, key: str='') -> Any: + """Get any key from any node from LibreOffice configuration. + + :param node_name: Name of node + :type name: str + :param key: Name of key + :type key: str + :return: Any value + :rtype: Any + + `See Api ConfigurationProvider `_ + """ + name = 'com.sun.star.configuration.ConfigurationProvider' service = 'com.sun.star.configuration.ConfigurationAccess' - if update: - service = 'com.sun.star.configuration.ConfigurationUpdateAccess' cp = create_instance(name, True) node = PropertyValue(Name='nodepath', Value=node_name) + value = '' + try: - ca = cp.createInstanceWithArguments(service, (node,)) - if ca and not key: - return ca - if ca and ca.hasByName(key): - return ca.getPropertyValue(key) + value = cp.createInstanceWithArguments(service, (node,)) + if value and value.hasByName(key): + value = value.getPropertyValue(key) except Exception as e: error(e) - return '' + value = '' + + return value + + +def set_app_config(node_name: str, key: str, new_value: Any) -> Any: + result = True + current_value = '' + name = 'com.sun.star.configuration.ConfigurationProvider' + service = 'com.sun.star.configuration.ConfigurationUpdateAccess' + cp = create_instance(name, True) + node = PropertyValue(Name='nodepath', Value=node_name) + update = cp.createInstanceWithArguments(service, (node,)) + + try: + current_value = update.getPropertyValue(key) + update.setPropertyValue(key, new_value) + update.commitChanges() + except Exception as e: + error(e) + if update.hasByName(key) and current_value: + update.setPropertyValue(key, current_value) + update.commitChanges() + result = False + + return result + + +def _set_app_command(command: str, disable: bool): + NEW_NODE_NAME = f'zaz_disable_command_{command.lower()}' + name = 'com.sun.star.configuration.ConfigurationProvider' + service = 'com.sun.star.configuration.ConfigurationUpdateAccess' + node_name = '/org.openoffice.Office.Commands/Execute/Disabled' + + cp = create_instance(name, True) + node = PropertyValue(Name='nodepath', Value=node_name) + update = cp.createInstanceWithArguments(service, (node,)) + + if disable: + new_node = update.createInstanceWithArguments(()) + new_node.setPropertyValue('Command', command) + update.insertByName(NEW_NODE_NAME, new_node) + else: + update.removeByName(NEW_NODE_NAME) + update.commitChanges() + + return + + +class commands(): + # ~ https://wiki.documentfoundation.org/Development/DispatchCommands + def __init__(self, command): + self._command = command + def disable(self): + return _set_app_command(self._command, True) + def enabled(self): + return _set_app_command(self._command, False) # Get info LibO @@ -162,35 +246,16 @@ day = get_app_config(node, 'DD') DATE_OFFSET = datetime.date(year, month, day).toordinal() -def msgbox(message: Any, title: str=TITLE, buttons=MSG_BUTTONS.BUTTONS_OK, type_msg: str='infobox') -> Any: - """ Create message box - type_msg: infobox, warningbox, errorbox, querybox, messbox - http://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XMessageBoxFactory.html - """ - toolkit = create_instance('com.sun.star.awt.Toolkit') - parent = toolkit.getDesktopWindow() - box = toolkit.createMessageBox(parent, type_msg, buttons, title, str(message)) - return box.execute() - - -def question(message: Any, title: str=TITLE) -> Any: - result = msgbox(message, title, MSG_BUTTONS.BUTTONS_YES_NO, 'querybox') - return result == YES - - -def warning(message: Any, title: str=TITLE) -> Any: - return msgbox(message, title, type_msg='warningbox') - - -def errorbox(message: Any, title: str=TITLE) -> Any: - return msgbox(message, title, type_msg='errorbox') - - def mri(obj: Any) -> None: + """Inspect object with MRI Extension + + :param obj: Any pyUno object + :type obj: Any + + `See MRI `_ """ - Inspect object with MRI Extension - """ - m = create_instance('mytools.Mri') + + mri = create_instance('mytools.Mri') if m is None: msg = 'Extension MRI not found' error(msg) @@ -198,11 +263,17 @@ def mri(obj: Any) -> None: if hasattr(obj, 'obj'): obj = obj.obj - m.inspect(obj) + mri.inspect(obj) return def catch_exception(f): + """Catch exception for any function + + :param f: Any Python function + :type f: Function instance + """ + @wraps(f) def func(*args, **kwargs): try: @@ -215,6 +286,91 @@ def catch_exception(f): return func +def msgbox(message: Any, title: str=TITLE, buttons=MSG_BUTTONS.BUTTONS_OK, \ + type_message_box=MessageBoxType.INFOBOX) -> Any: + """Create message box + + :param message: Any type message, all is converted to string. + :type message: Any + :param title: The title for message box + :type title: str + :param buttons: A combination of `com::sun::star::awt::MessageBoxButtons `_ + :type buttons: long + :param type_message_box: The `message box type `_ + :type type_message_box: enum + :return: Instance MessageBox + :rtype: pyUno + + `See Api XMessageBoxFactory `_ + """ + + toolkit = create_instance('com.sun.star.awt.Toolkit') + parent = toolkit.getDesktopWindow() + box = toolkit.createMessageBox(parent, type_message_box, buttons, title, str(message)) + return box.execute() + + +def question(message: str, title: str=TITLE) -> Any: + """Create message box question, show buttons YES and NO + + :param message: Message question + :type message: str + :param title: The title for message box + :type title: str + :return: True if user click YES and False if click NO + :rtype: bool + """ + + result = msgbox(message, title, MSG_BUTTONS.BUTTONS_YES_NO, MessageBoxType.QUERYBOX) + return result == YES + + +def warning(message: Any, title: str=TITLE) -> Any: + """Create message box with icon warning + + :param message: Any type message, all is converted to string. + :type message: Any + :param title: The title for message box + :type title: str + :return: Instance MessageBox + :rtype: pyUno + """ + + return msgbox(message, title, type_message_box=MessageBoxType.WARNINGBOX) + + +def errorbox(message: Any, title: str=TITLE) -> Any: + """Create message box with icon error + + :param message: Any type message, all is converted to string. + :type message: Any + :param title: The title for message box + :type title: str + :return: Instance MessageBox + :rtype: pyUno + """ + + return msgbox(message, title, type_message_box=MessageBoxType.ERRORBOX) + + +def now(): + """Current local date and time + + :return: Return the current local date and time + :rtype: datetime + """ + return datetime.datetime.now() + + +def today(): + """Current local date + + :return: Return the current local date + :rtype: date + """ + return datetime.date.today() + + class LOServer(object): HOST = 'localhost' PORT = '8100'