Merge branch 'master' of https://github.com/ericremoreynolds/excelpython

Author: ericremoreynolds

README.md

@@ -1,3 +1,5 @@
+We are pleased to announce our [one-day Python and Excel workshop](http://www.zoomeranalytics.com/training/) in London on 9th December! Learn how to use ExcelPython, xlwings, spreadgit and the Python Quant Platform directly from the people who developed them.
+
 # ExcelPython v2
 
 Write Excel user-defined functions and macros in Python!

docs/Readme.md

@@ -22,4 +22,3 @@ If you encounter any issues in getting the add-in set up consult the [troublesho
 **Learn how to analyse the problem when something goes wrong**
 
 * [Debugging](tutorials/Debugging01.md)
-* [Troubleshooting](tutorials/Troubleshooting01.md)

docs/tutorials/Debugging01.md

@@ -35,7 +35,11 @@ from xlpython import *
 
 # Add these two lines
 import ptvsd
-ptvsd.enable_attach(secret='cows')
+try:
+	ptvsd.enable_attach(secret='cows')
+except ptvsd.AttachAlreadyEnabledError:
+	pass
+
 
 @xlfunc
 def DoubleSum(x, y):
@@ -44,6 +48,8 @@ def DoubleSum(x, y):
 
 These to lines enable us to attach the Visual Studio debugger to the Python script, so that we can debug it. Note that the Python process itself must be running for this to work, and ExcelPython does not launch it until it is needed - so just to make sure that it is running and that the `Book1.py` script is loaded, click 'Import Python UDFs'.
 
+(Note: the `try ... except` clause is needed because if `enable_attach` is called twice PTVS will complain that it's already been called. Since we have no way of controlling if it's already been called (for example if the script is reloaded, or if it is called in a different script) we catch the error and ignore it, as recommended in the PTVS documentation.)
+
 At this point you may need to unblock a port on the Windows firewall:
 
 ![image](https://cloud.githubusercontent.com/assets/5197585/4387988/f02fbbe8-43e4-11e4-997e-31f12adbdf98.png)

docs/tutorials/Usage01.md

@@ -1,7 +1,7 @@
 A very simple usage example
 ---
 
-You can try out xlpython from the VBA Immediate Window (Ctrl + G if it's not already visible in the VBA window).
+You can try out ExcelPython from the VBA Immediate Window (Ctrl + G if it's not already visible in the VBA window).
 
 Type the following
 
@@ -12,6 +12,8 @@ and press return. You should see
     ?Py.Str(Py.Eval("1+2"))
     3
 
+(It can happen that you get an `Object required` error. This may happen if you do not have your ExcelPython-enabled workbook selected from the VBA project list when you press return in the Immediate Window. This is necessary because otherwise the Immediate Window statement will execute in the wrong VBA context and therefore will not be able to find the `Py` function.)
+
 You can try evaluating any Python expression, and you'll get the result
 printed in the Immediate Window.
 

docs/tutorials/Usage02.md

@@ -1,4 +1,4 @@
-A more practical use of xlpython
+A more practical use of ExcelPython
 ---
 
 The above example gives a light introduction to manipulating a few simple objects through VBA. In practice though, what's needed is a way to get a load of inputs from Excel, pass them to a method defined in a Python script somewhere, get the outputs back from Python and use them VBA or place them in the spreadsheet as required.
@@ -10,10 +10,10 @@ PyModule returns a pointer to a Python module, much like the import statement. I
     ?Py.Str(Py.Module("datetime"))
     <module 'datetime' (built-in)\>
 
-If you want to call functions from a script which you have placed in a non-standard location, you can tell xlpython to add additional search directories before trying to load the module, as follows:
+By default the Python instance associated with a workbook runs in that workbook's folder (as determined by `ThisWorkbook.Path`), so if you place a Python script in that folder, you can load it as a module.
 
-    ?Py.Str(Py.Module("MyScript", Py.AddPath("D:\Scripts")))
-    <module 'MyScript' from 'D:\Scripts\MyScript.py'\>
+    ?Py.Str(Py.Module("MyScript"))
+    <module 'MyScript' from 'C:\WorkbookFolder\MyScript.py'\>
 
 Once you have access to the module you want, you can use `Py.Call` to invoke functions contained in the module (note that `Py.Call` actually calls any method of any object, not just module objects). This is done by explicitly passing the ordered and keyword arguments. For example calling
 

docs/tutorials/Usage03.md

@@ -13,21 +13,17 @@ def MyFunction(x, y):
 
 The following VBA code can be used to call this function, taking the input parameters from a worksheet and pasting the outputs back to that sheet.
 
-    Function PyPath()
-        PyPath = ThisWorkbook.Path
-    End Function
-    
-    Sub CallPythonCode()
-        Set res = Py.Call( _
-            Py.Module("MyScript", Py.AddPath(PyPath)), "MyFunction", _
-            Py.Dict( _
-                "x", Sheet1.Range("A1").Value2, _
-                "y", Sheet1.Range("A2").Value2))
-        Sheet1.Range("A3").Value2 = Py.Var(Py.GetItem(res, "sum"))
-        Sheet1.Range("A4:B4").Value2 = Py.Var(Py.GetItem(res, "sorted"))
-    End Sub
-
-The function `PyPath` is a utility function which returns our additional module search path. It's set up so that to access Python scripts we just need to place them in the same folder as the workbook. It's worth defining this once in your workbook's VBA project for use wherever necessary.
+```vb.net
+Sub CallPythonCode()
+    Set res = Py.Call( _
+        Py.Module("MyScript"), "MyFunction", _
+        Py.Dict( _
+            "x", Sheet1.Range("A1").Value2, _
+            "y", Sheet1.Range("A2").Value2))
+    Sheet1.Range("A3").Value2 = Py.Var(Py.GetItem(res, "sum"))
+    Sheet1.Range("A4:B4").Value2 = Py.Var(Py.GetItem(res, "sorted"))
+End Sub
+```
 
 The calls to `Py.Module` and `Py.Call` have been explained above. Once the result dictionary is obtained from the function, its elements can be accessed using `Py.GetItem`.
 

docs/tutorials/Usage04.md

@@ -40,7 +40,7 @@ and all other size ranges have two-dimensional array values.
 Since two-dimensional tuples do not exist in Python, it gets converted to a tuple-of-tuples. Often however, you will want to pass a range as a one-dimensional tuple. Consider for example the built-in Python function `sorted`. If you call this function on the range "A1:C1" it returns the same value as is passed in:
 
 ```
-?Py.Str(Py.Call(Py.Builtins, "sorted", Py.Tuple(Range("A1:C1").Value2)))
+?Py.Str(Py.Call(Py.Builtin, "sorted", Py.Tuple(Range("A1:C1").Value2)))
 [(3.0, 1.0, 2.0)]
 ```
 
@@ -63,7 +63,7 @@ To do this, you can convert the 1x3 two-dimensional VBA array to 3-element one-d
 ```
 ?Py.Str(NDims(Range("A1:C1").Value2, 1))
 (3.0, 1.0, 2.0)
-?Py.Str(Py.Call(Py.Builtins, "sorted", Py.Tuple(NDims(Range("A1:C1").Value2, 1))))
+?Py.Str(Py.Call(Py.Builtin, "sorted", Py.Tuple(NDims(Range("A1:C1").Value2, 1))))
 [1.0, 2.0, 3.0]
 ```
 
@@ -96,7 +96,7 @@ So how do you get the value out of Python and into VBA? The key is to convert it
 or in the VBA code by calling the Python conversion function directly on the returned object:
 
 ```
-?Py.Var(Py.Call(Py.Builtins, "float", Py.Tuple(Py.Eval("norm.cdf(0.0)", locals))))
+?Py.Var(Py.Call(Py.Builtin, "float", Py.Tuple(Py.Eval("norm.cdf(0.0)", locals))))
  0.5
 ```