xlwings-utils 0.0.4__py3-none-any.whl → 0.0.6__py3-none-any.whl

xlwings_utils/xlwings_utils.py

@@ -5,36 +5,27 @@
 #  /_/\_\|_|  \_/\_/  |_||_| |_| \__, ||___/ _____  \__,_| \__||_||_||___/
 #                                |___/      |_____|
 
-__version__ = "0.0.4"
+__version__ = "0.0.6"
 
 
 import dropbox
 from pathlib import Path
 import os
-
-class BlockRange:
-    @property
-    def block(self):
-        return block(self.value)
-
-    @block.setter
-    def block(self, block):
-        self.value=block.as_list_of_lists
-try:
-    import xlwings
-    xlwings.Range.block=BlockRange
-except ImportError:
-    ...
+import sys
 
 _captured_stdout = []
 dbx = None
+Pythonista = sys.platform == "ios"
 
 
 def dropbox_init(refresh_token=None, app_key=None, app_secret=None):
     """
     dropbox initialize
 
-    This function has to be called prior to using any dropbox function
+    This function may to be called prior to using any dropbox function
+    to specify the request token, app key and app secret.
+    If these are specified as REFRESH_TOKEN, APP_KEY and APP_SECRET
+    environment variables, it is no necessary to call dropbox_init().
 
     Parameters
     ----------
@@ -58,54 +49,99 @@ def dropbox_init(refresh_token=None, app_key=None, app_secret=None):
     -------
     -
     """
+    global dbx
+
+    if Pythonista:
+        # under Pythonista, the environ is updated from the .environ.toml file, if present
+        environ_file = Path(os.environ["HOME"]) / "Documents" / ".environ.toml"
+
+        if environ_file.is_file():
+            with open(environ_file, "r") as f:
+                import toml
+
+                d = toml.load(f)
+                os.environ.update(d)
+
     if refresh_token is None:
-        refresh_token = os.environ["REFRESH_TOKEN"]
+        if "REFRESH_TOKEN" in os.environ:
+            refresh_token = os.environ["REFRESH_TOKEN"]
+        else:
+            raise ValueError("no REFRESH_TOKEN found in environment.")
     if app_key is None:
-        app_key = os.environ["APP_KEY"]
+        if "APP_KEY" in os.environ:
+            app_key = os.environ["APP_KEY"]
+        else:
+            raise ValueError("no APP_KEY found in environment.")
     if app_secret is None:
-        app_secret = os.environ["APP_SECRET"]
+        if "APP_SECRET" in os.environ:
+            app_secret = os.environ["APP_SECRET"]
+        else:
+            raise ValueError("no APP_SECRET found in environment.")
 
-    global dbx
     dbx = dropbox.Dropbox(oauth2_refresh_token=refresh_token, app_key=app_key, app_secret=app_secret)
+    try:
+        dbx.files_list_folder(path="")  # just to test proper credentials
+    except dropbox.exceptions.AuthError:
+        raise ValueError("invalid dropbox credentials")
 
 
-def _check_dbx():
+def _login_dbx():
     if dbx is None:
-        raise ValueError("not initialized. Please call dropbox_init()")
+        dropbox_init()  # use environment
 
 
-def list_dropbox(path="", recursive=False):
+def list_dropbox(path="", recursive=False, show_files=True, show_folders=False):
     """
     list_dropbox
 
-    returns all dropbox files in path
+    returns all dropbox files/folders in path
 
     Parameters
     ----------
     path : str or Pathlib.Path
         path from which to list all files (default: '')
 
-
     recursive : bool
         if True, recursively list files. if False (default) no recursion
 
+    show_files : bool
+        if True (default), show file entries
+        if False, do not show file entries
+
+    show_folders : bool
+        if True, show folder entries
+        if False (default), do not show folder entries
+
     Returns
     -------
-    files, relative to path : list
+    files : list
+
+    Note
+    ----
+    Directory entries are never returned
+
+    Note
+    ----
+    If REFRESH_TOKEN, APP_KEY and APP_SECRET environment variables are specified,
+    it is not necessary to call dropbox_init() prior to any dropbox function.
     """
-    _check_dbx()
+    _login_dbx()
     out = []
     result = dbx.files_list_folder(path, recursive=recursive)
 
     for entry in result.entries:
-        if isinstance(entry, dropbox.files.FileMetadata):
+        if show_files and isinstance(entry, dropbox.files.FileMetadata):
             out.append(entry.path_display)
+        if show_folders and isinstance(entry, dropbox.files.FolderMetadata):
+            out.append(entry.path_display + "/")
 
     while result.has_more:
         result = dbx.files_list_folder_continue(result.cursor)
         for entry in result.entries:
-            if isinstance(entry, dropbox.files.FileMetadata):
+            if show_files and isinstance(entry, dropbox.files.FileMetadata):
                 out.append(entry.path_display)
+            if show_folders and isinstance(entry, dropbox.files.FolderMetadata):
+                out.append(entry.path_display + "/")
 
     return out
 
@@ -124,16 +160,21 @@ def read_dropbox(dropbox_path):
     Returns
     -------
     contents of the dropbox file : bytes
+
+    Note
+    ----
+    If REFRESH_TOKEN, APP_KEY and APP_SECRET environment variables are specified,
+    it is not necessary to call dropbox_init() prior to any dropbox function.
     """
 
-    _check_dbx()
+    _login_dbx()
     metadata, response = dbx.files_download(dropbox_path)
     file_content = response.content
     return file_content
 
 
 def write_dropbox(dropbox_path, contents):
-    _check_dbx()
+    _login_dbx()
     """
     write_dropbox
     
@@ -147,13 +188,53 @@ def write_dropbox(dropbox_path, contents):
     contents : bytes
         contents to be written
         
+    Note
+    ----
+    If REFRESH_TOKEN, APP_KEY and APP_SECRET environment variables are specified,
+    it is not necessary to call dropbox_init() prior to any dropbox function.
     """
     dbx.files_upload(contents, dropbox_path, mode=dropbox.files.WriteMode.overwrite)
 
 
-def list_local(path):
+def list_local(path, recursive=False, show_files=True, show_folders=False):
+    """
+    list_local
+
+    returns all local files/folders in path
+
+    Parameters
+    ----------
+    path : str or Pathlib.Path
+        path from which to list all files (default: '')
+
+    recursive : bool
+        if True, recursively list files. if False (default) no recursion
+
+    show_files : bool
+        if True (default), show file entries
+        if False, do not show file entries
+
+    show_folders : bool
+        if True, show folder entries
+        if False (default), do not show folder entries
+     
+    Returns
+    -------
+    files, relative to path : list
+    """
     path = Path(path)
-    return list(path.iterdir())
+
+    result = []
+    for entry in path.iterdir():
+        if entry.is_file():
+            if show_files:
+                result.append(str(entry))
+        elif entry.is_dir():
+            if show_folders:
+                result.append(str(entry) + "/")
+            if recursive:
+                result.extend(list_local(entry, recursive=recursive, show_files=show_files, show_folders=show_folders))
+    return result
 
 
 def write_local(path, contents):
@@ -172,7 +253,7 @@ def read_local(path):
 
 class block:
     """
-    block is 2 dimensional with 1 as lowest index (like xlwings range) data structure
+    block is 2 dimensional data structure with 1 as lowest index (like xlwings range)
 
     Parameters
     ----------
@@ -207,7 +288,7 @@ class block:
 
             if True, one dimenional lists will be treated as a 1 wide range (column-like)
 
-            This parameter is not used for proper 2 dimensional list of lists
+            This parameter is not used for proper 2 dimensional list of lists or scalars
 
         Returns
         -------
@@ -240,17 +321,17 @@ class block:
     def __setitem__(self, row_column, value):
         row, column = row_column
         if row < 1 or row > self.number_of_rows:
-            raise IndexError
+            raise IndexError(f"row must be between 1 and {self.number_of_rows} not {row}")
         if column < 1 or column > self.number_of_columns:
-            raise IndexError
+            raise IndexError(f"column must be between 1 and {self.number_of_columns} not {column}")
         self.dict[row, column] = value
 
     def __getitem__(self, row_column):
         row, column = row_column
         if row < 1 or row > self.number_of_rows:
-            raise IndexError
+            raise IndexError(f"row must be between 1 and {self.number_of_rows} not {row}")
         if column < 1 or column > self.number_of_columns:
-            raise IndexError
+            raise IndexError(f"column must be between 1 and {self.number_of_columns} not {column}")
         return self.dict.get((row, column))
 
     @property
@@ -267,7 +348,7 @@ class block:
 
     @number_of_rows.setter
     def number_of_rows(self, value):
-        if value<1:
+        if value < 1:
             raise ValueError(f"number_of_rows should be >=1, not {value}")
         self._number_of_rows = value
         for row, column in list(self.dict):
@@ -280,7 +361,7 @@ class block:
 
     @number_of_columns.setter
     def number_of_columns(self, value):
-        if value<1:
+        if value < 1:
             raise ValueError(f"number_of_columns should be >=1, not {value}")
         self._number_of_columns = value
         for row, column in list(self.dict):
@@ -314,7 +395,7 @@ def clear_captured_stdout():
 
 def captured_stdout_as_str():
     """
-    returns the captured stdout as a list of strings
+    returns the captured stdout as a string
 
     Returns
     -------
@@ -333,14 +414,17 @@ def captured_stdout_as_list_of_lists():
     -------
     captured stdout : list
         each line is an element of the list
-    """
 
+    Note
+    ----
+    This can be used directly to fill a xlwings range
+    """
     return [[line] for line in captured_stdout_as_str().splitlines()]
 
 
 class capture_stdout:
     """
-    specifies how to capture stdout
+    start capture stdout
 
     Parameters
     ----------

{xlwings_utils-0.0.4.dist-info → xlwings_utils-0.0.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 0.0.4
+Version: 0.0.6
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -10,28 +10,37 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: dropbox
+Requires-Dist: ssl
 
-# xlwings_utils
+ <img src="https://www.salabim.org/xlwings_utils_logo1.png"> 
 
 ## Introduction
 
 This module provides some useful functions to be used in xlwings lite.
+
 The xlwings lite system does not provide access to the local file system. With this
-module, files can be copied between dropbox and the pyodide file systen. And
+module, files can be copied between dropbox and the local pyodide file systen. And
 therefore, it is possible to indirectly use the local file system.
 
+The module contains support for a useful 2 dimensional data structure: block.
+Thjs can be useful to manipulate a range without accessing the range directly,
+which is expensive in terms of memory and execution time.
+
 On top of that, this module makes it possible to capture stdout writes, which
 can then be copied to a worksheet in a later stage.
 
 ## Installation
 
-Just add xlwings-utils to the requirement tab.
+Just add xlwings-utils to the requirement tab. It might be required to add ssl.
 
 ## Dropbox support
 
 xlwings_lite only works with full access dropbox apps.
 
-In order to use dropbox, is is necessary to initialize the module with credentials.
+In order to use dropbox functionality, is is necessary to initialize the module with credentials.
+
+```xwu.dropbox_init()```
+If called without parameters, the refresh_token is
 
 ## Capture stdout support
 

xlwings_utils-0.0.6.dist-info/RECORD

@@ -0,0 +1,6 @@
+xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
+xlwings_utils/xlwings_utils.py,sha256=yvWW2yRjkHvF5814ptlbGxT5tpRRg-wH1yCDO-5qIe8,12866
+xlwings_utils-0.0.6.dist-info/METADATA,sha256=0fJEsPdOJ1uoHQnAeGzB5dPm-qKD9F_1CGfP9h1Oc4s,2083
+xlwings_utils-0.0.6.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+xlwings_utils-0.0.6.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
+xlwings_utils-0.0.6.dist-info/RECORD,,

{xlwings_utils-0.0.4.dist-info → xlwings_utils-0.0.6.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.3.0)
+Generator: setuptools (80.3.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

xlwings_utils-0.0.4.dist-info/RECORD

@@ -1,6 +0,0 @@
-xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
-xlwings_utils/xlwings_utils.py,sha256=J2eMXggaLHXLyNnw5n3Am6bDrMxgdyZZxT24lhmhups,9494
-xlwings_utils-0.0.4.dist-info/METADATA,sha256=H1En9zmkXwQaRbANKdz64auexCwoCN_BFeY0n-cm_yk,1662
-xlwings_utils-0.0.4.dist-info/WHEEL,sha256=GHB6lJx2juba1wDgXDNlMTyM13ckjBMKf-OnwgKOCtA,91
-xlwings_utils-0.0.4.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
-xlwings_utils-0.0.4.dist-info/RECORD,,