gnumeric 0.1.0__tar.gz

gnumeric-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: gnumeric
+Version: 0.1.0
+Summary: A python library for reading and writing Gnumeric files
+Author: Michael Lipschultz
+Author-email: Michael Lipschultz <michael.lipschultz@gmail.com>
+License-Expression: GPL-3.0-only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Requires-Dist: lxml>=6.1.1,<7
+Requires-Dist: python-dateutil>=2.9.0.post0,<3
+Requires-Dist: lark>=1.3.1,<2
+Requires-Python: >=3.11, <4
+Project-URL: Homepage, https://github.com/lipschultz/gnumeric-py
+Description-Content-Type: text/markdown
+
+# Gnumeric-py
+
+A python library for reading and writing [Gnumeric](http://www.gnumeric.org/) files.
+
+## Quick Start
+
+Open an existing workbook and explore what's available:
+
+```python
+from gnumeric.workbook import Workbook
+
+wb = Workbook.load_workbook('samples/test.gnumeric')
+
+# Get the active sheet
+ws = wb.get_active_sheet()  # can also use wb.active
+
+# Get a sheet by name
+ws_1 = wb.get_sheet_by_name('Sheet1')
+
+# Get cell at A1
+cell_a1 = ws['A1']
+cell_a1 = ws[(0, 0)]  # zero-indexed (row, column)
+
+# Get the value in the cell
+cell_a1.get_value()
+```
+
+## Unsupported Features
+
+Currently, this library does not support:
+
+1. Evaluating almost all expressions
+2. Graphs

gnumeric-0.1.0/README.md

@@ -0,0 +1,33 @@
+# Gnumeric-py
+
+A python library for reading and writing [Gnumeric](http://www.gnumeric.org/) files.
+
+## Quick Start
+
+Open an existing workbook and explore what's available:
+
+```python
+from gnumeric.workbook import Workbook
+
+wb = Workbook.load_workbook('samples/test.gnumeric')
+
+# Get the active sheet
+ws = wb.get_active_sheet()  # can also use wb.active
+
+# Get a sheet by name
+ws_1 = wb.get_sheet_by_name('Sheet1')
+
+# Get cell at A1
+cell_a1 = ws['A1']
+cell_a1 = ws[(0, 0)]  # zero-indexed (row, column)
+
+# Get the value in the cell
+cell_a1.get_value()
+```
+
+## Unsupported Features
+
+Currently, this library does not support:
+
+1. Evaluating almost all expressions
+2. Graphs

gnumeric-0.1.0/gnumeric/.constants.json

@@ -0,0 +1,8 @@
+{
+    "__author__": "Michael Lipschultz",
+    "__author_email__": "michael.lipschultz@gmail.com",
+    "__license__": "GPL v3",
+    "__maintainer_email__": "michael.lipschultz@gmail.com",
+    "__url__": "https://github.com/lipschultz/gnumeric-py",
+    "__version__": "0.0.1"
+}

gnumeric-0.1.0/gnumeric/__init__.py

@@ -0,0 +1,41 @@
+"""
+Gnumeric-py: Reading and writing gnumeric files with python
+Copyright (C) 2017 Michael Lipschultz
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+
+import json
+import os
+
+try:
+    here = os.path.abspath(os.path.dirname(__file__))
+    src_file = os.path.join(here, '.constants.json')
+    with open(src_file) as src:
+        constants = json.load(src)
+        __author__ = constants['__author__']
+        __author_email__ = constants['__author_email__']
+        __license__ = constants['__license__']
+        __maintainer_email__ = constants['__maintainer_email__']
+        __url__ = constants['__url__']
+        __version__ = constants['__version__']
+except IOError:
+    # packaged
+    pass
+
+from gnumeric.workbook import Workbook
+
+
+def load_workbook(filepath):
+    return Workbook.load_workbook(filepath)

gnumeric-0.1.0/gnumeric/cell.py

@@ -0,0 +1,294 @@
+"""
+Gnumeric-py: Reading and writing gnumeric files with python
+Copyright (C) 2017 Michael Lipschultz
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+
+import datetime
+from typing import Optional, Union
+
+from lxml import etree
+
+from gnumeric.exceptions import UnrecognizedCellTypeException
+from gnumeric.expression import Expression
+from gnumeric.utils import RowColReference
+
+VALUE_TYPE_EXPR = -10
+VALUE_TYPE_EMPTY = 10
+VALUE_TYPE_BOOLEAN = 20
+VALUE_TYPE_INTEGER = 30
+VALUE_TYPE_FLOAT = 40
+VALUE_TYPE_ERROR = 50
+VALUE_TYPE_STRING = 60
+VALUE_TYPE_CELLRANGE = 70
+VALUE_TYPE_ARRAY = 80
+
+
+class Cell:
+    _instances = {}
+
+    _BASE_DATETIME = datetime.datetime(1899, 12, 30)
+
+    def __new__(cls, cell_element, style_region_element, worksheet, ns):
+        key = (cell_element, style_region_element, worksheet)
+        instance = cls._instances.get(key)
+        if not instance:
+            instance = super(Cell, cls).__new__(cls)
+            instance.__cached_value = None
+            instance.__time_cached_value_set = None
+            cls._instances[key] = instance
+        return instance
+
+    def __init__(self, cell_element, style_region_element, worksheet, ns):
+        self.__cell = cell_element
+        self.__style_region = style_region_element
+        self.__worksheet = worksheet
+        self.__ns = ns
+
+    def __get_style_element(self):
+        elements = self.__style_region.xpath('./gnm:Style', namespaces=self.__ns)
+        return elements[0] if elements else None
+
+    def __set_expression_id(self, expr_id: str) -> None:
+        self.__cell.set('ExprID', expr_id)
+
+    @property
+    def worksheet(self):
+        """
+        The worksheet this cell belongs to.
+        """
+        return self.__worksheet
+
+    @property
+    def column(self) -> int:
+        """
+        The column this cell belongs to (0-indexed).
+        """
+        return int(self.__cell.get('Col'))
+
+    @property
+    def row(self) -> int:
+        """
+        The row this cell belongs to (0-indexed).
+        """
+        return int(self.__cell.get('Row'))
+
+    @property
+    def coordinate(self) -> RowColReference:
+        """
+        The (row, column) of the cell (0-indexed)
+        """
+        return RowColReference(self.row, self.column)
+
+    @property
+    def text(self) -> Optional[str]:
+        """
+        Returns the raw value stored in the cell.  The text will be `None` if the cell is empty.
+        :return: str or `None`
+        """
+        return self.__cell.text
+
+    @property
+    def value_type(self) -> int:
+        """
+        Returns the type of value stored in the cell:
+         - VALUE_TYPE_EXPR = -10
+         - VALUE_TYPE_EMPTY = 10
+         - VALUE_TYPE_BOOLEAN = 20
+         - VALUE_TYPE_INTEGER = 30
+         - VALUE_TYPE_FLOAT = 40
+         - VALUE_TYPE_ERROR = 50
+         - VALUE_TYPE_STRING = 60
+         - VALUE_TYPE_CELLRANGE = 70
+         - VALUE_TYPE_ARRAY = 80
+        """
+        value_type = self.__cell.get('ValueType')
+        if value_type is not None:
+            return int(value_type)
+        elif self.__cell.get('ExprID') is not None or self.text.startswith('='):
+            return VALUE_TYPE_EXPR
+        else:
+            raise UnrecognizedCellTypeException(
+                'Cell is: "' + str(etree.tostring(self.__cell)) + '"'
+            )
+
+    def is_datetime(self) -> bool:
+        return (
+            self.value_type == VALUE_TYPE_FLOAT
+            and self.__cell.get('ValueFormat') == 'yyyy-mmm-dd'
+        )
+
+    def __set_type(self, value_type: int):
+        if value_type == VALUE_TYPE_EXPR:
+            if 'ValueType' in self.__cell.keys():
+                self.__cell.attrib.pop('ValueType')
+        else:
+            self.__cell.set('ValueType', str(value_type))
+
+    def get_value(
+        self, *, compute_expression: bool = False
+    ) -> Union[bool, int, float, Expression, str]:
+        """
+        Gets the value stored in the cell, converted into the appropriate Python datatype when possible.
+
+        If the cell is an expression: If `compute_expression` is True, the the result of the expression
+        is returned, otherwise an Expression object is returned.
+        """
+        value = self.text
+        if self.value_type == VALUE_TYPE_BOOLEAN:
+            return value.lower() == 'true'
+        elif self.value_type == VALUE_TYPE_INTEGER:
+            return int(value)
+        elif self.value_type == VALUE_TYPE_FLOAT:
+            return float(value)
+        elif self.value_type == VALUE_TYPE_EXPR:
+            expression = Expression(self.__cell.get('ExprID'), self.__worksheet, self)
+            if not compute_expression:
+                return expression
+            else:
+                if self.__cached_value is None:
+                    self.__cached_value = 0
+                    self.__cached_value = expression.value
+                return self.__cached_value
+        else:
+            return value
+
+    def set_value(self, value, *, value_type: str = 'infer') -> None:
+        """
+        Sets the value stored in the cell.
+
+        If `value_type` is:
+        - one of the `VALUE_TYPE_` constants, then that value type will be used
+        - ``keep'`, then the cell will keep its type
+        - `'infer'`, then it tries to guess the type based on the value being set:
+            - if `value` is of type `bool`, then `VALUE_TYPE_BOOLEAN`
+            - if `value` is of type `int`, then `VALUE_TYPE_INTEGER`
+            - if `value` is of type `float`, then `VALUE_TYPE_FLOAT`
+            - if `value` is an empty string or `None`, then `VALUE_TYPE_EMPTY`
+            - if `value` is a string that starts with `=` or is an `Expression` object, then `VALUE_TYPE_EXPR`
+            - if `value` is anything else, then `VALUE_TYPE_STRING`
+
+        The default `value_type` is `'infer'`.
+
+        Warning: This method does no type checking, so it is possible to save a string into a cell whose type is
+        `VALUE_TYPE_INTEGER`.  This could result in problems when opening the workbook in Gnumeric.
+        """
+        val_types = {
+            bool: VALUE_TYPE_BOOLEAN,
+            int: VALUE_TYPE_INTEGER,
+            float: VALUE_TYPE_FLOAT,
+        }
+        if value_type == 'infer':
+            if type(value) in val_types:
+                value_type = val_types[type(value)]
+            elif value in ('', None):
+                value_type = VALUE_TYPE_EMPTY
+            elif isinstance(value, Expression) or value[0] == '=':
+                value_type = VALUE_TYPE_EXPR
+            elif self.value_type in (
+                VALUE_TYPE_EMPTY,
+                VALUE_TYPE_BOOLEAN,
+                VALUE_TYPE_INTEGER,
+                VALUE_TYPE_FLOAT,
+                VALUE_TYPE_ERROR,
+            ):
+                value_type = VALUE_TYPE_STRING
+            else:
+                value_type = self.value_type
+        elif value_type == 'keep':
+            value_type = self.value_type
+
+        if value_type == VALUE_TYPE_BOOLEAN:
+            self.__cell.text = str(bool(value)).upper()
+        elif value_type == VALUE_TYPE_EMPTY:
+            self.__cell.text = None
+        elif value_type == VALUE_TYPE_EXPR and isinstance(value, Expression):
+            if self.__worksheet != value.worksheet:
+                raise NotImplementedError(
+                    'Copying expression to different worksheet is not yet supported'
+                )  # TODO
+
+            expr_id = str(value.id)
+            if (
+                expr_id not in self.__worksheet.get_expression_map()
+                and value.id is None
+            ):
+                expr_id = str(
+                    max(int(k) for k in self.__worksheet.get_expression_map()) + 1
+                )
+
+            if len(value.get_all_cells()) == 1 and value.get_originating_cell() == self:
+                # copying expression over itself, so don't add it to cells using this expression
+                self.__cell.text = value.value
+            else:
+                # the expression is shared, so use the expression id
+                if len(value.get_all_cells()) == 1:
+                    value.get_originating_cell().__set_expression_id(expr_id)
+                self.__cell.text = None
+                self.__set_expression_id(expr_id)
+        else:
+            self.__cell.text = str(value)
+
+        self.__set_type(value_type)
+        self.__cached_value = self.get_value(compute_expression=True)
+
+    value = property(
+        get_value,
+        set_value,
+        doc='Get or set the value in the cell, converted into the correct type.',
+    )
+
+    @property
+    def result(self):
+        """
+        Gets the result of the cell.  For expressions, it returns the result of the expression.  For literals, it returns the literal.
+        """
+        value = self.get_value(compute_expression=True)
+        if value is None:
+            value = 0
+        elif self.is_datetime():
+            value = self._BASE_DATETIME + datetime.timedelta(days=value)
+        return value
+
+    @property
+    def text_format(self) -> str:
+        """
+        The format string used to format the text in the cell for display.  This is the "Number Format" in Gnumeric.
+        """
+        return str(
+            self.__style_region.xpath('./gnm:Style/@Format', namespaces=self.__ns)[0]
+        )
+
+    def __str__(self) -> str:
+        return repr(self.value)
+
+    def __repr__(self) -> str:
+        return 'Cell[%s, (%d, %d), ws="%s"]' % (
+            str(self),
+            self.row,
+            self.column,
+            self.__worksheet.title,
+        )
+
+    def __eq__(self, other) -> bool:
+        return (
+            isinstance(other, Cell)
+            and self.__worksheet == other.__worksheet
+            and self.row == other.row
+            and self.column == other.column
+        )
+
+    def __hash__(self) -> int:
+        return hash(self.__cell)

gnumeric-0.1.0/gnumeric/evaluation_errors.py

@@ -0,0 +1,24 @@
+import enum
+
+
+class EvaluationError(enum.Enum):
+    DIV0 = '#DIV/0!'
+    VALUE = '#VALUE!'
+    NA = '#N/A'
+    NAME = '#NAME?'
+    NUM = '#NUM!'  # =10000000000^1000000000
+    REF = '#REF!'
+    NULL = (
+        '#NULL!'  # occurs when the intersection of two areas don't actually intersect
+    )
+
+
+class ExpressionEvaluationException(Exception):
+    """
+    Evaulating the expression has failed.
+    """
+
+    def __init__(self, error: EvaluationError, msg=None):
+        msg = msg or error.value
+        super().__init__(msg)
+        self.error = error

gnumeric-0.1.0/gnumeric/exceptions.py

@@ -0,0 +1,49 @@
+"""
+Gnumeric-py: Reading and writing gnumeric files with python
+Copyright (C) 2017 Michael Lipschultz
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+
+
+class DuplicateTitleException(Exception):
+    """
+    A workbook cannot contain multiple sheets with the same name/title.
+    """
+
+    def __init__(self, msg):
+        super().__init__(msg)
+
+
+class WrongWorkbookException(Exception):
+    """
+    A sheet or cell from one workbook being using in another workbook.
+    """
+
+    def __init__(self, msg):
+        super().__init__(msg)
+
+
+class UnsupportedOperationException(Exception):
+    def __init__(self, msg):
+        super().__init__(msg)
+
+
+class UnrecognizedCellTypeException(Exception):
+    """
+    The type of cell cannot be determined.
+    """
+
+    def __init__(self, msg):
+        super().__init__(msg)

gnumeric-0.1.0/gnumeric/expression.py

@@ -0,0 +1,151 @@
+"""
+Gnumeric-py: Reading and writing gnumeric files with python
+Copyright (C) 2017 Michael Lipschultz
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+
+from typing import Set, Union
+
+from gnumeric import expression_evaluation, utils
+from gnumeric.evaluation_errors import EvaluationError
+
+
+class Expression:
+    # TODO: what to do if originating cell's text changes or is deleted?
+
+    def __init__(self, id, worksheet, cell):
+        """
+        :param cell: The cell this Expression was created from.  It could be the originating cell or just a cell that
+            uses this expression.  It's used when `id` is `None` (i.e. the expression isn't shared between cells).
+        """
+        self.__exprid = id
+        self.__worksheet = worksheet
+        self.__cell = cell
+
+    def __get_raw_originating_cell(self):
+        """
+        Returns a (int, int, str) tuple, where the values are (row, column, text of the cell).
+        """
+        if self.__exprid is not None:
+            coords, text = self.__worksheet.get_expression_map()[self.__exprid]
+            return int(coords[0]), int(coords[1]), text
+        else:
+            return self.__cell.row, self.__cell.column, self.__cell.text
+
+    @property
+    def id(self):
+        """
+        The expression id used to uniquely identify the expression within the sheet.  This will be `None` if the
+        expression isn't shared between cells.
+        """
+        return self.__exprid
+
+    @property
+    def original_text(self) -> str:
+        """
+        Returns the text of the expression, with cell references from the perspective of the cell where the expression
+        is stored (i.e. the original cell).
+        """
+        return self.__get_raw_originating_cell()[2]
+
+    @property
+    def text(self):
+        """
+        Returns the text of the exprsesion, with cell references updated to be from the perspective of the cell using the expression.
+        """
+        # TODO: fix this to actually return what it's supposed to
+        raise NotImplementedError
+
+    @property
+    def reference_coordinate_offset(self) -> utils.RowColReference:
+        """
+        The (row, col) offset to translate the original coordinates into the coordinates based at the current cell.
+        """
+        original_coordinates = self.get_originating_cell_coordinate()
+        current_coordinates = self.__cell.coordinate
+        return utils.RowColReference(
+            current_coordinates[0] - original_coordinates[0],
+            current_coordinates[1] - original_coordinates[1],
+        )
+
+    @property
+    def value(self):
+        """
+        Returns the result of the expression's evaluation.
+        """
+        return expression_evaluation.evaluate(self.original_text, self.__cell)
+
+    @property
+    def worksheet(self):
+        """
+        The worksheet this expression is created in.
+        """
+        return self.__worksheet
+
+    def get_originating_cell_coordinate(
+        self, representation_format='index'
+    ) -> Union[utils.RowColReference, str]:
+        """
+        Returns the cell coordinate for the cell Gnumeric is using to store the expression.
+
+        :param representation_format: For spreadsheet notation, use `'spreadsheet'`, for 0-indexed (row, column)
+            notation, use 'index' (default).
+        :return: A `str` if `representation_format` is `'spreadsheet'` and a tuple of ints `(int, int)` if 'index'.
+        """
+        row, col = self.__get_raw_originating_cell()[:2]
+        if representation_format == 'index':
+            return utils.RowColReference(row, col)
+        elif representation_format == 'spreadsheet':
+            return utils.coordinate_to_spreadsheet(row, col)
+
+    def get_originating_cell(self):
+        """
+        Returns the cell Gnumeric is using to store the expression.
+        """
+        return self.__worksheet.cell(
+            *self.get_originating_cell_coordinate(), create=False
+        )
+
+    def get_all_cells(self, sort=False):
+        """
+        Returns a list of all cells using this expression.
+
+        Use `sort` to specify whether the cells should be sorted.  If `False` (default), then no sorting will take
+        place.  If `sort` is `"row"`, then sorting will occur by row first, then by column within each row.  If `sort`
+        is `"column"`, then the opposite will happen: first sort by column, then by row within each column.
+        """
+        if self.__exprid is None:
+            return [self.__cell]
+        else:
+            return self.__worksheet.get_all_cells_with_expression(
+                self.__exprid, sort=sort
+            )
+
+    def get_referenced_cells(self) -> Union[Set, EvaluationError]:
+        return expression_evaluation.get_referenced_cells(
+            self.original_text, self.__cell
+        )
+
+    def __str__(self):
+        return self.original_text
+
+    def __repr__(self):
+        return 'Expression(id=%s, text="%s", ws=%s, cell=(%d, %d))' % (
+            self.id,
+            self.original_text,
+            self.__worksheet,
+            self.__cell.row,
+            self.__cell.column,
+        )