xlwings-utils 25.0.2__tar.gz → 25.0.3.post0__tar.gz

{xlwings_utils-25.0.2 → xlwings_utils-25.0.3.post0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.2
+Version: 25.0.3.post0
 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.2 → xlwings_utils-25.0.3.post0}/README.md

@@ -34,12 +34,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.
 
@@ -66,7 +73,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
 
@@ -83,7 +90,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
 ```
@@ -124,9 +131,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
 
@@ -160,29 +171,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.2 → xlwings_utils-25.0.3.post0}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
     { name = "Ruud van der Ham", email = "rt.van.der.ham@gmail.com" },
 ]
 description = "xlwings_utils"
-version = "25.0.2"
+version = "25.0.3.post0"
 readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [

{xlwings_utils-25.0.2 → xlwings_utils-25.0.3.post0}/tests/test_xlwings_utils.py

@@ -108,6 +108,7 @@ def test_lookup():
     assert bl.lookup(3, column2=3)=="Trois"
     with pytest.raises(ValueError):
         bl.lookup(4)
+    assert bl.lookup(4,default='x')=='x'        
     with pytest.raises(ValueError):
         bl.lookup(1, column1=4)
     with pytest.raises(ValueError):
@@ -121,6 +122,7 @@ def test_vookup():
     assert bl.vlookup(3, column2=3)=="Trois"
     with pytest.raises(ValueError):
         bl.vlookup(4)
+    assert bl.vlookup(4, default='x')=='x'
     with pytest.raises(ValueError):
         bl.vlookup(1, column1=4)
     with pytest.raises(ValueError):
@@ -133,6 +135,7 @@ def test_hlookup():
     assert bl.hlookup(3, row2=3)=="Trois"
     with pytest.raises(ValueError):
         bl.hlookup(4)
+    assert bl.hlookup(4,default='x')=='x'
     with pytest.raises(ValueError):
         bl.hlookup(1, row1=4)
     with pytest.raises(ValueError):
@@ -144,51 +147,52 @@ def test_hlookup():
 def test_capture(capsys):
     print("abc")
     print("def")
+    capture=xwu.Capture()
     out, err = capsys.readouterr()
     assert out == "abc\ndef\n"
-    assert xwu.capture.str_keep == ""
-    assert xwu.capture.value_keep == []
+    assert capture.str_keep == ""
+    assert capture.value_keep == []
 
-    with xwu.capture:
+    with capture:
         print("abc")
         print("def")
     out, err = capsys.readouterr()
     assert out == ""
-    assert xwu.capture.str_keep == "abc\ndef\n"
-    assert xwu.capture.value_keep == [['abc'], ['def']]
-    assert xwu.capture.str == "abc\ndef\n"
-    assert xwu.capture.value == []
+    assert capture.str_keep == "abc\ndef\n"
+    assert capture.value_keep == [['abc'], ['def']]
+    assert capture.str == "abc\ndef\n"
+    assert capture.value == []
         
-    with xwu.capture:
+    with capture:
         print("abc")
         print("def")
     out, err = capsys.readouterr()
-    xwu.capture.clear()
-    assert xwu.capture.str_keep == ""
+    capture.clear()
+    assert capture.str_keep == ""
 
-    with xwu.capture:
+    with capture:
         print("abc")
         print("def")
-    with xwu.capture:
+    with capture:
         print("ghi")
         print("jkl")        
     out, err = capsys.readouterr()
     assert out == ""
-    assert xwu.capture.str_keep == "abc\ndef\nghi\njkl\n"        
-    assert xwu.capture.value_keep == [['abc'], ['def'], ['ghi'], ['jkl']]
-    assert xwu.capture.value == [['abc'], ['def'], ['ghi'], ['jkl']]    
-    assert xwu.capture.value == []
+    assert capture.str_keep == "abc\ndef\nghi\njkl\n"        
+    assert capture.value_keep == [['abc'], ['def'], ['ghi'], ['jkl']]
+    assert capture.value == [['abc'], ['def'], ['ghi'], ['jkl']]    
+    assert capture.value == []
     
-    xwu.capture.enabled=True
+    capture.enabled=True
     print("abc")
     print("def")    
-    xwu.capture.enabled=False
+    capture.enabled=False
     print("xxx")
     print("yyy")          
-    xwu.capture.enabled=True
+    capture.enabled=True
     print("ghi")
     print("jkl")        
-    assert xwu.capture.str_keep == "abc\ndef\nghi\njkl\n"      
+    assert capture.str_keep == "abc\ndef\nghi\njkl\n"      
 
     
         # include_print is not testable with pytest

{xlwings_utils-25.0.2 → xlwings_utils-25.0.3.post0}/xlwings_utils/xlwings_utils.py

@@ -5,7 +5,7 @@
 #  /_/\_\|_|  \_/\_/  |_||_| |_| \__, ||___/ _____  \__,_| \__||_||_||___/
 #                                |___/      |_____|
 
-__version__ = "25.0.2"
+__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, max_retries_on_error=4):
     """
     dropbox initialize
 
@@ -66,23 +70,23 @@ 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:
             raise ValueError("no APP_SECRET found in environment.")
 
-    dbx = dropbox.Dropbox(oauth2_refresh_token=refresh_token, app_key=app_key, app_secret=app_secret)
+    dbx = dropbox.Dropbox(oauth2_refresh_token=refresh_token, app_key=app_key, app_secret=app_secret, max_retries_on_error=max_retries_on_error)
     try:
         dbx.files_list_folder(path="")  # just to test proper credentials
     except dropbox.exceptions.AuthError:
@@ -169,19 +173,18 @@ 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 filesize does not match the metadata, as sometimes happens on pyodide, an IOError exception will be raised.
+
+    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('filesize does not match metadata')
+        raise OSError(f"file size ({len(file_content)}) does not match metadata ({metadata.size})")
     return file_content
 
 
-    
 def write_dropbox(dropbox_path, contents):
     _login_dbx()
     """
@@ -277,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
@@ -292,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)
 
@@ -425,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)
 
@@ -454,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
 
@@ -495,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")
@@ -512,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)
 
@@ -543,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
 
@@ -584,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")
@@ -601,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)
 
@@ -632,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:
@@ -653,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
 
@@ -663,10 +697,9 @@ class Capture:
 
     Note
     ----
-    Use this function, like ::
+    Use this like ::
 
-        capture = xwu.Capture():
-            ...
+        capture = xwu.Capture()
     """
 
     _instance = None
@@ -677,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
 
@@ -755,4 +788,3 @@ class Capture:
 
 if __name__ == "__main__":
     ...
-

{xlwings_utils-25.0.2 → xlwings_utils-25.0.3.post0}/xlwings_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.2
+Version: 25.0.3.post0
 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.