xlwings-utils 25.0.0.post2__tar.gz → 25.0.0.post4__tar.gz

{xlwings_utils-25.0.0.post2 → xlwings_utils-25.0.0.post4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.0.post2
+Version: 25.0.0.post4
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -30,6 +30,16 @@ In the script, add
 >
 > The GitHub repository can be found on https://github.com/salabim/xlwings_utils .
 
+General
+
+It is recommended to put
+
+```
+import xlwings_utils as xwu
+```
+
+at the top of a xlwings lite script.
+
 ## 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.
@@ -50,15 +60,15 @@ The functions `list_local`, `read_local` and `write_local` offer similar functio
 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')
+contents = xwu.read_dropbox('/downloads/file1.xls')
+xwu.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')
+contents = xwu.read_local('file1.gif')
+xwu.write_dropbox('/downloads/file1.gif')
 ```
 
 ## Block support
@@ -89,7 +99,7 @@ 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)
+block = xwu.block(number_of_rows, number_columns)
 ```
 The dimensions can be queried or redefined with `block.number_of_rows` and 
 `block.number_of_columns`.
@@ -119,53 +129,71 @@ sheet.range(10,1).value = this_block.minimized().value
 
 In this case, only the really processed rows are copied to the sheet.
 
-With blocks, it is easy to use a sheet as an input for a project / scenario.
+###  Looking up in a block
 
-Like, something like
+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 have to be updated.
+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.
 
-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.
 
-Let's see how this works with the above sheet. The block (bl) looks like
+Let's see how this works with the above sheet. The corresponding block (bl) looks like
 
 ```
   |   1                2                3                4                5
 --+-------------------------------------------------------------------------------     
 1 |   Project          Factory1
-2 |   Name             Mega1
-3 |   Start date       2025-05-17
-4 |   End date         2026-02-01
-5 | 
-6 |   Parts            Width            Length           Height           Weight
-7 |   A                10               5                5                100
-8 |   B                11               5                8                102
-9 |   C                12               2                3                91        
-10|   
-
+2 |   Start date       2025-05-17
+3 |   End date         2026-02-01
+4 | 
+5 |   Parts            Width            Length           Height           Weight
+6 |   A                10               5                5                100
+7 |   B                11               5                8                102
+8 |   C                12               2                3                91     
+9 | 
+```
 Now we can do
-project  = bl.lookup("Project")
-name = bl.lookup("Start date")
+```project  = bl.lookup("Project")
+project = bl.lookup("Project")
 start_date = bl.lookup("Start date")
 end_date = bl.lookup("End date")
 row1 = bl.lookup_row("Parts")
 parts=[]
 for row2 in range(row1 + 1, bl.highest_used_row_number + 1):
     if not (part_name := bl.hlookup("Part",row1=row1, row2=row2)):
-        # stop when reach a 'blank' part_name
+        # stop when a 'blank' part_name is found
         break
     width = bl.hlookup("Width",row1=row1, row2=row2)
     length = bl.hlookup("Length",row1=row1, row2=row2)  
     height = bl.hlookup("HeightL",row1=row1, row2=row2)  
     weight = bl.hlookup("Weight",row1=row1, row2=row2)         
     parts.append(Part(part_name, width, length, height, weight))
-       
-You see lookup, which is vertical lookup, which just scans column 1 for the given label and then returns the corresponding value from column 2.
+```
+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.
+
+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.
+
+### 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.
+
+It is possible to make a block from a 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 an openpyxl worksheet with `block.from_openpyxl_sheet`. 
+
+### Writing a block to an openpyxl sheet
 
-Then, there's lookup_row, which also scans column1 for the given label (Parts), but returns the corresponding row (6). Store it in row1.
-And then we just read the following rows (with hlookup) and access the required values.
+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
 
 ## Capture stdout support
 
@@ -173,30 +201,53 @@ The module has support for capturing stdout and -later- using showing the captur
 
 This is rather important as printing in xlwings lite to the UI pane is rather slow.
 
-In order to capture stdout output, use
+In order to capture stdout output, it is required to first issue
 
+```caoture
+capture = xwu.Capture()
+```
 
+By this, capture is automatically enabled and print is disabled. Alternatively, it is possible to use
+
+```
+capture = xwu.Capture(enabled=False)
+```
+
+to disable the capture. And with
+
+```
+capture = xwu.Capture(include_print=True)
 ```
-with xwu.capture:
+
+the stdout output is captured and printed.
+
+Capturing van be enabled and disabled at any time with `capture.enbaled = True` and `capture.enabled = False`.
+
+And including print likewise with `capture.include_print`.
+
+Alternatively, a context manager is provided:
+
+
+```
+with capture:
     """
     code with print statements
     """
 ```
+Note that stopping the capture, leaves the captured output in place, so it can be extended later.
 
-and then the captured output can be copied to a sheet, like
+In either case, the captured output can be then copied to a sheet, like
 
 ```
-sheet.range(4,5).value = xwu.capture.value
+sheet.range(4,5).value = capture.value
 ```
 Upon reading the value, the capture buffer will be emptied.
 
-If you don't want the buffer to be emptied after accessing the value, use `xwu.capture.value_keep`.
-
-The capture buffer can also be retrieved as a string with `xwu.capture.str` and `xwu.capture.str_keep`.
+If you don't want the buffer to be emptied after accessing the value, use `capture.value_keep`.
 
-Clearing the captured stdout buffer can be done at any time with `xwu.capture.clear()`.
+The capture buffer can also be retrieved as a string with `capture.str` and `capture.str_keep`.
 
-Normally, stdout will not be sent to the xlwings lite UI panel when captured with the `xwu.capture` context manager. However, if you specify `xwu.capture.include_print = True`, the output will be sent to the UI panel as well. Note that this setting remains active until a `xwu.capture.include_print = False` is issued.
+Clearing the captured stdout buffer can be done at any time with `capture.clear()`.
 
 
 ## Contact info

{xlwings_utils-25.0.0.post2 → xlwings_utils-25.0.0.post4}/README.md

@@ -16,6 +16,16 @@ In the script, add
 >
 > The GitHub repository can be found on https://github.com/salabim/xlwings_utils .
 
+General
+
+It is recommended to put
+
+```
+import xlwings_utils as xwu
+```
+
+at the top of a xlwings lite script.
+
 ## 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.
@@ -36,15 +46,15 @@ The functions `list_local`, `read_local` and `write_local` offer similar functio
 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')
+contents = xwu.read_dropbox('/downloads/file1.xls')
+xwu.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')
+contents = xwu.read_local('file1.gif')
+xwu.write_dropbox('/downloads/file1.gif')
 ```
 
 ## Block support
@@ -75,7 +85,7 @@ 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)
+block = xwu.block(number_of_rows, number_columns)
 ```
 The dimensions can be queried or redefined with `block.number_of_rows` and 
 `block.number_of_columns`.
@@ -105,53 +115,71 @@ sheet.range(10,1).value = this_block.minimized().value
 
 In this case, only the really processed rows are copied to the sheet.
 
-With blocks, it is easy to use a sheet as an input for a project / scenario.
+###  Looking up in a block
 
-Like, something like
+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 have to be updated.
+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.
 
-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.
 
-Let's see how this works with the above sheet. The block (bl) looks like
+Let's see how this works with the above sheet. The corresponding block (bl) looks like
 
 ```
   |   1                2                3                4                5
 --+-------------------------------------------------------------------------------     
 1 |   Project          Factory1
-2 |   Name             Mega1
-3 |   Start date       2025-05-17
-4 |   End date         2026-02-01
-5 | 
-6 |   Parts            Width            Length           Height           Weight
-7 |   A                10               5                5                100
-8 |   B                11               5                8                102
-9 |   C                12               2                3                91        
-10|   
-
+2 |   Start date       2025-05-17
+3 |   End date         2026-02-01
+4 | 
+5 |   Parts            Width            Length           Height           Weight
+6 |   A                10               5                5                100
+7 |   B                11               5                8                102
+8 |   C                12               2                3                91     
+9 | 
+```
 Now we can do
-project  = bl.lookup("Project")
-name = bl.lookup("Start date")
+```project  = bl.lookup("Project")
+project = bl.lookup("Project")
 start_date = bl.lookup("Start date")
 end_date = bl.lookup("End date")
 row1 = bl.lookup_row("Parts")
 parts=[]
 for row2 in range(row1 + 1, bl.highest_used_row_number + 1):
     if not (part_name := bl.hlookup("Part",row1=row1, row2=row2)):
-        # stop when reach a 'blank' part_name
+        # stop when a 'blank' part_name is found
         break
     width = bl.hlookup("Width",row1=row1, row2=row2)
     length = bl.hlookup("Length",row1=row1, row2=row2)  
     height = bl.hlookup("HeightL",row1=row1, row2=row2)  
     weight = bl.hlookup("Weight",row1=row1, row2=row2)         
     parts.append(Part(part_name, width, length, height, weight))
-       
-You see lookup, which is vertical lookup, which just scans column 1 for the given label and then returns the corresponding value from column 2.
+```
+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.
+
+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.
+
+### 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.
+
+It is possible to make a block from a 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 an openpyxl worksheet with `block.from_openpyxl_sheet`. 
+
+### Writing a block to an openpyxl sheet
 
-Then, there's lookup_row, which also scans column1 for the given label (Parts), but returns the corresponding row (6). Store it in row1.
-And then we just read the following rows (with hlookup) and access the required values.
+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
 
 ## Capture stdout support
 
@@ -159,30 +187,53 @@ The module has support for capturing stdout and -later- using showing the captur
 
 This is rather important as printing in xlwings lite to the UI pane is rather slow.
 
-In order to capture stdout output, use
+In order to capture stdout output, it is required to first issue
 
+```caoture
+capture = xwu.Capture()
+```
 
+By this, capture is automatically enabled and print is disabled. Alternatively, it is possible to use
+
+```
+capture = xwu.Capture(enabled=False)
+```
+
+to disable the capture. And with
+
+```
+capture = xwu.Capture(include_print=True)
 ```
-with xwu.capture:
+
+the stdout output is captured and printed.
+
+Capturing van be enabled and disabled at any time with `capture.enbaled = True` and `capture.enabled = False`.
+
+And including print likewise with `capture.include_print`.
+
+Alternatively, a context manager is provided:
+
+
+```
+with capture:
     """
     code with print statements
     """
 ```
+Note that stopping the capture, leaves the captured output in place, so it can be extended later.
 
-and then the captured output can be copied to a sheet, like
+In either case, the captured output can be then copied to a sheet, like
 
 ```
-sheet.range(4,5).value = xwu.capture.value
+sheet.range(4,5).value = capture.value
 ```
 Upon reading the value, the capture buffer will be emptied.
 
-If you don't want the buffer to be emptied after accessing the value, use `xwu.capture.value_keep`.
-
-The capture buffer can also be retrieved as a string with `xwu.capture.str` and `xwu.capture.str_keep`.
+If you don't want the buffer to be emptied after accessing the value, use `capture.value_keep`.
 
-Clearing the captured stdout buffer can be done at any time with `xwu.capture.clear()`.
+The capture buffer can also be retrieved as a string with `capture.str` and `capture.str_keep`.
 
-Normally, stdout will not be sent to the xlwings lite UI panel when captured with the `xwu.capture` context manager. However, if you specify `xwu.capture.include_print = True`, the output will be sent to the UI panel as well. Note that this setting remains active until a `xwu.capture.include_print = False` is issued.
+Clearing the captured stdout buffer can be done at any time with `capture.clear()`.
 
 
 ## Contact info

{xlwings_utils-25.0.0.post2 → xlwings_utils-25.0.0.post4}/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.0.post2"
+version = "25.0.0.post4"
 readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [

{xlwings_utils-25.0.0.post2 → xlwings_utils-25.0.0.post4}/tests/test_xlwings_utils.py

@@ -178,8 +178,20 @@ def test_capture(capsys):
     assert xwu.capture.value_keep == [['abc'], ['def'], ['ghi'], ['jkl']]
     assert xwu.capture.value == [['abc'], ['def'], ['ghi'], ['jkl']]    
     assert xwu.capture.value == []
- 
-    # include_print is not testable with pytest
+    
+    xwu.capture.enabled=True
+    print("abc")
+    print("def")    
+    xwu.capture.enabled=False
+    print("xxx")
+    print("yyy")          
+    xwu.capture.enabled=True
+    print("ghi")
+    print("jkl")        
+    assert xwu.capture.str_keep == "abc\ndef\nghi\njkl\n"      
+
+    
+        # include_print is not testable with pytest
     
 if __name__ == "__main__":
     pytest.main(["-vv", "-s", "-x", __file__])

{xlwings_utils-25.0.0.post2 → xlwings_utils-25.0.0.post4}/xlwings_utils/xlwings_utils.py

@@ -289,16 +289,30 @@ class block:
                 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=None, number_of_columns=None):
         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):
+        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):
+        with open(filename, "r") as f:
+            v = [[line if line else None] 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):
-        v=df.values.tolist()
+    def from_dataframe(cls, df, number_of_rows=None, number_of_columns=None):
+        v = df.values.tolist()
         return cls(v, number_of_rows=number_of_rows, number_of_columns=number_of_columns)
 
+    def to_openpyxl_sheet(self, sheet):
+        for row in self.value:
+            sheet.append(row)
+
     @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)]
@@ -318,7 +332,7 @@ class block:
 
         for row, row_contents in enumerate(value, 1):
             for column, item in enumerate(row_contents, 1):
-                if item and not (isinstance(item,float) and math.isnan(item)):
+                if item and not (isinstance(item, float) and math.isnan(item)):
                     self.dict[row, column] = item
                     self._number_of_columns = max(self.number_of_columns, column)
 
@@ -405,36 +419,36 @@ class block:
     def vlookup(self, s, *, row_from=1, row_to=None, column1=1, column2=None):
         """
         searches in column1 for row between row_from and row_to for s and returns the value found at (that row, column2)
-        
+
         Parameters
         ----------
         s : any
             value to seach for
-            
+
         row_from : int
              row to start search (default 1)
-             
+
              should be between 1 and number_of_rows
-     
+
         row_to : int
              row to end search (default number_of_rows)
-             
-             should be between 1 and number_of_rows         
-             
+
+             should be between 1 and number_of_rows
+
         column1 : int
              column to search in (default 1)
-             
+
              should be between 1 and number_of_columns
-             
+
         column2 : int
              column to return looked up value from (default column1 + 1)
-             
-             should be between 1 and number_of_columns             
-             
+
+             should be between 1 and number_of_columns
+
         Returns
         -------
         block[found row number, column2] : any
-        
+
         Note
         ----
         If s is not found, a ValueError is raised
@@ -448,34 +462,34 @@ class block:
     def lookup_row(self, s, *, row_from=1, row_to=None, column1=1):
         """
         searches in column1 for row between row_from and row_to for s and returns that row number
-        
+
         Parameters
         ----------
         s : any
             value to seach for
-            
+
         row_from : int
              row to start search (default 1)
-             
+
              should be between 1 and number_of_rows
-     
+
         row_to : int
              row to end search (default number_of_rows)
-             
-             should be between 1 and number_of_rows         
-             
+
+             should be between 1 and number_of_rows
+
         column1 : int
              column to search in (default 1)
-             
+
              should be between 1 and number_of_columns
-             
+
         column2 : int
              column to return looked up value from (default column1 + 1)
-             
+
         Returns
         -------
-        row number where block[row nunber, column1] == s : int  
-             
+        row number where block[row nunber, column1] == s : int
+
         Note
         ----
         If s is not found, a ValueError is raised
@@ -494,41 +508,41 @@ class block:
     def hlookup(self, s, *, column_from=1, column_to=None, row1=1, row2=None):
         """
         searches in row1 for column between column_from and column_to for s and returns the value found at (that column, row2)
-        
+
         Parameters
         ----------
         s : any
             value to seach for
-            
+
         column_from : int
              column to start search (default 1)
-             
+
              should be between 1 and number_of_columns
-     
+
         column_to : int
              column to end search (default number_of_columns)
-             
-             should be between 1 and number_of_columns         
-             
+
+             should be between 1 and number_of_columns
+
         row1 : int
              row to search in (default 1)
-             
+
              should be between 1 and number_of_rows
-             
+
         row2 : int
              row to return looked up value from (default row1 + 1)
-             
-             should be between 1 and number_of_rows             
-             
+
+             should be between 1 and number_of_rows
+
         Returns
         -------
         block[row, found column, row2] : any
-        
+
         Note
         ----
         If s is not found, a ValueError is raised
         """
-        if column2 is None:
+        if row2 is None:
             row2 = row1 + 1
         self._check_row(row2, "row2")
         column = self.lookup_column(s, column_from=column_from, column_to=column_to, row1=row1)
@@ -537,34 +551,34 @@ class block:
     def lookup_column(self, s, *, column_from=1, column_to=None, row1=1):
         """
         searches in row1 for column between column_from and column_to for s and returns that column number
-        
+
         Parameters
         ----------
         s : any
             value to seach for
-            
+
         column_from : int
              column to start search (default 1)
-             
+
              should be between 1 and number_of_columns
-     
+
         column_to : int
              column to end search (default number_of_columns)
-             
-             should be between 1 and number_of_columns         
-             
+
+             should be between 1 and number_of_columns
+
         row1 : int
              row to search in (default 1)
-             
+
              should be between 1 and number_of_rows
-             
+
         row2 : int
              row to return looked up value from (default row1 + 1)
-             
+
         Returns
         -------
-        column number where block[row1, column number] == s : int  
-             
+        column number where block[row1, column number] == s : int
+
         Note
         ----
         If s is not found, a ValueError is raised
@@ -583,46 +597,46 @@ class block:
     def lookup(self, s, *, row_from=1, row_to=None, column1=1, column2=None):
         """
         searches in column1 for row between row_from and row_to for s and returns the value found at (that row, column2)
-        
+
         Parameters
         ----------
         s : any
             value to seach for
-            
+
         row_from : int
              row to start search (default 1)
-             
+
              should be between 1 and number_of_rows
-     
+
         row_to : int
              row to end search (default number_of_rows)
-             
-             should be between 1 and number_of_rows         
-             
+
+             should be between 1 and number_of_rows
+
         column1 : int
              column to search in (default 1)
-             
+
              should be between 1 and number_of_columns
-             
+
         column2 : int
              column to return looked up value from (default column1 + 1)
-             
-             should be between 1 and number_of_columns             
-             
+
+             should be between 1 and number_of_columns
+
         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)
 
 
-class _capture:
+class Capture:
     """
     specifies how to capture stdout
 
@@ -647,10 +661,10 @@ class _capture:
         self._buffer = []
 
     def __enter__(self):
-        sys.stdout = self
+        self.enabled = True
 
     def __exit__(self, exc_type, exc_value, tb):
-        sys.stdout = self.stdout
+        self.enabled = False
 
     def write(self, data):
         self._buffer.append(data)
@@ -662,6 +676,17 @@ class _capture:
             self.stdout.flush()
         self._buffer.append("\n")
 
+    @property
+    def enabled(self):
+        return sys.out == self
+
+    @enabled.setter
+    def enabled(self, value):
+        if value:
+            sys.stdout = self
+        else:
+            sys.stdout = self.stdout
+
     @property
     def value(self):
         result = self.value_keep
@@ -696,13 +721,6 @@ class _capture:
         self._include_print = value
 
 
-def reset():
-    capture.include_print = False
-    capture.clear()
-
-
-capture = _capture()
-
-
 if __name__ == "__main__":
     ...
+

{xlwings_utils-25.0.0.post2 → xlwings_utils-25.0.0.post4}/xlwings_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.0.post2
+Version: 25.0.0.post4
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -30,6 +30,16 @@ In the script, add
 >
 > The GitHub repository can be found on https://github.com/salabim/xlwings_utils .
 
+General
+
+It is recommended to put
+
+```
+import xlwings_utils as xwu
+```
+
+at the top of a xlwings lite script.
+
 ## 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.
@@ -50,15 +60,15 @@ The functions `list_local`, `read_local` and `write_local` offer similar functio
 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')
+contents = xwu.read_dropbox('/downloads/file1.xls')
+xwu.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')
+contents = xwu.read_local('file1.gif')
+xwu.write_dropbox('/downloads/file1.gif')
 ```
 
 ## Block support
@@ -89,7 +99,7 @@ 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)
+block = xwu.block(number_of_rows, number_columns)
 ```
 The dimensions can be queried or redefined with `block.number_of_rows` and 
 `block.number_of_columns`.
@@ -119,53 +129,71 @@ sheet.range(10,1).value = this_block.minimized().value
 
 In this case, only the really processed rows are copied to the sheet.
 
-With blocks, it is easy to use a sheet as an input for a project / scenario.
+###  Looking up in a block
 
-Like, something like
+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 have to be updated.
+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.
 
-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.
 
-Let's see how this works with the above sheet. The block (bl) looks like
+Let's see how this works with the above sheet. The corresponding block (bl) looks like
 
 ```
   |   1                2                3                4                5
 --+-------------------------------------------------------------------------------     
 1 |   Project          Factory1
-2 |   Name             Mega1
-3 |   Start date       2025-05-17
-4 |   End date         2026-02-01
-5 | 
-6 |   Parts            Width            Length           Height           Weight
-7 |   A                10               5                5                100
-8 |   B                11               5                8                102
-9 |   C                12               2                3                91        
-10|   
-
+2 |   Start date       2025-05-17
+3 |   End date         2026-02-01
+4 | 
+5 |   Parts            Width            Length           Height           Weight
+6 |   A                10               5                5                100
+7 |   B                11               5                8                102
+8 |   C                12               2                3                91     
+9 | 
+```
 Now we can do
-project  = bl.lookup("Project")
-name = bl.lookup("Start date")
+```project  = bl.lookup("Project")
+project = bl.lookup("Project")
 start_date = bl.lookup("Start date")
 end_date = bl.lookup("End date")
 row1 = bl.lookup_row("Parts")
 parts=[]
 for row2 in range(row1 + 1, bl.highest_used_row_number + 1):
     if not (part_name := bl.hlookup("Part",row1=row1, row2=row2)):
-        # stop when reach a 'blank' part_name
+        # stop when a 'blank' part_name is found
         break
     width = bl.hlookup("Width",row1=row1, row2=row2)
     length = bl.hlookup("Length",row1=row1, row2=row2)  
     height = bl.hlookup("HeightL",row1=row1, row2=row2)  
     weight = bl.hlookup("Weight",row1=row1, row2=row2)         
     parts.append(Part(part_name, width, length, height, weight))
-       
-You see lookup, which is vertical lookup, which just scans column 1 for the given label and then returns the corresponding value from column 2.
+```
+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.
+
+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.
+
+### 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.
+
+It is possible to make a block from a 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 an openpyxl worksheet with `block.from_openpyxl_sheet`. 
+
+### Writing a block to an openpyxl sheet
 
-Then, there's lookup_row, which also scans column1 for the given label (Parts), but returns the corresponding row (6). Store it in row1.
-And then we just read the following rows (with hlookup) and access the required values.
+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
 
 ## Capture stdout support
 
@@ -173,30 +201,53 @@ The module has support for capturing stdout and -later- using showing the captur
 
 This is rather important as printing in xlwings lite to the UI pane is rather slow.
 
-In order to capture stdout output, use
+In order to capture stdout output, it is required to first issue
 
+```caoture
+capture = xwu.Capture()
+```
 
+By this, capture is automatically enabled and print is disabled. Alternatively, it is possible to use
+
+```
+capture = xwu.Capture(enabled=False)
+```
+
+to disable the capture. And with
+
+```
+capture = xwu.Capture(include_print=True)
 ```
-with xwu.capture:
+
+the stdout output is captured and printed.
+
+Capturing van be enabled and disabled at any time with `capture.enbaled = True` and `capture.enabled = False`.
+
+And including print likewise with `capture.include_print`.
+
+Alternatively, a context manager is provided:
+
+
+```
+with capture:
     """
     code with print statements
     """
 ```
+Note that stopping the capture, leaves the captured output in place, so it can be extended later.
 
-and then the captured output can be copied to a sheet, like
+In either case, the captured output can be then copied to a sheet, like
 
 ```
-sheet.range(4,5).value = xwu.capture.value
+sheet.range(4,5).value = capture.value
 ```
 Upon reading the value, the capture buffer will be emptied.
 
-If you don't want the buffer to be emptied after accessing the value, use `xwu.capture.value_keep`.
-
-The capture buffer can also be retrieved as a string with `xwu.capture.str` and `xwu.capture.str_keep`.
+If you don't want the buffer to be emptied after accessing the value, use `capture.value_keep`.
 
-Clearing the captured stdout buffer can be done at any time with `xwu.capture.clear()`.
+The capture buffer can also be retrieved as a string with `capture.str` and `capture.str_keep`.
 
-Normally, stdout will not be sent to the xlwings lite UI panel when captured with the `xwu.capture` context manager. However, if you specify `xwu.capture.include_print = True`, the output will be sent to the UI panel as well. Note that this setting remains active until a `xwu.capture.include_print = False` is issued.
+Clearing the captured stdout buffer can be done at any time with `capture.clear()`.
 
 
 ## Contact info