xlwings-utils 25.0.1__py3-none-any.whl → 25.0.3__py3-none-any.whl

xlwings_utils/xlwings_utils.py

@@ -5,7 +5,7 @@
 #  /_/\_\|_|  \_/\_/  |_||_| |_| \__, ||___/ _____  \__,_| \__||_||_||___/
 #                                |___/      |_____|
 
-__version__ = "25.0.1"
+__version__ = "25.0.3"
 
 
 import dropbox
@@ -18,11 +18,15 @@ dbx = None
 Pythonista = sys.platform == "ios"
 try:
     import xlwings
+
     xlwings = True
 except ImportError:
-    xlwings=False
+    xlwings = False
+
+missing = object()
+
 
-def dropbox_init(refresh_token=None, app_key=None, app_secret=None):
+def dropbox_init(refresh_token=missing, app_key=missing, app_secret=missing):
     """
     dropbox initialize
 
@@ -66,17 +70,17 @@ def dropbox_init(refresh_token=None, app_key=None, app_secret=None):
                 d = toml.load(f)
                 os.environ.update(d)
 
-    if refresh_token is None:
+    if refresh_token is missing:
         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:
+    if app_key is missing:
         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:
+    if app_secret is missing:
         if "APP_SECRET" in os.environ:
             app_secret = os.environ["APP_SECRET"]
         else:
@@ -169,11 +173,15 @@ def read_dropbox(dropbox_path):
     ----
     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.
+
+    If the file size does not match the metadata, as sometimes happens on pyodide, an OSError exception will be raised.
     """
 
     _login_dbx()
     metadata, response = dbx.files_download(dropbox_path)
     file_content = response.content
+    if len(file_content) != metadata.size:
+        raise OSError(f"file size ({len(file_content)}) does not match metadata ({metadata.size})")
     return file_content
 
 
@@ -272,13 +280,13 @@ class block:
     block
     """
 
-    def __init__(self, value=None, *, number_of_rows=None, number_of_columns=None, column_like=False):
+    def __init__(self, value=missing, *, number_of_rows=missing, number_of_columns=missing, column_like=False):
         self.dict = {}
         self.column_like = column_like
-        if value is None:
-            if number_of_rows is None:
+        if value is missing:
+            if number_of_rows is missing:
                 number_of_rows = 1
-            if number_of_columns is None:
+            if number_of_columns is missing:
                 number_of_columns = 1
             self.number_of_rows = number_of_rows
             self.number_of_columns = number_of_columns
@@ -287,29 +295,29 @@ class block:
             if isinstance(value, block):
                 value = value.value
             self.value = value
-            if number_of_rows is not None:
+            if number_of_rows is not missing:
                 self.number_of_rows = number_of_rows
-            if number_of_columns is not None:
+            if number_of_columns is not missing:
                 self.number_of_columns = number_of_columns
 
     @classmethod
-    def from_xlrd_sheet(cls, sheet, number_of_rows=None, number_of_columns=None):
+    def from_xlrd_sheet(cls, sheet, number_of_rows=missing, number_of_columns=missing):
         v = [sheet.row_values(row_idx)[0 : sheet.ncols] for row_idx in range(0, sheet.nrows)]
         return cls(v, number_of_rows=number_of_rows, number_of_columns=number_of_columns)
 
     @classmethod
-    def from_openpyxl_sheet(cls, sheet, number_of_rows=None, number_of_columns=None):
+    def from_openpyxl_sheet(cls, sheet, number_of_rows=missing, number_of_columns=missing):
         v = [[cell.value for cell in row] for row in sheet.iter_rows()]
         return cls(v, number_of_rows=number_of_rows, number_of_columns=number_of_columns)
 
     @classmethod
-    def from_file(cls, filename, number_of_rows=None, number_of_columns=None):
+    def from_file(cls, filename, number_of_rows=missing, number_of_columns=missing):
         with open(filename, "r") as f:
-            v = [[line if line else None] for line in f.read().splitlines()]
+            v = [[line if line else missing] for line in f.read().splitlines()]
         return cls(v, number_of_rows=number_of_rows, number_of_columns=number_of_columns)
 
     @classmethod
-    def from_dataframe(cls, df, number_of_rows=None, number_of_columns=None):
+    def from_dataframe(cls, df, number_of_rows=missing, number_of_columns=missing):
         v = df.values.tolist()
         return cls(v, number_of_rows=number_of_rows, number_of_columns=number_of_columns)
 
@@ -420,7 +428,7 @@ class block:
         if column > self.number_of_columns:
             raise ValueError(f"{name}={column} > number_of_columns={self.number_of_columns}")
 
-    def vlookup(self, s, *, row_from=1, row_to=None, column1=1, column2=None):
+    def vlookup(self, s, *, row_from=1, row_to=missing, column1=1, column2=missing, default=missing):
         """
         searches in column1 for row between row_from and row_to for s and returns the value found at (that row, column2)
 
@@ -449,21 +457,28 @@ class block:
 
              should be between 1 and number_of_columns
 
+        default : any
+             if s is not found, returns the default.
+
+             if omitted, a ValueError exception will be raised in that case
+
         Returns
         -------
         block[found row number, column2] : any
-
-        Note
-        ----
-        If s is not found, a ValueError is raised
         """
-        if column2 is None:
+        if column2 is missing:
             column2 = column1 + 1
         self._check_column(column2, "column2")
-        row = self.lookup_row(s, row_from=row_from, row_to=row_to, column1=column1)
-        return self[row, column2]
+        row = self.lookup_row(s, row_from=row_from, row_to=row_to, column1=column1, default=-1)
+        if row == -1:
+            if default is missing:
+                raise ValueError(f"{s} not found]")
+            else:
+                return default
+        else:
+            return self[row, column2]
 
-    def lookup_row(self, s, *, row_from=1, row_to=None, column1=1):
+    def lookup_row(self, s, *, row_from=1, row_to=missing, column1=1, default=missing):
         """
         searches in column1 for row between row_from and row_to for s and returns that row number
 
@@ -490,15 +505,22 @@ class block:
         column2 : int
              column to return looked up value from (default column1 + 1)
 
+        default : any
+             if s is not found, returns the default.
+
+             if omitted, a ValueError exception will be raised
+
+        default : any
+             if s is not found, returns the default.
+
+             if omitted, a ValueError exception will be raised in that case
+
+
         Returns
         -------
         row number where block[row nunber, column1] == s : int
-
-        Note
-        ----
-        If s is not found, a ValueError is raised
         """
-        if row_to is None:
+        if row_to is missing:
             row_to = self.highest_used_row_number
         self._check_row(row_from, "row_from")
         self._check_row(row_to, "row_to")
@@ -507,9 +529,12 @@ class block:
         for row in range(row_from, row_to + 1):
             if self[row, column1] == s:
                 return row
-        raise ValueError(f"{s} not found")
+        if default is missing:
+            raise ValueError(f"{s} not found")
+        else:
+            return default
 
-    def hlookup(self, s, *, column_from=1, column_to=None, row1=1, row2=None):
+    def hlookup(self, s, *, column_from=1, column_to=missing, row1=1, row2=missing, default=missing):
         """
         searches in row1 for column between column_from and column_to for s and returns the value found at (that column, row2)
 
@@ -538,21 +563,28 @@ class block:
 
              should be between 1 and number_of_rows
 
+        default : any
+             if s is not found, returns the default.
+
+             if omitted, a ValueError exception will be raised in that case
+
         Returns
         -------
         block[row, found column, row2] : any
-
-        Note
-        ----
-        If s is not found, a ValueError is raised
         """
-        if row2 is None:
+        if row2 is missing:
             row2 = row1 + 1
         self._check_row(row2, "row2")
-        column = self.lookup_column(s, column_from=column_from, column_to=column_to, row1=row1)
-        return self[row2, column]
+        column = self.lookup_column(s, column_from=column_from, column_to=column_to, row1=row1, default=-1)
+        if column == -1:
+            if default is missing:
+                raise ValueError(f"{s} not found")
+            else:
+                return default
+        else:
+            return self[row2, column]
 
-    def lookup_column(self, s, *, column_from=1, column_to=None, row1=1):
+    def lookup_column(self, s, *, column_from=1, column_to=missing, row1=1, default=missing):
         """
         searches in row1 for column between column_from and column_to for s and returns that column number
 
@@ -579,15 +611,16 @@ class block:
         row2 : int
              row to return looked up value from (default row1 + 1)
 
+        default : any
+             if s is not found, returns the default.
+
+             if omitted, a ValueError exception will be raised in that case
+
         Returns
         -------
         column number where block[row1, column number] == s : int
-
-        Note
-        ----
-        If s is not found, a ValueError is raised
         """
-        if column_to is None:
+        if column_to is missing:
             column_to = self.highest_used_column_number
         self._check_column(column_from, "column_from")
         self._check_column(column_to, "column_to")
@@ -596,9 +629,12 @@ class block:
         for column in range(column_from, column_to + 1):
             if self[row1, column] == s:
                 return column
-        raise ValueError(f"{s} not found")
+        if default is missing:
+            raise ValueError(f"{s} not found")
+        else:
+            return default
 
-    def lookup(self, s, *, row_from=1, row_to=None, column1=1, column2=None):
+    def lookup(self, s, *, row_from=1, row_to=missing, column1=1, column2=missing, default=missing):
         """
         searches in column1 for row between row_from and row_to for s and returns the value found at (that row, column2)
 
@@ -627,17 +663,20 @@ class block:
 
              should be between 1 and number_of_columns
 
+        default : any
+             if s is not found, returns the default.
+
+             if omitted, a ValueError exception will be raised in that case
+
         Returns
         -------
         block[found row number, column2] : any
 
         Note
         ----
-        If s is not found, a ValueError is raised
-
         This is exactly the same as vlookup.
         """
-        return self.vlookup(s, row_from=row_from, row_to=row_to, column1=column1, column2=column2)
+        return self.vlookup(s, row_from=row_from, row_to=row_to, column1=column1, column2=column2, default=default)
 
 
 class Capture:
@@ -648,9 +687,9 @@ class Capture:
     ----------
     enabled : bool
         if True (default), all stdout output is captured
-        
-        if False, stdout output is printed 
-        
+
+        if False, stdout output is printed
+
     include_print : bool
         if False (default), nothing will be printed if enabled is True
 
@@ -658,10 +697,9 @@ class Capture:
 
     Note
     ----
-    Use this function, like ::
+    Use this like ::
 
-        capture = xwu.Capture():
-            ...
+        capture = xwu.Capture()
     """
 
     _instance = None
@@ -672,21 +710,21 @@ class Capture:
             cls._instance = super(Capture, cls).__new__(cls)
         return cls._instance
 
-    def __init__(self, enabled=None, include_print=None):
+    def __init__(self, enabled=missing, include_print=missing):
         if hasattr(self, "stdout"):
-            if enabled is not None:
+            if enabled is not missing:
                 self.enabled = enabled
-            if include_print is not None:
+            if include_print is not missing:
                 self.include_print = include_print
             return
         self.stdout = sys.stdout
         self._buffer = []
-        self.enabled = True if enabled is None else enabled
-        self.include_print = False if include_print is None else include_print
+        self.enabled = True if enabled is missing else enabled
+        self.include_print = False if include_print is missing else include_print
 
-    def __call__(self, enabled=None, include_print=None):
+    def __call__(self, enabled=missing, include_print=missing):
         return self.__class__(enabled, include_print)
-    
+
     def __enter__(self):
         self.enabled = True
 
@@ -750,4 +788,3 @@ class Capture:
 
 if __name__ == "__main__":
     ...
-

{xlwings_utils-25.0.1.dist-info → xlwings_utils-25.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.1
+Version: 25.0.3
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -48,12 +48,19 @@ The xlwings lite system does not provide access to the local file system. With t
 
 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.
+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. Instructions on how to get these variables can be found here.
 
-Then, it is possible to list all files in a specified folder with the function `list_dropbox`.
+In order to make a Dropbox app, and get the required environment variables, just execute this line from the command line (shell).
+
+```
+python -c "exec(__import__('requests').get('https://salabim.org/dropbox setup.py').text)"
+```
+
+Then, it is possible to list all files in a specified folder using the list_dropbox function.
 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 `read_dropbox` function can be used to read the contents (bytes) of a Dropbox file. If the file is not read correctly, which seems
+to happen rather frequently, an OSError exception is raised.
 
 The function `write_dropbox` can be used to write contents (bytes) to a Dropbox file.
 
@@ -80,7 +87,7 @@ This can be useful to manipulate a range without accessing the range directly, w
 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`. 
+A block stores the values internally as a dictionary and will only convert these to a list of lists when using `block.value` or `block.value_keep`. 
 
 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
 
@@ -97,7 +104,7 @@ 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 not allowed to read or write outside the block dimensions.
 
 It is also possible to define an empty block, like
 ```
@@ -138,9 +145,13 @@ With blocks, it is easy to use a sheet as an input for a project / scenario.
 Something like
  <img src="https://www.salabim.org/xlwings_utils/fig01.png">  
 
-Of course, we could access the various input fields with absolute ranges, but if something changes later (like adding a row), all references would have to be updated.
+Of course, we could access the various input fields with absolute ranges, but if something changes later (such as adding a row), all references would need to be updated.
 
-If we read the project sheet (partly) into a block, lookup methods are available to access 'fields' easily and future-proof.
+If we read the project sheet (partly) into a block, lookup methods are available to access *fields* easily and future-proof:
+
+```
+bl = xwu.block.from_value(sheet.range((0,0),(100,10)).value)
+```
 
 Let's see how this works with the above sheet. The corresponding block (bl) looks like
 
@@ -174,29 +185,27 @@ for row2 in range(row1 + 1, bl.highest_used_row_number + 1):
     weight = bl.hlookup("Weight",row1=row1, row2=row2)         
     parts.append(Part(part_name, width, length, height, weight))
 ```
-First we do a couple of `lookup`s, which are vertical lookups, to scan column 1 for the given labels and return the corresponding values from column 2.
+First, we perform a couple of vertical lookups to scan column 1 for the given labels and return the corresponding values from column 2.
 
 Then, there's `lookup_row`, which also scans column1 for the given label (Parts), but returns the corresponding row (5). It is then stored in row1.
-And then we just read the following rows (with `hlookup`) and access the required values.
+We then read the following rows (using hlookups) and access the required values.
 
 ### Filling a block from other sources
 
-The advantage of using a block instead of accessing these sources is, that they are one-based, just like in Excel.
+The advantage of using a block instead of accessing these sources is	 that they are one-based, just like in Excel.
 
-It is possible to make a block from a xlrd worksheet with `block.from_xlrd_sheet`. 
+It is possible to make a block from an xlrd worksheet with `block.from_xlrd_sheet`. 
 
-It is possible to make a block from a pandas dataframe with `block.from_dataframe`. Make sure that, if the dataframe is created by reading from an Excel sheet, headers=None should be specified, e.g. `df = pd.read_excel(filename, header=None)`.
+It is possible to make a block from a pandas dataframe with `block.from_dataframe`. Ensure that, if the dataframe is created by reading from an Excel sheet, headers=None is specified, e.g., `df = pd.read_excel(filename, header=None)`.
 
 It is possible to make a block from an openpyxl worksheet with `block.from_openpyxl_sheet`. 
 
-### Writing a block to an openpyxl sheet
-
-In order to write (append) to an openpyxl sheet, use: block.to_openpyxl_sheet.
-
 It is possible to make a block from a text file with `block.from_file`. 
 
 ### Writing a block to an openpyxl sheet
 
+In order to write (append) to an openpyxl sheet, use: block.to_openpyxl_sheet.
+
 ## Capture stdout support
 
 The module has support for capturing stdout and -later- using showing the captured output on a sheet.

xlwings_utils-25.0.3.dist-info/RECORD

@@ -0,0 +1,6 @@
+xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
+xlwings_utils/xlwings_utils.py,sha256=GXuxgnbZ4WzhTy3QM16Ru1ofj4FIAauWN36kXDFFDQ8,23356
+xlwings_utils-25.0.3.dist-info/METADATA,sha256=CapEwbNevIQnlpCndBQMkS3isd7tPWCK2NZnX7yA6xg,10223
+xlwings_utils-25.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xlwings_utils-25.0.3.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
+xlwings_utils-25.0.3.dist-info/RECORD,,

{xlwings_utils-25.0.1.dist-info → xlwings_utils-25.0.3.dist-info}/WHEEL

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

xlwings_utils-25.0.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
-xlwings_utils/xlwings_utils.py,sha256=8_OKnH-UnvOZnybavnC4CEWAR27IiqfTGyezWja-s-o,21809
-xlwings_utils-25.0.1.dist-info/METADATA,sha256=G6E8CscnLZ6zinaPdl1XbSBQuDZcKfMi3AwdSVppb0k,9791
-xlwings_utils-25.0.1.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-xlwings_utils-25.0.1.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
-xlwings_utils-25.0.1.dist-info/RECORD,,