updated docs for v0.3.0

Author: fzumstein

README.rst

@@ -80,7 +80,7 @@ This essentially hands over control to ``mymodule.py``:
 
     def rand_numbers():
         """ produces standard normally distributed random numbers with shape (n,n)"""
-        wb = Workbook()  # Creates a reference to the calling Excel file
+        wb = Workbook.caller()  # Creates a reference to the calling Excel file
         n = Range('Sheet1', 'B1').value  # Write desired dimensions into Cell B1
         rand_num = np.random.randn(n, n)
         Range('Sheet1', 'C3').value = rand_num
@@ -121,16 +121,17 @@ Dependencies
 
 * **Windows**: ``pywin32``
 
-* **Mac**: ``psutil``, ``appscript``
+  On Windows, it is recommended to use one of the scientific Python distributions like
+  `Anaconda <https://store.continuum.io/cshop/anaconda/>`_,
+  `WinPython <https://winpython.github.io/>`_ or
+  `Canopy <https://www.enthought.com/products/canopy/>`_ as they already include pywin32. Otherwise it needs to be
+  installed from `here <http://sourceforge.net/projects/pywin32/files/pywin32/>`_.
 
-On Windows, it is recommended to use one of the scientific Python distributions like
-`Anaconda <https://store.continuum.io/cshop/anaconda/>`_,
-`WinPython <https://winpython.github.io/>`_ or
-`Canopy <https://www.enthought.com/products/canopy/>`_ as they already include pywin32. Otherwise it needs to be
-installed from `here <http://sourceforge.net/projects/pywin32/files/pywin32/>`_.
+* **Mac**: ``psutil``, ``appscript``
 
-.. note:: On Mac, the dependencies are automatically being handled if xlwings is installed with ``pip``. However,
-    the Xcode command line tools need to be available. Mac OS X 10.4 (*Tiger*) or later is required.
+  On Mac, the dependencies are automatically being handled if xlwings is installed with ``pip``. However,
+  the Xcode command line tools need to be available. Mac OS X 10.4 (*Tiger*) or later is required.
+  The recommended Python distribution for Mac is `Anaconda <https://store.continuum.io/cshop/anaconda/>`_.
 
 Optional Dependencies
 ---------------------

docs/debugging.rst

@@ -22,15 +22,17 @@ Consider the following code structure of your Python source code:
     import os
     from xlwings import Workbook, Range
 
-    def my_macro(workbook_path=None):
-        wb = Workbook(workbook_path)
+    def my_macro(wb=None):
+        if wb is None:
+            wb = Workbook.caller()
         Range('A1').value = 1
 
     if __name__ == '__main__':
         # To run from Python, not needed when called from Excel.
         # Expects the Excel file next to this source file, adjust accordingly.
         path = os.path.abspath(os.path.join(os.path.dirname(__file__), 'myfile.xlsm'))
-        my_macro(path)
+        wb = Workbook(path)
+        my_macro(wb)
 
 
 ``my_macro()`` can now easily be run from Python for debugging and from Excel for testing without having to change the

docs/images/udf_example.png

@@ -23,6 +23,7 @@ xlwings fully supports NumPy arrays and Pandas DataFrames. It works with Microso
     datastructures
     vba
     debugging
+    udfs
     api
 
 

docs/index.rst

@@ -19,16 +19,17 @@ Dependencies
 
 * **Windows**: ``pywin32``
 
-* **Mac**: ``psutil``, ``appscript``
+  On Windows, it is recommended to use one of the scientific Python distributions like
+  `Anaconda <https://store.continuum.io/cshop/anaconda/>`_,
+  `WinPython <https://winpython.github.io/>`_ or
+  `Canopy <https://www.enthought.com/products/canopy/>`_ as they already include pywin32. Otherwise it needs to be
+  installed from `here <http://sourceforge.net/projects/pywin32/files/pywin32/>`_.
 
-On Windows, it is recommended to use one of the scientific Python distributions like
-`Anaconda <https://store.continuum.io/cshop/anaconda/>`_,
-`WinPython <https://winpython.github.io/>`_ or
-`Canopy <https://www.enthought.com/products/canopy/>`_ as they already include pywin32. Otherwise it needs to be
-installed from `here <http://sourceforge.net/projects/pywin32/files/pywin32/>`_.
+* **Mac**: ``psutil``, ``appscript``
 
-.. note:: On Mac, the dependencies are automatically being handled if xlwings is installed with ``pip``. However,
-    the Xcode command line tools need to be available. Mac OS X 10.4 (*Tiger*) or later is required.
+  On Mac, the dependencies are automatically being handled if xlwings is installed with ``pip``. However,
+  the Xcode command line tools need to be available. Mac OS X 10.4 (*Tiger*) or later is required.
+  The recommended Python distribution for Mac is `Anaconda <https://store.continuum.io/cshop/anaconda/>`_.
 
 Optional Dependencies
 ---------------------

docs/installation.rst

@@ -71,7 +71,7 @@ This essentially hands over control to ``mymodule.py``:
 
     def rand_numbers():
         """ produces standard normally distributed random numbers with shape (n,n)"""
-        wb = Workbook()  # Creates a reference to the calling Excel file
+        wb = Workbook.caller()  # Creates a reference to the calling Excel file
         n = Range('Sheet1', 'B1').value  # Write desired dimensions into Cell B1
         rand_num = np.random.randn(n, n)
         Range('Sheet1', 'C3').value = rand_num
@@ -82,7 +82,7 @@ then go to ``File > Import File...`` and import the ``xlwings.bas`` file. ). It
 your ``xlwings`` installation.
 
 .. note:: Always instantiate the ``Workbook`` within the function that is called from Excel and not outside as global
-    variable. Older versions of the docs/samples were showing the wrong approach.
+    variable.
 
 For further details, see :ref:`vba`.
 

docs/quickstart.rst

@@ -0,0 +1,56 @@
+.. _udfs:
+
+User Defined Functions (UDFs)
+=============================
+
+.. note:: This feature is currently experimental and only available on Windows. It is the first step of an integration
+    with `ExcelPython <http://ericremoreynolds.github.io/excelpython//>`_. Currently, there is no support for
+    ExcelPython's decorator functionality and add-in. Also, ExcelPython's config file is obsolete as settings are being
+    handled in the xlwings VBA module.
+
+
+In it's current implementation, the UDF functionality is most useful to get access to existing Python code like for example
+NumPy's powerful set of functions. This is best explained in a simple example: To expose NumPy's
+`pseudo-inverse <http://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.pinv.html>`_, you would write the
+following VBA code:
+
+.. code-block:: vb.net
+
+    Public Function pinv(x As Range)
+    On Error GoTo Fail:
+        Set numpy_array = Py.GetAttr(Py.Module("numpy"), "array")
+        Set pseudo_inv = Py.GetAttr(Py.GetAttr(Py.Module("numpy"), "linalg"), "pinv")
+        Set x_array = Py.Call(numpy_array, Py.Tuple(x.Value))
+        Set result_array = Py.Call(pseudo_inv, Py.Tuple(x_array))
+        Set result_list = Py.Call(result_array, "tolist")
+        pinv = Py.Var(result_list)
+        Exit Function
+    Fail:
+        pinv = Err.Description
+    End Function
+
+This then enables you to use ``pinv()`` as array function from Excel cells:
+
+.. figure:: images/udf_example.png
+
+1. Fill a spreadsheet with the following numbers as shown on the image:
+
+   ``A1``: 1, ``A2``: 2, ``B1``: 2, ``B2``: 4
+
+2. Select cells ``D1:E2``.
+
+3. Type ``pinv(A1:B2)`` into D1 while D1:E2 are still selected.
+
+4. Hit ``Ctrl-Shift-Enter`` to enter the array formula. If done right, the formula bar will automatically
+   wrap the formula with curly braces ``{}``.
+
+Further documentation
+---------------------
+
+For more in depth documentation at this point in time, please refer directly to the
+`ExcelPython <http://ericremoreynolds.github.io/excelpython//>`_ project, mainly the following docs:
+
+* `A very simple usage example <https://github.com/ericremoreynolds/excelpython/blob/master/docs/tutorials/Usage01.md>`_
+* `A more practical use of ExcelPython <https://github.com/ericremoreynolds/excelpython/blob/master/docs/tutorials/Usage02.md>`_
+* `Putting it all together <https://github.com/ericremoreynolds/excelpython/blob/master/docs/tutorials/Usage03.md>`_
+* `Ranges, lists and SAFEARRAYs <https://github.com/ericremoreynolds/excelpython/blob/master/docs/tutorials/Usage04.md>`_

docs/udfs.rst

@@ -28,26 +28,35 @@ While the defaults will often work out-of-the box, you can change the settings a
 under ``Function Settings``::
 
     PYTHON_WIN = ""
-    PYTHON_MAC = GetMacDir("Home") & "/anaconda/bin"
+    PYTHON_MAC = ""
     PYTHON_FROZEN = ThisWorkbook.Path & "\build\exe.win32-2.7"
     PYTHONPATH = ThisWorkbook.Path
     LOG_FILE = ThisWorkbook.Path & "\xlwings_log.txt"
+    SHOW_LOG = True
+    OPTIMIZED_CONNECTION = False
 
 * ``PYTHON_WIN``: This is the directory of the Python interpreter on Windows. ``""`` resolves to your default Python
   installation on the PATH, i.e. the one you can start by just typing ``python`` at a command prompt.
 * ``PYTHON_MAC``: This is the directory of the Python interpreter on Mac OSX. ``""`` resolves to your default
-  installation on $PATH but **not** the one defined in .bash_profile! Since you most probably define your default Python
-  installation in .bash_profile, you will have to adjust this value to match your installation. To get special folders
+  installation as per PATH on .bash_profile. To get special folders
   on Mac, type ``GetMacDir("Name")`` where ``Name`` is one of the following: ``Home``, ``Desktop``, ``Applications``,
   ``Documents``.
 * ``PYTHON_FROZEN`` [Optional]: Currently only on Windows, indicates the directory of the exe file that has been frozen
   by either using ``cx_Freeze`` or ``py2exe``. Can be set to ``""`` if unused.
 * ``PYTHONPATH`` [Optional]: If the source file of your code is not found, add the path here. Otherwise set it to ``""``.
 * ``LOG_FILE``: Directory **including** the file name. This file is necessary for error handling.
+* ``SHOW_LOG``: If False, no pop-up with the Log messages (usually errors) will be shown. Use with care.
+* ``OPTIMIZED_CONNECTION``: Currently only on Windows, use a COM Server for an efficient connection (experimental!)
 
 .. note:: If the settings (especially ``PYTHONPATH`` and ``LOG_FILE``) need to work on Windows on Mac, use backslashes
     in relative file path, i.e. ``ThisWorkbook.Path & "\mydirectory"``.
 
+.. note:: ``OPTIMIZED_CONNECTION = True`` works currently on **Windows only** and is still experimental! This will
+  use a COM server that will keep the connection to Python alive between different calls and is therefore much more
+  efficient. However, changes in the Python code are not being picked up until the ``pythonw.exe`` process is restarted
+  by killing it manually in the Windows Task Manager. The suggested workflow is hence to set
+  ``OPTIMIZED_CONNECTION = False`` for development and to only set it to ``True`` for production.
+
 
 Subtle difference between the Windows and Mac Version
 -----------------------------------------------------
@@ -79,12 +88,13 @@ This essentially hands over control to ``mymodule.py``:
 
     def rand_numbers():
         """ produces std. normally distributed random numbers with shape (n,n)"""
-        wb = Workbook()  # Creates a reference to the calling Excel file
+        wb = Workbook.caller()  # Creates a reference to the calling Excel file
         n = Range('Sheet1', 'B1').value  # Write desired dimensions into Cell B1
         rand_num = np.random.randn(n, n)
         Range('Sheet1', 'C3').value = rand_num
 
 You can then attach ``MyMacro`` to a button or run it directly in the VBA Editor by hitting ``F5``.
 
-.. note:: Always instantiate the ``Workbook`` within the function that is called from Excel and not outside as
-    module-wide global variable. Older versions of the docs/samples were showing the wrong approach.
+.. note:: Always place ``Workbook.caller()`` within the function that is called from Excel and not outside as
+    module-wide global variable. Otherwise it doesn't get garbage collected with ``OPTIMIZED_CONNECTION = True``
+    which prevents Excel from shutting down properly upon exiting and and leaves you with a zombie process.

docs/vba.rst

@@ -9,7 +9,7 @@ API changes
 
 * To reference the calling Workbook when running code from VBA, you now have to use ``Workbook.caller()``. This means
   that ``wb = Workbook()`` is now consistently creating a new Workbook, whether the code is called interactively or
-  through VBA.
+  from VBA.
 
   ==============================  =========================
   **New**                         **Old**
@@ -26,7 +26,7 @@ This version adds two exciting but still **experimental** features from
   will keep the connection to Python alive between different calls and is therefore much more efficient. However,
   changes in the Python code are not being picked up until the ``pythonw.exe`` process is restarted by killing it
   manually in the Windows Task Manager. The suggested workflow is hence to set ``OPTIMIZED_CONNECTION = False`` for
-  development and only set it to ``True`` for production - keep in mind though that this feature is stil experimental!
+  development and only set it to ``True`` for production - keep in mind though that this feature is still experimental!
 
 * User Defined Functions (UDFs): Using ExcelPython's wrapper syntax in VBA, you can expose Python functions as UDFs.
 
@@ -36,18 +36,12 @@ isn't available through xlwings yet.
 
 Further enhancements include:
 
-* New method :meth:`xlwings.Range.resize` (:issue:`90`)
-
-* New method :meth:`xlwings.Range.offset` (:issue:`89`)
-
-* New property :attr:`xlwings.Range.shape` (:issue:`109`)
-
-* New property :attr:`xlwings.Range.size` (:issue:`109`)
-
-* New property :attr:`xlwings.Range.hyperlink` and new method :meth:`xlwings.Range.add_hyperlink` (:issue:`104`)
-
-* New property :attr:`xlwings.Range.color` (:issue:`97`)
-
+* New method :meth:`xlwings.Range.resize` (:issue:`90`).
+* New method :meth:`xlwings.Range.offset` (:issue:`89`).
+* New property :attr:`xlwings.Range.shape` (:issue:`109`).
+* New property :attr:`xlwings.Range.size` (:issue:`109`).
+* New property :attr:`xlwings.Range.hyperlink` and new method :meth:`xlwings.Range.add_hyperlink` (:issue:`104`).
+* New property :attr:`xlwings.Range.color` (:issue:`97`).
 * The ``len`` built-in function can now be used on ``Range`` (:issue:`109`):
 
     >>> len(Range('A1:B5'))
@@ -60,8 +54,7 @@ Further enhancements include:
             cell.color = (255, 0, 0)
 
 * [Mac version]: The VBA module finds now automatically the default Python installation as per ``PATH`` variable on
-  ``.bash_profile`` when ``PYTHON_MAC = ""`` (the default now in the VBA settings) (:issue:`95`).
-
+  ``.bash_profile`` when ``PYTHON_MAC = ""`` (the default in the VBA settings) (:issue:`95`).
 * The VBA error pop-up can now be muted by setting ``SHOW_LOG = False`` in the VBA settings. To be used with
   care, but it can be useful on Mac, as the pop-up window is currently showing printed log messages even if no error
   occurred(:issue:`94`).