xlwings-utils 25.0.6.post4__py3-none-any.whl → 25.0.7__py3-none-any.whl

xlwings_utils/xlwings_utils.py

@@ -5,7 +5,7 @@
 #  /_/\_\|_|  \_/\_/  |_||_| |_| \__, ||___/ _____  \__,_| \__||_||_||___/
 #                                |___/      |_____|
 
-__version__ = "25.0.6"
+__version__ = "25.0.7"
 
 
 import dropbox
@@ -20,7 +20,6 @@ Pythonista = sys.platform == "ios"
 try:
     import xlwings
 
-    xlwings = True
 except ImportError:
     xlwings = False
 
@@ -276,83 +275,212 @@ class block:
     Parameters
     ----------
     number_of_rows : int
-        number of rows
+        number of rows (dedault 1)
 
     number_of_columns : int
-        number of columns
+        number of columns (default 1)
 
     Returns
     -------
     block
     """
 
-    def __init__(self, value=missing, *, number_of_rows=missing, number_of_columns=missing, column_like=False):
+    def __init__(self, number_of_rows=1, number_of_columns=1):
         self.dict = {}
-        self.column_like = column_like
-        if value is missing:
-            if number_of_rows is missing:
-                number_of_rows = 1
-            if number_of_columns is missing:
-                number_of_columns = 1
-            self.number_of_rows = number_of_rows
-            self.number_of_columns = number_of_columns
+        self.number_of_rows = number_of_rows
+        self.number_of_columns = number_of_columns
 
-        else:
-            if isinstance(value, block):
-                value = value.value
-            self.value = value
-            if number_of_rows is not missing:
-                self.number_of_rows = number_of_rows
-            if number_of_columns is not missing:
-                self.number_of_columns = number_of_columns
+    @classmethod
+    def from_value(cls, value, column_like=False):
+        """
+        makes a block from a given value
+
+        Parameters
+        ----------
+        value : scaler, list of scalars, list of lists of scalars or block
+            value to be used in block, possibly expanded to a list of lists of scalars
+
+        column_like : boolean
+            if value is a list of scalars, values is interpreted as a column if True, as a row otherwise
+
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
+
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
+
+        Returns
+        -------
+        block : block
+        """
+        if isinstance(value, block):
+            value = value.value
+        if not isinstance(value, list):
+            value = [[value]]
+        if not isinstance(value[0], list):
+            if column_like:
+                value = [[item] for item in value]
+            else:
+                value = [value]
+        bl = cls(len(value), 1)
+
+        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)):
+                    bl.dict[row, column] = item
+                    bl._number_of_columns = max(bl.number_of_columns, column)
+        return bl
 
     @classmethod
-    def from_xlrd_sheet(cls, sheet, number_of_rows=missing, number_of_columns=missing):
+    def from_range(cls, rng):
+        """
+        makes a block from a given range
+
+        Parameters
+        ----------
+        rng : xlwings.Range
+            range to be used be used in block
+
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
+
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
+
+        Returns
+        -------
+        block : block
+        """
+        number_of_rows, number_of_columns = rng.shape
+        bl = cls.from_value(rng.value, column_like=(number_of_columns == 1))
+        return bl
+
+    @classmethod
+    def from_xlrd_sheet(cls, sheet):
+        """
+        makes a block from a xlrd sheet
+
+        Parameters
+        ----------
+        sheet : xlrd sheet
+            sheet to be used be used in block
+
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
+
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
+
+        Returns
+        -------
+        block : block
+        """
         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)
+        return cls.from_value(v)
 
     @classmethod
-    def from_openpyxl_sheet(cls, sheet, number_of_rows=missing, number_of_columns=missing):
+    def from_openpyxl_sheet(cls, sheet):
         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)
+        return cls.from_value(v)
 
     @classmethod
-    def from_file(cls, filename, number_of_rows=missing, number_of_columns=missing):
+    def from_file(cls, filename):
+        """
+        makes a block from a file
+
+        Parameters
+        ----------
+        filename : str
+            file to be used be used in block
+
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
+
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
+
+        Returns
+        -------
+        block : block
+        """
         with open(filename, "r") as f:
             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)
+        return cls.from_value(v)
 
     @classmethod
-    def from_dataframe(cls, df, number_of_rows=missing, number_of_columns=missing):
+    def from_dataframe(cls, df):
+        """
+        makes a block from a given dataframe
+
+        Parameters
+        ----------
+        df : pandas dataframe
+            dataframe to be used be used in block
+
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
+
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
+
+        Returns
+        -------
+        block : block
+        """
         v = df.values.tolist()
-        return cls(v, number_of_rows=number_of_rows, number_of_columns=number_of_columns)
+        return cls.from_value(v)
 
     def to_openpyxl_sheet(self, sheet):
+        """
+        makes a block from a given openpyxl sheet
+
+        Parameters
+        ----------
+        sheet: openpyxl sheet
+            sheet to be used be used in block
+
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
+
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
+
+        Returns
+        -------
+        block : block
+        """
         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)]
+    def reshape(self, number_of_rows=missing, number_of_columns=missing):
+        """
+        makes a new block with given dimensions
 
-    @value.setter
-    def value(self, value):
-        if not isinstance(value, list):
-            value = [[value]]
-        if not isinstance(value[0], list):
-            if self.column_like:
-                value = [[item] for item in value]
-            else:
-                value = [value]
+        Parameters
+        ----------
+        number_of_rows : int
+            if given, expand or shrink to the given number of rows
 
-        self.number_of_rows = len(value)
-        self._number_of_columns = 0
+        number_of_columns : int
+            if given, expand or shrink to the given number of columns
 
-        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)):
-                    self.dict[row, column] = item
-                    self._number_of_columns = max(self.number_of_columns, column)
+        Returns
+        -------
+        block : block
+        """
+        if number_of_rows is missing:
+            number_of_rows = self.number_of_rows
+        if number_of_columns is missing:
+            number_of_columns = self.number_of_columns
+        bl = block(number_of_rows=number_of_rows, number_of_columns=number_of_columns)
+        for (row, column), value in self.dict.items():
+            if row <= number_of_columns and column <= number_of_columns:
+                bl.dict[row, column] = value
+        return bl
+
+    @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)]
 
     def __setitem__(self, row_column, value):
         row, column = row_column
@@ -377,7 +505,7 @@ class block:
         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)
+        return self.reshape(number_of_rows=self.highest_used_row_number, number_of_columns=self.highest_used_column_number)
 
     @property
     def number_of_rows(self):

{xlwings_utils-25.0.6.post4.dist-info → xlwings_utils-25.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.6.post4
+Version: 25.0.7
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -87,14 +87,20 @@ xwu.write_dropbox('/downloads/file1.gif')
 The module contains a useful 2-dimensional data structure: *block*.
 This can be useful for manipulating a range without accessing it directly, which is expensive in terms of memory and execution time.
 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]`
+So, `my_block[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` or `block.value_keep`. 
+A block stores the values internally as a dictionary and will only convert these to a list of lists when using `block.value`. 
 
-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
+Converting of a range to a block can be done like
 
 ```
-my_block = xwu.block.from_value(range.value)
+rng = book.sheets.active.range((5,7),(8,100))
+my_block = xwu.block.from_range(rng
+```
+
+A value of a range (list of lists, list of scalars or scalar can be converted to a block with
+```
+my_block = xwu.block.from_value(rng.value)
 ```
 The dimensions (number of rows and number of columns) are automatically set.
 
@@ -115,9 +121,10 @@ 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`.
 
-To assign a block to range, use
+It is also possible to get a copy of a block with different dimensions:
+
 ```
-range.value = block.value
+bl = my.block.reshape(number_of_rows=2, number_of_columns=10)
 ```
 
 The property `block.highest_used_row_number` returns the row number of the highest non-None cell.
@@ -152,7 +159,7 @@ Of course, we could access the various input fields with absolute ranges, but if
 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)
+bl = xwu.block.from_range(sheet.range(1,1),(100,10)))
 ```
 
 Let's see how this works with the above sheet. The corresponding block (bl) looks like
@@ -171,7 +178,8 @@ Let's see how this works with the above sheet. The corresponding block (bl) look
 9 | 
 ```
 Now we can do
-```project  = bl.lookup("Project")
+```
+project  = bl.lookup("Project")
 project = bl.lookup("Project")
 start_date = bl.lookup("Start date")
 end_date = bl.lookup("End date")
@@ -194,11 +202,11 @@ 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 directly is that they are one-based, just like in Excel.
 
 It is possible to make a block from an xlrd worksheet with `block.from_xlrd_sheet`. 
 
-It is possible to create a block from a Pandas DataFrame using `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 create a block from a panda dataFrame using `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`. 
 
@@ -293,7 +301,7 @@ Just add the .bas file to a worksheet and call like
 Sub MacroToExecute()
     DecodeFile(Me, 10, 1)
 ```
-    
+
 In this example, the file *film1.mp4* will be downloaded into the current directory.
 
 The module xlwings_utils also contains code to encode a local file to a sheet:

xlwings_utils-25.0.7.dist-info/RECORD

@@ -0,0 +1,6 @@
+xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
+xlwings_utils/xlwings_utils.py,sha256=e8Lo40ceG0kSzSuytOpIT3cvJ_bhZRxLC2x69EE6k9Y,28725
+xlwings_utils-25.0.7.dist-info/METADATA,sha256=NVLthhuk58Inh4nNVC9Bvue1VEUXuRUYdjJYKlhEqyA,12418
+xlwings_utils-25.0.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xlwings_utils-25.0.7.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
+xlwings_utils-25.0.7.dist-info/RECORD,,

xlwings_utils-25.0.6.post4.dist-info/RECORD

@@ -1,6 +0,0 @@
-xlwings_utils/__init__.py,sha256=FdaRztevSu5akGL7KBUBRzqwLMRTdvVUuS2Kfp2f1Uc,68
-xlwings_utils/xlwings_utils.py,sha256=znZtMTebQuTZ4ZvLITbfDlZCdzba7Avlz9RCLXq5LYk,25788
-xlwings_utils-25.0.6.post4.dist-info/METADATA,sha256=O8dVqUWel4m__6PgnkWLR_08whGUUJGRuuy77FxfxRM,12255
-xlwings_utils-25.0.6.post4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xlwings_utils-25.0.6.post4.dist-info/top_level.txt,sha256=kf5SEv0gZiRObPhUoYcc1O_iX_wwTOPeUIYvzyYeAM4,14
-xlwings_utils-25.0.6.post4.dist-info/RECORD,,