From 327dd76291ce506d79e637c7ed43494643236a9e Mon Sep 17 00:00:00 2001
From: Mauricio Baeza <elmau@correolibre.net>
Date: Thu, 24 Jun 2021 21:50:25 -0500
Subject: [PATCH] Add examples for paths

---
 doc/source/main/paths.rst | 244 +++++++++++++++++++++++++++++++++++++-
 source/easymacro.py       |  20 +++-
 2 files changed, 252 insertions(+), 12 deletions(-)

diff --git a/doc/source/main/paths.rst b/doc/source/main/paths.rst
index f47dc55..321d8d1 100644
--- a/doc/source/main/paths.rst
+++ b/doc/source/main/paths.rst
@@ -117,15 +117,15 @@ Get path executable python
     app.msgbox(path_python)
 
 
-Save text data
-^^^^^^^^^^^^^^
+Save and read text data
+^^^^^^^^^^^^^^^^^^^^^^^
 
 * Default encoding is UTF8
 
 .. code-block:: python
 
-    data = """“Do you want to know who you are? Don't ask. Act!
-    Action will delineate and define you.”
+    data = """Do you want to know who you are? Don't ask. Act!
+    Action will delineate and define you.
 
     Thomas Jefferson
     """
@@ -133,6 +133,9 @@ Save text data
     path = '/home/mau/temp.txt'
     app.paths.save(path, data)
 
+    data = app.paths.read(path)
+    app.msgbox(data)
+
 * Change encoding
 
 .. code-block:: python
@@ -140,8 +143,8 @@ Save text data
     app.paths.save(path, data, 'iso-8859-1')
 
 
-Save binary data
-^^^^^^^^^^^^^^^^
+Save and read binary data
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: python
 
@@ -149,6 +152,9 @@ Save binary data
     path = '/home/mau/temp.bin'
     app.paths.save_bin(path, data)
 
+    data = app.paths.read_bin(path)
+    app.msgbox(data)
+
 
 Join paths
 ^^^^^^^^^^
@@ -214,4 +220,230 @@ Get a temporal dir
     app.debug(app.paths.exists(dt))
 
 
+Get path for save
+^^^^^^^^^^^^^^^^^
+
+* Default open in user documents.
+
+.. code-block:: python
+
+    path = app.paths.get()
+    app.msgbox(path)
+
+* Open in other path.
+
+.. code-block:: python
+
+    path_tmp = app.paths.temp_dir
+    path = app.paths.get(path_tmp)
+    app.msgbox(path)
+
+* Add one filter
+
+.. code-block:: python
+
+    path = app.paths.get(filters='xml')
+    app.msgbox(path)
+
+* Add multiple filters
+
+.. code-block:: python
+
+    path = app.paths.get(filters='xml,txt')
+
+
+Select directory
+^^^^^^^^^^^^^^^^
+
+* Default open in user documents.
+
+.. code-block:: python
+
+    path_dir = app.paths.get_dir()
+    app.msgbox(path_dir)
+
+* Open in other path.
+
+.. code-block:: python
+
+    path_tmp = app.paths.temp_dir
+    path_dir = app.paths.get_dir(path_tmp)
+    app.msgbox(path_dir)
+
+
+Get path exists file
+^^^^^^^^^^^^^^^^^^^^
+
+* Default open in user documents.
+
+.. code-block:: python
+
+    path_file = app.paths.get_file()
+    app.msgbox(path_file)
+
+* Change init dir.
+
+.. code-block:: python
+
+    path = '/home/mau'
+    path_file = app.paths.get_file(path)
+    app.msgbox(path_file)
+
+* Add filter or filters.
+
+.. code-block:: python
+
+    path_file = app.paths.get_file(filters='ods')
+
+    # or
+
+    path_file = app.paths.get_file(filters='ods,odt')
+
+* Can select multiple files.
+
+.. code-block:: python
+
+    path_file = app.paths.get_file(multiple=True)
+
+
+Replace extension
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    path = '/home/mau/myFile.ods'
+    path_new = app.paths.replace_ext(path, 'pdf')
+    app.msgbox(path_new)
+
+
+Path in format URL <-> System
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    path = '/home/mau/myFile.ods'
+    path_url = app.paths.to_url(path)
+    app.msgbox(path_url)
+
+    path = app.paths.to_system(path_url)
+    app.msgbox(path)
+
+
+Delete files and directories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**CAUTION**: Delete files and directories immediately, always confirm this action.
+
+.. code-block:: python
+
+    path = '/home/mau/temp.bin'
+    result = app.paths.kill(path)
+    app.msgbox(result)
+
+* Delete directory and all content.
+
+.. code-block:: python
+
+    path = '/home/mau/safe_for_delete'
+    result = app.paths.kill(path)
+    app.msgbox(result)
+
+
+Get files
+^^^^^^^^^
+
+This method use library `pathlib`
+
+* Get files not recursively
+
+.. code-block:: python
+
+    path = '/home/mau/Documents'
+    files = app.paths.files(path)
+    for f in files:
+        app.debug(f)
+
+* Add filter
+
+.. code-block:: python
+
+    files = app.paths.files(path, '*.pdf')
+
+* Get from this directory and all subdirectories, recursively
+
+.. code-block:: python
+
+    files = app.paths.files(path, '**/*.pdf')
+
+This method use `os.walk`
+
+* Get content files recursively
+
+.. code-block:: python
+
+    path = '/home/mau/Documents'
+    files = app.paths.walk(path)
+    for f in files:
+        app.debug(f)
+
+* Add filters
+
+.. code-block:: python
+
+    files = app.paths.walk(path, 'ods')
+
+    # or filters
+
+    files = app.paths.walk(path, 'ods|odt')
+
+
+Get directories
+^^^^^^^^^^^^^^^
+
+This method use library `pathlib`
+
+* Get directories in path not recursively
+
+.. code-block:: python
+
+    path = '/home/mau/Documents'
+    folders = app.paths.dirs(path)
+    for f in folders:
+        app.debug(f)
+
+This method use `os.walk`
+
+* Get directories in path recursively
+
+.. code-block:: python
+
+    path = '/home/mau/Documents'
+    folders = app.paths.walk_dirs(path)
+    for f in folders:
+        app.debug(f)
+
+* Get info in a tuple (ID_FOLDER, ID_PARENT, NAME)
+
+.. code-block:: python
+
+    path = '/home/mau/Documents'
+    folders = app.paths.walk_dirs(path, True)
+    for f in folders:
+        app.debug(f)
+
+
+Get install path extension from id
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    id_ext = 'net.elmau.zaz.EasyMacro'
+    path = app.paths.from_id(id_ext)
+    app.debug(path)
+
+.. code-block:: bash
+
+    24/06/2021 21:47:29 - DEBUG - /home/mau/.config/libreoffice/4/user/uno_packages/cache/uno_packages/lu20665x29msz.tmp_/ZAZEasyMacro_v0.1.0.oxt
+
+
 .. _API XPathSettings: http://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1util_1_1XPathSettings.html
diff --git a/source/easymacro.py b/source/easymacro.py
index 8c45d1b..abfc979 100644
--- a/source/easymacro.py
+++ b/source/easymacro.py
@@ -6289,15 +6289,17 @@ class Paths(object):
     @classmethod
     def config(cls, name='Work'):
         """
-            Return de path name in config
+            Return path from config
             http://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1util_1_1XPathSettings.html
         """
         path = create_instance('com.sun.star.util.PathSettings')
-        return cls.to_system(getattr(path, name))
+        path = cls.to_system(getattr(path, name))
+        return path
 
     @classmethod
     def get(cls, init_dir='', filters: str=''):
         """
+            Get path for save
             Options: http://api.libreoffice.org/docs/idl/ref/namespacecom_1_1sun_1_1star_1_1ui_1_1dialogs_1_1TemplateDescription.html
             filters: 'xml' or 'txt,xml'
         """
@@ -6336,9 +6338,11 @@ class Paths(object):
     @classmethod
     def get_file(cls, init_dir: str='', filters: str='', multiple: bool=False):
         """
+            Get path file
+
             init_folder: folder default open
-            multiple: True for multiple selected
             filters: 'xml' or 'xml,txt'
+            multiple: True for multiple selected
         """
         if not init_dir:
             init_dir = cls.documents
@@ -6436,14 +6440,13 @@ class Paths(object):
 
     @classmethod
     def kill(cls, path):
-        result = True
         p = Path(path)
-
         try:
             if p.is_file():
                 p.unlink()
             elif p.is_dir():
                 shutil.rmtree(path)
+            result = True
         except OSError as e:
             log.error(e)
             result = False
@@ -6474,7 +6477,12 @@ class Paths(object):
         return paths
 
     @classmethod
-    def walk_dir(cls, path, tree=False):
+    def walk_dirs(cls, path, tree=False):
+        """
+            Get directories recursively
+            path: path source
+            tree: get info in a tuple (ID_FOLDER, ID_PARENT, NAME)
+        """
         folders = []
         if tree:
             i = 0