xlwings-utils 25.0.0.post1__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
@@ -385,6 +403,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 +446,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,13 +492,83 @@ class block:
         raise ValueError(f"{s} not found")
 
     def hlookup(self, s, *, column_from=1, column_to=None, row1=1, row2=None):
-        if row2 is 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")
@@ -423,6 +581,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)
 
 

{xlwings_utils-25.0.0.post1.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.post1
+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.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,,