xlwings-utils 25.0.0.post1__py3-none-any.whl → 25.0.0.post3__py3-none-any.whl

xlwings_utils/xlwings_utils.py

@@ -12,6 +12,7 @@ import dropbox
 from pathlib import Path
 import os
 import sys
+import math
 
 dbx = None
 Pythonista = sys.platform == "ios"
@@ -287,6 +288,31 @@ class block:
             if number_of_columns is not None:
                 self.number_of_columns = number_of_columns
 
+    @classmethod
+    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()
+        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)]
@@ -306,7 +332,7 @@ class block:
 
         for row, row_contents in enumerate(value, 1):
             for column, item in enumerate(row_contents, 1):
-                if item is not None:
+                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)
 
@@ -327,6 +353,12 @@ class block:
         return self.dict.get((row, column))
 
     def minimized(self):
+        """
+        Returns
+        -------
+        minimized block : block
+             uses highest_used_row_number and highest_used_column_number to minimize the block
+        """
         return block(self, number_of_rows=self.highest_used_row_number, number_of_columns=self.highest_used_column_number)
 
     @property
@@ -385,6 +417,42 @@ class block:
             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):
+        """
+        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
+
+        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
+
+        Returns
+        -------
+        block[found row number, column2] : any
+
+        Note
+        ----
+        If s is not found, a ValueError is raised
+        """
         if column2 is None:
             column2 = column1 + 1
         self._check_column(column2, "column2")
@@ -392,6 +460,40 @@ class block:
         return self[row, column2]
 
     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
+
+        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
+
+        Note
+        ----
+        If s is not found, a ValueError is raised
+        """
         if row_to is None:
             row_to = self.highest_used_row_number
         self._check_row(row_from, "row_from")
@@ -404,6 +506,42 @@ class block:
         raise ValueError(f"{s} not found")
 
     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
+
+        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
+
+        Returns
+        -------
+        block[row, found column, row2] : any
+
+        Note
+        ----
+        If s is not found, a ValueError is raised
+        """
         if row2 is None:
             row2 = row1 + 1
         self._check_row(row2, "row2")
@@ -411,6 +549,40 @@ class block:
         return self[row2, column]
 
     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
+
+        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
+
+        Note
+        ----
+        If s is not found, a ValueError is raised
+        """
         if column_to is None:
             column_to = self.highest_used_column_number
         self._check_column(column_from, "column_from")
@@ -423,6 +595,44 @@ class block:
         raise ValueError(f"{s} not found")
 
     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
+
+        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
+
+        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)
 
 
@@ -451,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)
@@ -466,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
@@ -501,12 +722,14 @@ class _capture:
 
 
 def reset():
+    capture.enabled = False
     capture.include_print = False
     capture.clear()
-
+    print('reset',sys.stdout)
 
 capture = _capture()
 
 
 if __name__ == "__main__":
     ...
+

{xlwings_utils-25.0.0.post1.dist-info → xlwings_utils-25.0.0.post3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.0.post1
+Version: 25.0.0.post3
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -119,13 +119,80 @@ sheet.range(10,1).value = this_block.minimized().value
 
 In this case, only the really processed rows are copied to the sheet.
 
+###  Looking up in a block
+
+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.
+
+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 corresponding block (bl) looks like
+
+```
+  |   1                2                3                4                5
+--+-------------------------------------------------------------------------------     
+1 |   Project          Factory1
+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")
+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 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))
+```
+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
+
+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
 
 The module has support for capturing stdout and -later- using showing the captured output on a sheet.
 
 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, use `xwu.capture.enabled = True`. And to stop capturing, use `xwu.capture.enabled = False`.
+Alternatively, a context manager is provided:
 
 
 ```
@@ -134,8 +201,9 @@ with xwu.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

xlwings_utils-25.0.0.post3.dist-info/RECORD

@@ -0,0 +1,6 @@
+xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
+xlwings_utils/xlwings_utils.py,sha256=o1iCbb5BmXDeVelksKNTJrSkGZ7e0y-iwnYlITKr3dQ,21039
+xlwings_utils-25.0.0.post3.dist-info/METADATA,sha256=Mwx61halKRiHZAvXI5eoSrLiV5lqUCwKVkZu-tZ3P5E,9537
+xlwings_utils-25.0.0.post3.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+xlwings_utils-25.0.0.post3.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
+xlwings_utils-25.0.0.post3.dist-info/RECORD,,

{xlwings_utils-25.0.0.post1.dist-info → xlwings_utils-25.0.0.post3.dist-info}/WHEEL

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

xlwings_utils-25.0.0.post1.dist-info/RECORD

@@ -1,6 +0,0 @@
-xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
-xlwings_utils/xlwings_utils.py,sha256=UQenav-IEe7Hl8IQKNVLYDBscEdmvkR4IQbptsq3Obg,14830
-xlwings_utils-25.0.0.post1.dist-info/METADATA,sha256=Vh86pfRnT_0wuFKqO643CMLViq2YdcqAGoaNx53eEiE,6166
-xlwings_utils-25.0.0.post1.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-xlwings_utils-25.0.0.post1.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
-xlwings_utils-25.0.0.post1.dist-info/RECORD,,