xlwings-utils 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

xlwings_utils/xlwings_utils.py

@@ -5,22 +5,27 @@
 #  /_/\_\|_|  \_/\_/  |_||_| |_| \__, ||___/ _____  \__,_| \__||_||_||___/
 #                                |___/      |_____|
 
-__version__ = "0.0.5"
+__version__ = "0.0.7"
 
 
 import dropbox
 from pathlib import Path
 import os
+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
     ----------
@@ -44,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
 
@@ -110,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
     
@@ -133,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):
@@ -173,55 +268,51 @@ class block:
     block
     """
 
-    def __init__(self, number_of_rows, number_of_columns):
+    def __init__(self, value=None, *, number_of_rows=None, number_of_columns=None,column_like=False):
         self.dict = {}
-        self.number_of_columns = number_of_columns
-        self.number_of_rows = number_of_rows
-
-    @classmethod
-    def from_list_of_lists(cls, list_of_lists, column_like=False):
-        """
-        from_list_of_lists
-
-        Parameters
-        ----------
-        list_of_lists : list of lists
-            to be used to fill the block
-
-        columns_like : bool
-            if False (default), one dimenional lists will be treated as a 1 high range (row-like)
-
-            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 or scalars
-
-        Returns
-        -------
-        block
-
-        Note
-        ----
-        number_of_rows and number_of_columns will be retrieved from list_of_lists dimension
-        """
-        if not isinstance(list_of_lists, list):
-            list_of_lists = [[list_of_lists]]
-        if not isinstance(list_of_lists[0], list):
-            if column_like:
-                list_of_lists = [[value] for value in list_of_lists]
+        self.column_like=column_like
+        if value is None:
+            if number_of_rows is None:
+                 number_of_rows=1
+            if number_of_columns is None:
+                 number_of_columns=1
+            self.number_of_rows=number_of_rows
+            self.number_of_columns=number_of_columns                 
+            
+        else:
+            if isinstance(value,block):
+                value=value.value
+            self.value=value
+            if number_of_rows is not None:
+                self.number_of_rows=number_of_rows
+            if number_of_columns is not None:
+                self.number_of_columns=number_of_columns            
+
+        
+    @property
+    def value(self):
+        return [[self.dict.get((row, column)) for column in range(1, self.number_of_columns + 1)] for row in range(1, self.number_of_rows + 1)]
+        
+    @value.setter
+    def value(self,value): 
+        if not isinstance(value, list):
+            value = [[value]]
+        if not isinstance(value[0], list):
+            if self.column_like:
+                value = [[item] for item in value]
             else:
-                list_of_lists = [list_of_lists]
+                value = [value]
 
-        self = cls(1, 1)
 
-        self.number_of_rows = len(list_of_lists)
+        self.number_of_rows = len(value)
         self._number_of_columns = 0
 
-        for row, row_contents in enumerate(list_of_lists, 1):
-            for column, value in enumerate(row_contents, 1):
-                if value is not None:
-                    self.dict[row, column] = value
-                    self._number_of_columns = max(self.number_of_columns, column)
-        return self
+        for row, row_contents in enumerate(value, 1):
+            for column, item in enumerate(row_contents, 1):
+                if item is not None:
+                    self.dict[row, column] = item
+                    self._number_of_columns = max(self.number_of_columns, column)                
+
 
     def __setitem__(self, row_column, value):
         row, column = row_column
@@ -238,14 +329,9 @@ class block:
         if column < 1 or column > self.number_of_columns:
             raise IndexError(f"column must be between 1 and {self.number_of_columns} not {column}")
         return self.dict.get((row, column))
-
-    @property
-    def as_list_of_lists(self):
-        return [[self.dict.get((row, column)) for column in range(1, self.number_of_columns + 1)] for row in range(1, self.number_of_rows + 1)]
-
-    @property
-    def as_minimal_list_of_lists(self):
-        return [[self.dict.get((row, column)) for column in range(1, self.maximum_column + 1)] for row in range(1, self.maximum_row + 1)]
+        
+    def minimized(self):
+        return block(self, number_of_rows=self.highest_used_row_number, number_of_columns=self.highest_used_column_number)
 
     @property
     def number_of_rows(self):
@@ -253,7 +339,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):
@@ -266,29 +352,30 @@ 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):
             if column > self._number_of_columns:
                 del self.dict[row, column]
+    
 
     @property
-    def maximum_row(self):
+    def highest_used_row_number(self):
         if self.dict:
             return max(row for (row, column) in self.dict)
         else:
             return 1
 
     @property
-    def maximum_column(self):
+    def highest_used_column_number(self):
         if self.dict:
             return max(column for (row, column) in self.dict)
         else:
             return 1
 
     def __repr__(self):
-        return f"block.from_list_of_lists({self.as_list_of_lists})"
+        return f"block({self.value})"
 
 
 def clear_captured_stdout():
@@ -300,7 +387,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
     -------
@@ -311,7 +398,7 @@ def captured_stdout_as_str():
     return "".join(_captured_stdout)
 
 
-def captured_stdout_as_list_of_lists():
+def captured_stdout_as_value():
     """
     returns the captured stdout as a list of lists
 
@@ -319,14 +406,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.7.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: xlwings_utils
+Version: 0.0.7
+Summary: xlwings_utils
+Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
+Project-URL: Homepage, https://github.com/salabim/xlwings_utils
+Project-URL: Repository, https://github.com/salabim/xlwings_utils
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: dropbox
+Requires-Dist: ssl
+
+ <img src="https://www.salabim.org/xlwings_utils_logo2.png">  
+
+## Introduction
+
+This module provides some useful functions to be used in xlwings lite.
+
+## Installation
+
+Just add xlwings-utils to the *requirement.txt* tab. It might be required to add ssl.
+
+In the script, add
+
+```ìmport xlwings_utils as xwu```
+
+## Dropbox support
+
+The xlwings lite system does not provide access to the local file system. With this module, files can be copied between Dropbox and the local pyodide file system, making it possible to indirectly use the local file system.
+
+It is only possible, as of now, to use full-access Dropbox apps.
+
+The easiest way to use the Dropbox functionality is to add the credentials to the environment variables. Add REFRESH_TOKEN, APP_KEY and APP_SECRET with their corresponding values to the environment variables.
+
+Then, it is possible to list all files in a specified folder with the function `list_dropbox`.
+It is also possible to get the folders and to access all underlying folders.
+
+The function `read_dropbox` can be used to read a Dropbox file's contents (bytes).
+
+The function `write_dropbox` can be used to write contents (bytes) to a Dropbox file.
+
+The functions `list_local`, `read_local` and `write_local` offer similar functionality for the local file system (on pyodide).
+
+So, a way to access a file on the system's drive (mapped to Dropbox) as a local file is:
+
+```
+contents = xlwings_utils.read_dropbox('/downloads/file1.xls')
+xlwings_utils.write_local('file1.xlsx')
+df = pandas.read_excel"file1.xlsx")
+...
+```
+And the other direction:
+```
+contents = xlwings_utils.read_local('file1.gif')
+xlwings_utils.write_dropbox('/downloads/file1.gif')
+```
+
+## Block support
+
+The module contains a useful 2-dimensional data structure: *block*.
+This can be useful to manipulate a range without accessing the range directly, which is expensive in terms of memory and execution time.
+The advantage over an ordinary list of lists is that a block is index one-based, in line with range and addressing is done with a row, column tuple.
+So, `my_block(lol)[row, col]` is roughly equivalent to `lol[row-1][col-1]`
+
+A block stores the values internally as a dictionary and will only convert these to a list of lists when using `block.value`. 
+
+Converting the value of a range (usually a list of lists, but can also be a list or scalar) to a block can be done with
+
+```
+my_block = xwu.block.from_value(range.value)
+```
+The dimensions (number of rows and number of columns) are automatically set.
+
+Setting of an individual item (one-based, like range) can be done like
+```
+my_block[row, column] = x
+```
+And, likewise, reading an individual item can be done like
+```
+x = my_block[row, column]
+```
+It is not allowed t,o read or write outside the block dimensions.
+
+It is also possible to define an empty block, like
+```
+block = xlwings_utils.block(number_of_rows, number_columns)
+```
+The dimensions can be queried or redefined with `block.number_of_rows` and 
+`block.number_of_columns`.
+
+To assign a block to range, use
+```
+range.value = block.value
+```
+
+The property `block.highest`_used_row_number returns the
+
+The method `block.minimized()` returns a block that has the dimensions of (highest_used_row_number, highest_used_column_number). 
+
+## Capture stdout support
+
+The module has support for capturing stdout and -later- using showing the captured output on a sheet.
+
+To do that:
+
+```makes it possible to capture stdout writes, which
+with xwu.capture_stdout():
+    ...
+```
+and then the captured output can be copied to the screen, like
+
+```can then be copied to a worksheet in a later stage.
+sheet.range(4,5).value = xwu.captured_stdout_as_value()
+```
+
+Clearing the captured stdout buffer can be done with `xwu.clear_captured_std_out`.
+
+Normally, stdout will be also sent to the xlwings lite UI panel. This can be suppressed with
+
+```
+with xwu.capture_stdout(include_print=False):
+    ...
+```
+
+## Badges
+
+![PyPI](https://img.shields.io/pypi/v/xlwings-utils) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/xlwings-utils) ![PyPI - Implementation](https://img.shields.io/pypi/implementation/xlwings-utils)
+![PyPI - License](https://img.shields.io/pypi/l/xlwings-utils) ![ruff](https://img.shields.io/badge/style-ruff-41B5BE?style=flat) 
+![GitHub last commit](https://img.shields.io/github/last-commit/salabim/peek)
+

xlwings_utils-0.0.7.dist-info/RECORD

@@ -0,0 +1,6 @@
+xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
+xlwings_utils/xlwings_utils.py,sha256=gCAgs3x6BjHaCX8I3HVw-s84EIS4pkrYQzCK38yG5T4,12656
+xlwings_utils-0.0.7.dist-info/METADATA,sha256=js1Qw-rZuxDke_i-AjBl8P7mXZ7aMocqlJYj9Gfgyjg,4962
+xlwings_utils-0.0.7.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+xlwings_utils-0.0.7.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
+xlwings_utils-0.0.7.dist-info/RECORD,,

{xlwings_utils-0.0.5.dist-info → xlwings_utils-0.0.7.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.5.dist-info/METADATA

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: xlwings_utils
-Version: 0.0.5
-Summary: xlwings_utils
-Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
-Project-URL: Homepage, https://github.com/salabim/xlwings_utils
-Project-URL: Repository, https://github.com/salabim/xlwings_utils
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: dropbox
-
-# xlwings_utils
-
-## 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
-therefore, it is possible to indirectly use the local file system.
-
-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.
-
-## 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.
-
-## Capture stdout support
-
- Badges
-
-![PyPI](https://img.shields.io/pypi/v/xlwings-utils) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/xlwings-utils) ![PyPI - Implementation](https://img.shields.io/pypi/implementation/xlwings-utils)
-![PyPI - License](https://img.shields.io/pypi/l/xlwings-utils) ![ruff](https://img.shields.io/badge/style-ruff-41B5BE?style=flat) 
-![GitHub last commit](https://img.shields.io/github/last-commit/salabim/peek)
-

xlwings_utils-0.0.5.dist-info/RECORD

@@ -1,6 +0,0 @@
-xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
-xlwings_utils/xlwings_utils.py,sha256=RiDWmEsUQclIjB5fYofA9D4WRIp3qQLMFq5-vEkOJ4E,9508
-xlwings_utils-0.0.5.dist-info/METADATA,sha256=XiPrWlKI2a683dGVOa7FMBsYt5SqOhGe8cu7FTQDU1w,1662
-xlwings_utils-0.0.5.dist-info/WHEEL,sha256=GHB6lJx2juba1wDgXDNlMTyM13ckjBMKf-OnwgKOCtA,91
-xlwings_utils-0.0.5.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
-xlwings_utils-0.0.5.dist-info/RECORD,,