Adding upstream version 0.19.2.upstream/0.19.2upstream

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

21 files changed, 383 insertions, 0 deletions

diff --git a/doc/python/index.rst b/doc/python/index.rst
new file mode 100644
index 0000000..bb76c47
--- /dev/null
+++ b/doc/python/index.rst
@@ -0,0 +1,17 @@
+
+Python API reference
+====================
+
+Packages
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   orcus/index.rst
+   orcus/tools/index.rst
+   orcus/csv/index.rst
+   orcus/gnumeric/index.rst
+   orcus/ods/index.rst
+   orcus/xlsx/index.rst
+   orcus/xls_xml/index.rst
diff --git a/doc/python/orcus/cell.rst b/doc/python/orcus/cell.rst
new file mode 100644
index 0000000..0143307
--- /dev/null
+++ b/doc/python/orcus/cell.rst
@@ -0,0 +1,31 @@
+
+Cell
+====
+
+.. py:class:: orcus.Cell
+
+   This class represents a single cell within a :py:class:`.Sheet` object.
+
+   .. py:method:: get_formula_tokens
+
+      :rtype: :py:class:`.FormulaTokens`
+      :return: an iterator object for a formula cell.
+
+      Get an iterator object for formula tokens if the cell is a formula cell.
+      This method returns ``None`` for a non-formula cell.
+
+   .. py:attribute:: type
+      :type: orcus.CellType
+
+      Attribute specifying the type of this cell.
+
+   .. py:attribute:: value
+
+      Attribute containing the value of the cell.
+
+   .. py:attribute:: formula
+      :type: str
+
+      Attribute containing the formula string in case of a formula cell.  This
+      value will be ``None`` for a non-formula cell.
+
diff --git a/doc/python/orcus/cell_type.rst b/doc/python/orcus/cell_type.rst
new file mode 100644
index 0000000..26568d4
--- /dev/null
+++ b/doc/python/orcus/cell_type.rst
@@ -0,0 +1,7 @@
+
+CellType
+========
+
+.. autoclass:: orcus.CellType
+   :members:
+   :undoc-members:
diff --git a/doc/python/orcus/csv/index.rst b/doc/python/orcus/csv/index.rst
new file mode 100644
index 0000000..f2b73a0
--- /dev/null
+++ b/doc/python/orcus/csv/index.rst
@@ -0,0 +1,19 @@
+
+orcus.csv
+=========
+
+.. py:function:: orcus.csv.read
+
+   Read an CSV file from a specified file path and create a :py:class:`orcus.Document`
+   instance object.
+
+   :param stream: either string value, or file object containing a string stream.
+   :rtype: :py:class:`orcus.Document`
+   :return: document instance object that stores the content of the file.
+
+   Example::
+
+      from orcus import csv
+
+      with open("path/to/file.csv", "r") as f:
+          doc = csv.read(f)
diff --git a/doc/python/orcus/document.rst b/doc/python/orcus/document.rst
new file mode 100644
index 0000000..d4b6fc5
--- /dev/null
+++ b/doc/python/orcus/document.rst
@@ -0,0 +1,21 @@
+
+Document
+========
+
+.. py:class:: orcus.Document
+
+   An instance of this class represents a document model.  A document consists
+   of multiple sheet objects.
+
+   .. py:attribute:: sheets
+
+      Read-only attribute that stores a tuple of :py:class:`.Sheet` instance
+      objects.
+
+   .. py:function:: get_named_expressions
+
+      Get a named expressions iterator.
+
+      :rtype: :obj:`.NamedExpressions`
+      :return: named expression object.
+
diff --git a/doc/python/orcus/format_type.rst b/doc/python/orcus/format_type.rst
new file mode 100644
index 0000000..a3d4b01
--- /dev/null
+++ b/doc/python/orcus/format_type.rst
@@ -0,0 +1,7 @@
+
+FormatType
+==========
+
+.. autoclass:: orcus.FormatType
+   :members:
+   :undoc-members:
diff --git a/doc/python/orcus/formula_token.rst b/doc/python/orcus/formula_token.rst
new file mode 100644
index 0000000..d9627cf
--- /dev/null
+++ b/doc/python/orcus/formula_token.rst
@@ -0,0 +1,19 @@
+
+FormulaToken
+============
+
+.. py:class:: orcus.FormulaToken
+
+   This class represents a single formula token value as returned from a
+   :py:class:`.FormulaTokens` iterator.
+
+   .. py:attribute:: op
+      :type: orcus.FormulaTokenOp
+
+   Attribute specifying the opcode of the formula token.
+
+   .. py:attribute:: type
+      :type: orcus.FormulaTokenType
+
+   Attribute specifying the type of the formula token.
+
diff --git a/doc/python/orcus/formula_token_op.rst b/doc/python/orcus/formula_token_op.rst
new file mode 100644
index 0000000..0f29d59
--- /dev/null
+++ b/doc/python/orcus/formula_token_op.rst
@@ -0,0 +1,7 @@
+
+FormulaTokenOp
+==============
+
+.. autoclass:: orcus.FormulaTokenOp
+   :members:
+   :undoc-members:
diff --git a/doc/python/orcus/formula_token_type.rst b/doc/python/orcus/formula_token_type.rst
new file mode 100644
index 0000000..cc575d4
--- /dev/null
+++ b/doc/python/orcus/formula_token_type.rst
@@ -0,0 +1,7 @@
+
+FormulaTokenType
+================
+
+.. autoclass:: orcus.FormulaTokenType
+   :members:
+   :undoc-members:
diff --git a/doc/python/orcus/formula_tokens.rst b/doc/python/orcus/formula_tokens.rst
new file mode 100644
index 0000000..ba5aa4e
--- /dev/null
+++ b/doc/python/orcus/formula_tokens.rst
@@ -0,0 +1,8 @@
+
+FormulaTokens
+=============
+
+.. py:class:: orcus.FormulaTokens
+
+   Iterator for formula tokens within a :py:class:`.Cell` object representing
+   a formula cell.  Each iteration will return a :py:class:`.FormulaToken` object.
diff --git a/doc/python/orcus/gnumeric/index.rst b/doc/python/orcus/gnumeric/index.rst
new file mode 100644
index 0000000..a3ab2cc
--- /dev/null
+++ b/doc/python/orcus/gnumeric/index.rst
@@ -0,0 +1,24 @@
+
+orcus.gnumeric
+==============
+
+.. py:function:: orcus.gnumeric.read
+
+   Read an Gnumeric file from a specified file path and create a
+   :py:class:`orcus.Document` instance object.
+
+   :param stream: file object containing byte streams.
+   :param bool recalc: optional parameter specifying whether or not to recalculate
+       the formula cells on load. Defaults to ``False``.
+   :param str error_policy: optional parameter indicating what to do when
+       encountering formula cells with invalid formula expressions. The value
+       must be either ``fail`` or ``skip``.  Defaults to ``fail``.
+   :rtype: :py:class:`orcus.Document`
+   :return: document instance object that stores the content of the file.
+
+   Example::
+
+      from orcus import gnumeric
+
+      with open("path/to/file.gnumeric", "rb") as f:
+          doc = gnumeric.read(f, recalc=True, error_policy="fail")
diff --git a/doc/python/orcus/index.rst b/doc/python/orcus/index.rst
new file mode 100644
index 0000000..69ee284
--- /dev/null
+++ b/doc/python/orcus/index.rst
@@ -0,0 +1,34 @@
+
+orcus
+=====
+
+.. py:function:: orcus.detect_format
+
+   Detects the file format of the stream.
+
+   :param stream: either bytes, or file object containing a byte stream.
+   :rtype: :py:class:`orcus.FormatType`
+   :return: enum value specifying the detected file format.
+
+   Example::
+
+      import orcus
+
+      with open("path/to/file", "rb") as f:
+          fmt = orcus.detect_format(f)
+
+
+.. toctree::
+   :maxdepth: 1
+
+   cell.rst
+   cell_type.rst
+   document.rst
+   format_type.rst
+   formula_token.rst
+   formula_token_op.rst
+   formula_token_type.rst
+   formula_tokens.rst
+   named_expressions.rst
+   sheet.rst
+   sheet_rows.rst
diff --git a/doc/python/orcus/named_expressions.rst b/doc/python/orcus/named_expressions.rst
new file mode 100644
index 0000000..fc1aa81
--- /dev/null
+++ b/doc/python/orcus/named_expressions.rst
@@ -0,0 +1,13 @@
+
+NamedExpressions
+================
+
+.. py:class:: NamedExpressions
+
+   Iterator for named expressions.
+
+   .. py:attribute:: names
+      :type: set
+
+      A set of strings representing the names of the named expressions.
+
diff --git a/doc/python/orcus/ods/index.rst b/doc/python/orcus/ods/index.rst
new file mode 100644
index 0000000..1dac00e
--- /dev/null
+++ b/doc/python/orcus/ods/index.rst
@@ -0,0 +1,24 @@
+
+orcus.ods
+==========
+
+.. py:function:: orcus.ods.read
+
+   Read an Open Document Spreadsheet file from a specified file path and create
+   a :py:class:`orcus.Document` instance object.
+
+   :param stream: file object containing byte streams.
+   :param bool recalc: optional parameter specifying whether or not to recalculate
+       the formula cells on load. Defaults to ``False``.
+   :param str error_policy: optional parameter indicating what to do when
+       encountering formula cells with invalid formula expressions. The value
+       must be either ``fail`` or ``skip``.  Defaults to ``fail``.
+   :rtype: :py:class:`orcus.Document`
+   :return: document instance object that stores the content of the file.
+
+   Example::
+
+      from orcus import ods
+
+      with open("path/to/file.ods", "rb") as f:
+          doc = ods.read(f, recalc=True, error_policy="fail")
diff --git a/doc/python/orcus/sheet.rst b/doc/python/orcus/sheet.rst
new file mode 100644
index 0000000..a94f64e
--- /dev/null
+++ b/doc/python/orcus/sheet.rst
@@ -0,0 +1,56 @@
+
+Sheet
+=====
+
+.. py:class:: orcus.Sheet
+
+   An instance of this class represents a single sheet inside a document.
+
+   .. py:function:: get_rows
+
+      This function returns a row iterator object that allows you to iterate
+      through rows in the data region.
+
+      :rtype: :py:class:`.SheetRows`
+      :return: row iterator object.
+
+      Example::
+
+         rows = sheet.get_rows()
+
+         for row in rows:
+             print(row)  # tuple of cell values
+
+   .. py:function:: get_named_expressions
+
+      Get a named expressions iterator.
+
+      :rtype: :obj:`.NamedExpressions`
+      :return: named expression object.
+
+   .. py:function:: write
+
+      Write sheet content to specified file object.
+
+      :param file: writable object to write the sheet content to.
+      :param format: format of the output. Note that it currently
+          only supports a subset of the formats provided by the :obj:`.FormatType`
+          type.
+      :type format: :obj:`.FormatType`
+
+   .. py:attribute:: name
+
+      Read-only attribute that stores the name of the sheet.
+
+   .. py:attribute:: sheet_size
+
+      Read-only dictionary object that stores the column and row sizes of the
+      sheet with the **column** and **row** keys, respectively.
+
+   .. py:attribute:: data_size
+
+      Read-only dictionary object that stores the column and row sizes of the
+      data region of the sheet with the **column** and **row** keys, respectively.
+      The data region is the smallest possible range that includes all non-empty
+      cells in the sheet.  The top-left corner of the data region is always at
+      the top-left corner of the sheet.
diff --git a/doc/python/orcus/sheet_rows.rst b/doc/python/orcus/sheet_rows.rst
new file mode 100644
index 0000000..bd86e6e
--- /dev/null
+++ b/doc/python/orcus/sheet_rows.rst
@@ -0,0 +1,9 @@
+
+SheetRows
+=========
+
+.. py:class:: SheetRows
+
+   Iterator for rows within a :py:class:`.Sheet` object.  Each iteration returns
+   a tuple of :py:class:`.Cell` objects for the row.
+
diff --git a/doc/python/orcus/tools/bugzilla.rst b/doc/python/orcus/tools/bugzilla.rst
new file mode 100644
index 0000000..53cf869
--- /dev/null
+++ b/doc/python/orcus/tools/bugzilla.rst
@@ -0,0 +1,11 @@
+
+bugzilla
+========
+
+.. argparse::
+   :module: orcus.tools.bugzilla
+   :func: _create_argparser
+   :prog: orcus.tools.bugzilla
+
+.. autoclass:: orcus.tools.bugzilla.BugzillaAccess
+   :members:
diff --git a/doc/python/orcus/tools/file_processor.rst b/doc/python/orcus/tools/file_processor.rst
new file mode 100644
index 0000000..20b7e0a
--- /dev/null
+++ b/doc/python/orcus/tools/file_processor.rst
@@ -0,0 +1,9 @@
+
+file_processor
+==============
+
+.. argparse::
+   :module: orcus.tools.file_processor
+   :func: _create_argparser
+   :prog: orcus.tools.file_processor
+
diff --git a/doc/python/orcus/tools/index.rst b/doc/python/orcus/tools/index.rst
new file mode 100644
index 0000000..0942183
--- /dev/null
+++ b/doc/python/orcus/tools/index.rst
@@ -0,0 +1,10 @@
+
+orcus.tools
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   bugzilla.rst
+   file_processor.rst
+
diff --git a/doc/python/orcus/xls_xml/index.rst b/doc/python/orcus/xls_xml/index.rst
new file mode 100644
index 0000000..e7c07b1
--- /dev/null
+++ b/doc/python/orcus/xls_xml/index.rst
@@ -0,0 +1,25 @@
+
+orcus.xls_xml
+=============
+
+.. py:function:: orcus.xls_xml.read
+
+   Read an Excel file from a specified file path and create a
+   :py:class:`orcus.Document` instance object.  The file must be saved in the
+   SpreadsheetML format.
+
+   :param stream: file object containing byte streams.
+   :param bool recalc: optional parameter specifying whether or not to recalculate
+       the formula cells on load. Defaults to ``False``.
+   :param str error_policy: optional parameter indicating what to do when
+       encountering formula cells with invalid formula expressions. The value
+       must be either ``fail`` or ``skip``.  Defaults to ``fail``.
+   :rtype: :py:class:`orcus.Document`
+   :return: document instance object that stores the content of the file.
+
+   Example::
+
+      from orcus import xls_xml
+
+      with open("path/to/file.xls_xml", "rb") as f:
+          doc = xls_xml.read(f, recalc=True, error_policy="fail")
diff --git a/doc/python/orcus/xlsx/index.rst b/doc/python/orcus/xlsx/index.rst
new file mode 100644
index 0000000..977ea1c
--- /dev/null
+++ b/doc/python/orcus/xlsx/index.rst
@@ -0,0 +1,25 @@
+
+orcus.xlsx
+==========
+
+.. py:function:: orcus.xlsx.read
+
+   Read an Excel file from a specified file path and create a
+   :py:class:`orcus.Document` instance object.  The file must be of Excel 2007
+   XML format.
+
+   :param stream: file object containing byte streams.
+   :param bool recalc: optional parameter specifying whether or not to recalculate
+       the formula cells on load. Defaults to ``False``.
+   :param str error_policy: optional parameter indicating what to do when
+       encountering formula cells with invalid formula expressions. The value
+       must be either ``fail`` or ``skip``.  Defaults to ``fail``.
+   :rtype: :py:class:`orcus.Document`
+   :return: document instance object that stores the content of the file.
+
+   Example::
+
+      from orcus import xlsx
+
+      with open("path/to/file.xlsx", "rb") as f:
+          doc = xlsx.read(f, recalc=True, error_policy="fail")