xlwings-utils 25.0.0__py3-none-any.whl → 25.0.0.post2__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,17 @@ 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_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)
+
     @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 +318,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 +339,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
@@ -372,6 +390,236 @@ class block:
     def __repr__(self):
         return f"block({self.value})"
 
+    def _check_row(self, row, name):
+        if row < 1:
+            raise ValueError(f"{name}={row} < 1")
+        if row > self.number_of_rows:
+            raise ValueError(f"{name}={row} > number_of_rows={self.number_of_rows}")
+
+    def _check_column(self, column, name):
+        if column < 1:
+            raise ValueError(f"{name}={column} < 1")
+        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):
+        """
+        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")
+        row = self.lookup_row(s, row_from=row_from, row_to=row_to, column1=column1)
+        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")
+        self._check_row(row_to, "row_to")
+        self._check_column(column1, "column1")
+
+        for row in range(row_from, row_to + 1):
+            if self[row, column1] == s:
+                return row
+        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 column2 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)
+        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")
+        self._check_column(column_to, "column_to")
+        self._check_row(row1, "row1")
+
+        for column in range(column_from, column_to + 1):
+            if self[row1, column] == s:
+                return column
+        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)
 
 
 class _capture:
@@ -396,7 +644,7 @@ class _capture:
     def __init__(self):
         self.stdout = sys.stdout
         self._include_print = False
-        self._buffer=[]
+        self._buffer = []
 
     def __enter__(self):
         sys.stdout = self
@@ -413,50 +661,47 @@ class _capture:
         if self._include_print:
             self.stdout.flush()
         self._buffer.append("\n")
-        
 
     @property
     def value(self):
-        result=self.value_keep
+        result = self.value_keep
         self.clear()
         return result
-        
-        
+
     @property
     def value_keep(self):
-        result= [[line] for line in self.str_keep.splitlines()]
+        result = [[line] for line in self.str_keep.splitlines()]
         return result
-        
+
     @property
     def str(self):
         result = self.str_keep
         self._buffer.clear()
-        return result        
-        
+        return result
+
     @property
     def str_keep(self):
         result = "".join(self._buffer)
-        return result        
-        
+        return result
+
     def clear(self):
         self._buffer.clear()
-        
-        
+
     @property
     def include_print(self):
         return self._include_print
-        
+
     @include_print.setter
     def include_print(self, value):
-        self._include_print=value
-        
+        self._include_print = value
 
 
 def reset():
-    capture.include_print=False
+    capture.include_print = False
     capture.clear()
-    
-capture=_capture()
+
+
+capture = _capture()
 
 
 if __name__ == "__main__":

{xlwings_utils-25.0.0.dist-info → xlwings_utils-25.0.0.post2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.0
+Version: 25.0.0.post2
 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,6 +119,54 @@ 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.
+
+Like, something like
+
+
+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.
+
+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
+
+```
+  |   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|   
+
+Now we can do
+project  = bl.lookup("Project")
+name = bl.lookup("Start date")
+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
+        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.
+
+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.
+
 ## Capture stdout support
 
 The module has support for capturing stdout and -later- using showing the captured output on a sheet.

xlwings_utils-25.0.0.post2.dist-info/RECORD

@@ -0,0 +1,6 @@
+xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
+xlwings_utils/xlwings_utils.py,sha256=bqy2SkFBf2GvHPLcXu1YpyLESiIHkT3rpSemruy5twc,20792
+xlwings_utils-25.0.0.post2.dist-info/METADATA,sha256=PJyv0aEsxLn5v3V8kVtriKjl_2tjwjXXNogHjKNEMt8,8358
+xlwings_utils-25.0.0.post2.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
+xlwings_utils-25.0.0.post2.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
+xlwings_utils-25.0.0.post2.dist-info/RECORD,,

xlwings_utils-25.0.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
-xlwings_utils/xlwings_utils.py,sha256=NX8bnrKeG3znlI78F4nN0rMQoL-SCXHMIlIHyxxyMlY,12732
-xlwings_utils-25.0.0.dist-info/METADATA,sha256=p4CcbZ-Ju0_F1vvr1ES_ZOhrCrDR1veBXNol4LH9ktE,6160
-xlwings_utils-25.0.0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-xlwings_utils-25.0.0.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
-xlwings_utils-25.0.0.dist-info/RECORD,,