Adding upstream version 0.19.0.upstream/0.19.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 237 insertions, 0 deletions

diff --git a/doc/python/document.rst b/doc/python/document.rst
new file mode 100644
index 0000000..7171f2c
--- /dev/null
+++ b/doc/python/document.rst
@@ -0,0 +1,58 @@
+
+.. py:currentmodule:: ixion
+
+Document
+========
+
+.. class:: Document()
+
+   Class :class:`~ixion.Document` represents an entire document which consists
+   of one or more :class:`~ixion.Sheet` objects.
+
+.. attribute:: Document.sheet_names
+
+   A read-only attribute that provides a tuple of the names of the sheets that
+   belong to the document. The order of the sheet names signifies the order
+   of the sheets in the document.
+
+.. method:: Document.append_sheet(sheet_name)
+
+   Append a new sheet to the document object and return the newly created
+   :class:`~ixion.Sheet` object. The *sheet name* will become the name of the
+   sheet object being appended. Each :class:`Sheet` object must have a name,
+   and the name must be unique within the document.
+
+   :param str sheet_name: name of the sheet to be appended to the document.
+   :rtype: :class:`ixion.Sheet`
+   :return: appended sheet object.
+
+.. method:: Document.get_sheet(arg)
+
+   Get a sheet object either by the position or by the name.  When the ``arg``
+   is an integer, it returns the sheet object at specified position (0-based).
+   When the ``arg`` is a string, it returns the sheet object whose name
+   matches the specified string.
+
+   :param arg: either the name of a sheet if it's of type ``str``, or the
+      index of a sheet if it's of type ``int``.
+   :rtype: :class:`ixion.Sheet`
+   :return: sheet object representing the specified sheet.
+
+.. warning:: Prefer passing a sheet index to :meth:`~ixion.Document.get_sheet`
+             than passing a sheet name.  When passing a sheet name as an
+             argument, the current :meth:`~ixion.Document.get_sheet`
+             implementation has to iterate through the sheet objects in the
+             document to find a matching one.
+
+.. method:: Document.calculate([threads])
+
+   Calculate all formula cells within the document that are marked "dirty" i.e.
+   either those formula cells whose direct or indirect references have changed
+   their values, or those formula cells that have been entered into the
+   document.
+
+   :param int threads: (optional) number of threads to use for the calculation
+      besides the main thread.  Set this to 0 if you want the calculation to
+      be performed on the main thread only.  The value of 0 is assumed if this
+      value is not specified.
+
diff --git a/doc/python/index.rst b/doc/python/index.rst
new file mode 100644
index 0000000..9efcad2
--- /dev/null
+++ b/doc/python/index.rst
@@ -0,0 +1,11 @@
+
+Python API
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart.rst
+   document.rst
+   sheet.rst
+
diff --git a/doc/python/quickstart.rst b/doc/python/quickstart.rst
new file mode 100644
index 0000000..6b44e0f
--- /dev/null
+++ b/doc/python/quickstart.rst
@@ -0,0 +1,85 @@
+
+.. py:currentmodule:: ixion
+
+Quickstart
+==========
+
+Let's go over very quickly how to create a document and populate some cells inside spreadsheet.
+
+First, you need to import ixion module and create a new :class:`Document` object.
+
+::
+
+    >>> import ixion
+    >>> doc = ixion.Document()
+
+Since your newly-created document has no sheet at all, you need to insert one.
+
+::
+
+    >>> sheet1 = doc.append_sheet("MySheet1")
+
+The :meth:`Document.append_sheet` method takes a sheet name string as an argument (which in
+this case is "MySheet1") and returns an object representing the sheet that has
+just been inserted.  This sheet object allows access to the sheet
+name via the :attr:`Sheet.name` attribute.
+
+::
+
+    >>> print(sheet1.name)
+    'MySheet1'
+
+.. note:: This attribute is read-only; you'll get a :exc:`TypeError` if you
+          attempt to assign a new value to it.
+
+Now that you have a sheet object, let's go over how to put new cell values into
+the sheet.  The sheet object provides several methods to set new cell values
+and also to retrieve them afterward.
+
+::
+
+    >>> sheet1.set_numeric_cell(0, 0, 12.3)  # Set 12.3 to cell A1.
+    >>> sheet1.get_numeric_value(0, 0)
+    12.3
+    >>> sheet1.set_string_cell(1, 0, "My string")  # Set "My string" to cell A2.
+    >>> sheet1.get_string_value(1, 0)
+    'My string'
+
+The setters take 3 arguments: the first one is a 0-based row index, the second
+one is a column index (also 0-based), and the third one is the new cell value.
+You can also pass these arguments by name as follows:
+
+::
+
+    >>> sheet1.set_string_cell(row=1, column=0, value="My string")
+
+Let's insert a formula expression next.
+
+::
+
+    >>> sheet1.set_formula_cell(0, 1, "A1*100")  # B1
+    >>> sheet1.set_formula_cell(1, 1, "A2")      # B2
+
+.. note:: When setting a formula expression to a cell, you don't need to start
+          your formula expression with a '=' like you would when you are
+          entering a formula in a spreadsheet application.
+
+The formula cells don't get calculated automatically as you enter them;
+you need to explicitly tell the document to calculate the formula cells via
+the :meth:`Document.calculate` method.
+
+::
+
+    >>> doc.calculate()
+
+Now all the formula cells in this document have been calculated.  Let's retrieve
+the results of the formula cells.
+
+::
+
+   >>> sheet1.get_numeric_value(0, 1)
+   1230.0
+   >>> sheet1.get_string_value(1, 1)
+   'My string'
+
+That's all there is to it!
diff --git a/doc/python/sheet.rst b/doc/python/sheet.rst
new file mode 100644
index 0000000..74f4ab4
--- /dev/null
+++ b/doc/python/sheet.rst
@@ -0,0 +1,83 @@
+
+.. py:currentmodule:: ixion
+
+Sheet
+=====
+
+.. class:: ixion.Sheet()
+
+   Class :class:`~ixion.Sheet` represents a single sheet that stores cells in
+   a 2-dimensional grid address space.  Rows and columns are used to specify a
+   position in the grid, and both rows and columns are 0-based, with the
+   top-left-most cell having the address of row 0 and column 0.
+
+.. attribute:: Sheet.name
+
+   A string representing the name of the sheet object.  This is a read-only
+   attribute.
+
+.. method:: Sheet.set_numeric_cell(row, column, value)
+
+   Set a numeric *value* to a cell at specified *row* and *column* position.
+
+   :param int row: row position.
+   :param int column: column position.
+   :param float value: numeric value to set to the specified position.
+
+.. method:: Sheet.set_string_cell(row, column, value)
+
+   Set a string *value* to a cell at specified *row* and *column* position.
+
+   :param int row: row position.
+   :param int column: column position.
+   :param str value: string value to set to the specified position.
+
+.. method:: Sheet.set_formula_cell(row, column, value)
+
+   Set a formula expression (*value*) to a cell at specified *row* and *column* position.
+
+   :param int row: row position.
+   :param int column: column position.
+   :param str value: formula expression to set to the specified position.
+
+.. method:: Sheet.get_numeric_value(row, column)
+
+   Get a numeric value representing the content of a cell at specified *row*
+   and *column* position.  If the cell is of numeric type, its value is
+   returned.  If it's a formula cell, the result of the calculated formula
+   result is returned if the result is of numeric type.
+
+   :param int row: row position.
+   :param int column: column position.
+   :rtype: float
+   :return: numeric value of the cell at specified position.
+
+.. method:: Sheet.get_string_value(row, column)
+
+   Get a string value representing the content of a cell at specified *row*
+   and *column* position.  If the cell is of string type, its value is
+   returned as-is.  If it's a formula cell, the result of the calculated
+   formula result is returned if the result is of string type.
+
+   :param int row: row position.
+   :param int column: column position.
+   :rtype: str
+   :return: string value of the cell at specified position.
+
+.. method:: Sheet.get_formula_expression(row, column)
+
+   Given a formula cell at specified *row* and *column* position, get the
+   formula expression stored in that cell.
+
+   :param int row: row position.
+   :param int column: column position.
+   :rtype: str
+   :return: formula expression stored in the cell at specified position.
+
+.. method:: Sheet.erase_cell(row, column)
+
+   Erase the cell at specified *row* and *column* position.  The slot at the
+   specified position becomes empty afterward.
+
+   :param int row: row position.
+   :param int column: column position.