xlwings-utils 25.0.5__tar.gz → 25.0.6__tar.gz

{xlwings_utils-25.0.5/xlwings_utils.egg-info → xlwings_utils-25.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xlwings_utils
-Version: 25.0.5
+Version: 25.0.6
 Summary: xlwings_utils
 Author-email: Ruud van der Ham <rt.van.der.ham@gmail.com>
 Project-URL: Homepage, https://github.com/salabim/xlwings_utils
@@ -62,8 +62,7 @@ python -c "exec(__import__('requests').get('https://salabim.org/dropbox setup.py
 Then, it is possible to list all files in a specified folder using the list_dropbox function.
 It is also possible to get the folders and to access all underlying folders.
 
-The `read_dropbox` function can be used to read the contents (bytes) of a Dropbox file. If the file is not read correctly, which seems
-to happen rather frequently, an OSError exception is raised.
+The `read_dropbox` function can be used to read the contents (bytes) of a Dropbox file. As reading from Dropbox under pyodide is very unreliable, xlwings_utils automatically retries several times (by default 100 times). The actual number of retries can be found with `read_dropbox.retries`.
 
 The function `write_dropbox` can be used to write contents (bytes) to a Dropbox file.
 
@@ -263,10 +262,93 @@ The capture buffer can also be retrieved as a string with `capture.str` and `cap
 
 Clearing the captured stdout buffer can be done at any time with `capture.clear()`.
 
+## Functionality for accessing local files via VBA
+
+Currently, *xlwings Lite* does not provide access to the local file system. Therefore, xlwings_utils offers some functionality to trigger a VBA script as well as functionality to encode a file in the pyodide file system to a VBA sheet and to trigger writing the encoded file(s) to the local file system.
+
+Files can be encoded into a block, like:
+
+```
+    bl = xwu.block.encode_files("film1.mp4", "settings.txt")
+    book.sheets["VBA"].range((10,2)).value=bl.value
+```
+
+With this code, column B will be filled with encoded copies of the files *film1.mp4* and *settings.txt* . This can then be used with a suitable VBA macro to decode to the real file system. A VBA macro can be triggered with `xwu.trigger_macro()`. This requires an Excel worksheet where cell A1 is reserved for communication with xlwings lite. This worksheet needs to contain a macro, like
+
+```
+Private Sub Worksheet_Calculate()
+    If Me.Range("A1").Formula = "=NOW()" Then
+        Me.Range("A1").Value = Null
+        Call MacroToExecute
+    End If
+End Sub
+```
+
+, where `MacroToExecute` should contain the user code, most likely code to decode files encoded with something like
+
+```
+bl.decode_to_files()
+```
+
+The VBA code below can be used to decode encoded file(s ) on a worksheet.
+
+```
+Sub DecodeFiles()
+    
+    Dim vArr() As Byte
+    Dim S As String
+    Dim Column As Integer
+    Dim Row As Integer
+    Dim ws As Worksheet
+    Dim Count As Integer
+    Dim FileNames As String
+    
+    Column = 2
+    Row = 1
+    
+    ThisDir = ThisWorkbook.Path
+    Set ws = Me
+    Count = 0
+    While Row < 30000
+        Line = ws.Cells(Row, Column)
+        If InStr(Line, "<file=") = 1 And Right(Line, 1) = ">" Then
+            If Count <> 0 Then
+                FileNames = FileNames & ", "
+            End If
+            Count = Count + 1
+            FileNameOnly = Mid(Line, 7, Len(Line) - 7)
+            Filename = ThisDir & "/" & FileNameOnly
+            FileNames = FileNames & FileNameOnly
+            
+            Row = Row + 1
+            S = ""
+            While ws.Cells(Row, Column) <> "</file>"
+                S = S & ws.Cells(Row, Column)
+                Row = Row + 1
+            Wend
+                
+            vArr = Base64ToArray(S)
+        
+            Open Filename For Binary Access Write As #1
+            WritePos = 1
+            Put #1, WritePos, vArr
+            Close #1
+        End If
+        
+        Row = Row + 1
+    
+    Wend
+    
+    If Count = 0 Then
+        MsgBox "No files to decode"
+    Else
+        MsgBox "Successfully decoded and written " & Str(Count) & " file(s): " & FileNames
+    End If
+```
 
 ## Contact info
 
-You can contact Ruud van der Ham, the core developer, via ruud@salabim.org .
+You can contact Ruud van der Ham, the core developer, at ruud@salabim.org.
 
 ## Badges