openpyxl2 3.2.0b2__py3-none-any.whl

openpyxl/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2010-2025 openpyxl
+
+DEBUG = False
+
+from openpyxl.compat.numbers import NUMPY
+from openpyxl.xml import DEFUSEDXML
+from openpyxl.xml import LXML
+from openpyxl.workbook.workbook import Workbook
+from openpyxl.reader.excel import load_workbook
+import openpyxl._constants as constants
+
+# Expose constants especially the version number
+
+__author__ = constants.__author__
+__author_email__ = constants.__author_email__
+__license__ = constants.__license__
+__maintainer_email__ = constants.__maintainer_email__
+__url__ = constants.__url__
+__version__ = constants.__version__

openpyxl/_constants.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2010-2025 openpyxl
+"""
+Package metadata
+"""
+
+__author__ = "See AUTHORS"
+__author_email__ = "charlie.clark@clark-consulting.eu"
+__license__ = "MIT"
+__maintainer_email__ = "openpyxl-users@googlegroups.com"
+__url__ = "https://openpyxl.pages.heptapod.net/openpyxl/"
+__version__ = "3.2.0b2"
+__python__ = "3.8"

openpyxl/cell/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2010-2025 openpyxl
+from openpyxl.cell.cell import Cell
+from openpyxl.cell.cell import MergedCell
+from openpyxl.cell.cell import WriteOnlyCell
+from openpyxl.cell.read_only import ReadOnlyCell

openpyxl/cell/_writer.py

@@ -0,0 +1,121 @@
+# Copyright (c) 2010-2025 openpyxl
+import datetime
+
+from openpyxl.cell.rich_text import CellRichText
+from openpyxl.compat.strings import safe_string
+from openpyxl.utils.datetime import to_excel
+from openpyxl.utils.datetime import to_ISO8601
+from openpyxl.worksheet.formula import ArrayFormula
+from openpyxl.worksheet.formula import DataTableFormula
+from openpyxl.xml import LXML
+from openpyxl.xml.functions import XML_NS
+from openpyxl.xml.functions import Element
+from openpyxl.xml.functions import SubElement
+from openpyxl.xml.functions import whitespace
+
+
+def _set_attributes(cell, styled=None):
+    """
+    Set coordinate and datatype
+    """
+    coordinate = cell.coordinate
+    attrs = {"r": coordinate}
+    if styled:
+        attrs["s"] = f"{cell.style_id}"
+    if cell.data_type == "s":
+        attrs["t"] = "inlineStr"
+    elif cell.data_type != "f":
+        attrs["t"] = cell.data_type
+    value = cell._value
+    if cell.data_type == "d":
+        if hasattr(value, "tzinfo") and value.tzinfo is not None:
+            raise TypeError(
+                "Excel does not support timezones in datetimes. "
+                "The tzinfo in the datetime/time object must be set to None."
+            )
+        if cell.parent.parent.iso_dates and not isinstance(value, datetime.timedelta):
+            value = to_ISO8601(value)
+        else:
+            attrs["t"] = "n"
+            value = to_excel(value, cell.parent.parent.epoch)
+    if cell.hyperlink:
+        cell.parent._hyperlinks.append(cell.hyperlink)
+    return value, attrs
+
+
+def etree_write_cell(xf, worksheet, cell, styled=None):
+    value, attributes = _set_attributes(cell, styled)
+    el = Element("c", attributes)
+    if value is None or value == "":
+        xf.write(el)
+        return
+    if cell.data_type == "f":
+        attrib = {}
+        if isinstance(value, ArrayFormula):
+            attrib = dict(value)
+            value = value.text
+        elif isinstance(value, DataTableFormula):
+            attrib = dict(value)
+            value = None
+        formula = SubElement(el, "f", attrib)
+        if value is not None and not attrib.get("t") == "dataTable":
+            formula.text = value[1:]
+            value = None
+    if cell.data_type == "s":
+        if isinstance(value, CellRichText):
+            el.append(value.to_tree())
+        else:
+            inline_string = Element("is")
+            text = Element("t")
+            text.text = value
+            whitespace(text)
+            inline_string.append(text)
+            el.append(inline_string)
+    else:
+        cell_content = SubElement(el, "v")
+        if value is not None:
+            cell_content.text = safe_string(value)
+    xf.write(el)
+
+
+def lxml_write_cell(xf, worksheet, cell, styled=False):
+    value, attributes = _set_attributes(cell, styled)
+    if value == "" or value is None:
+        with xf.element("c", attributes):
+            return
+    with xf.element("c", attributes):
+        if cell.data_type == "f":
+            attrib = {}
+            if isinstance(value, ArrayFormula):
+                attrib = dict(value)
+                value = value.text
+            elif isinstance(value, DataTableFormula):
+                attrib = dict(value)
+                value = None
+            with xf.element("f", attrib):
+                if value is not None and not attrib.get("t") == "dataTable":
+                    xf.write(value[1:])
+                    value = None
+        if cell.data_type == "s":
+            if isinstance(value, CellRichText):
+                el = value.to_tree()
+                xf.write(el)
+            else:
+                with xf.element("is"):
+                    if isinstance(value, str):
+                        attrs = {}
+                        if value != value.strip():
+                            attrs[f"{{{XML_NS}}}space"] = "preserve"
+                        el = Element("t", attrs)  # lxml can't handle xml-ns
+                        el.text = value
+                        xf.write(el)
+        else:
+            with xf.element("v"):
+                if value is not None:
+                    xf.write(safe_string(value))
+
+
+if LXML:
+    write_cell = lxml_write_cell
+else:
+    write_cell = etree_write_cell

openpyxl/cell/cell.py

@@ -0,0 +1,417 @@
+# Copyright (c) 2010-2025 openpyxl
+"""Manage individual cells in a spreadsheet.
+
+The Cell class is required to know its value and type, display options,
+and any other features of an Excel cell.  Utilities for referencing
+cells using Excel's 'A1' column/row nomenclature are also provided.
+
+"""
+import copy
+import datetime
+import re
+
+from openpyxl.cell.coordinate import Coordinate
+from openpyxl.cell.rich_text import CellRichText
+from openpyxl.compat.numbers import NUMERIC_TYPES
+from openpyxl.styles.alignment import Alignment
+from openpyxl.styles.borders import Border
+from openpyxl.styles.fills import PatternFill
+from openpyxl.styles.fonts import Font
+from openpyxl.styles.numbers import FORMAT_DATE_DATETIME
+from openpyxl.styles.numbers import FORMAT_DATE_TIME6
+from openpyxl.styles.numbers import FORMAT_DATE_TIMEDELTA
+from openpyxl.styles.numbers import FORMAT_DATE_YYYYMMDD2
+from openpyxl.styles.numbers import FORMAT_GENERAL
+from openpyxl.styles.numbers import is_date_format
+from openpyxl.styles.protection import Protection
+from openpyxl.styles.styleable import NamedStyleDescriptor
+from openpyxl.styles.styleable import StyleableObject
+from openpyxl.utils.exceptions import IllegalCharacterError
+from openpyxl.worksheet.formula import ArrayFormula
+from openpyxl.worksheet.formula import DataTableFormula
+from openpyxl.worksheet.hyperlink import Hyperlink
+
+TIME_TYPES = (datetime.datetime, datetime.date, datetime.time, datetime.timedelta)
+TIME_FORMATS = {
+    datetime.datetime: FORMAT_DATE_DATETIME,
+    datetime.date: FORMAT_DATE_YYYYMMDD2,
+    datetime.time: FORMAT_DATE_TIME6,
+    datetime.timedelta: FORMAT_DATE_TIMEDELTA,
+}
+STRING_TYPES = (str, bytes, CellRichText)
+KNOWN_TYPES = NUMERIC_TYPES + TIME_TYPES + STRING_TYPES + (bool, type(None))
+ILLEGAL_CHARACTERS_RE = re.compile(r"[\000-\010]|[\013-\014]|[\016-\037]")
+ERROR_CODES = ("#NULL!", "#DIV/0!", "#VALUE!", "#REF!", "#NAME?", "#NUM!", "#N/A")
+TYPE_STRING = "s"
+TYPE_FORMULA = "f"
+TYPE_NUMERIC = "n"
+TYPE_BOOL = "b"
+TYPE_NULL = "n"
+TYPE_INLINE = "inlineStr"
+TYPE_ERROR = "e"
+TYPE_FORMULA_CACHE_STRING = "str"
+VALID_TYPES = (
+    TYPE_STRING,
+    TYPE_FORMULA,
+    TYPE_NUMERIC,
+    TYPE_BOOL,
+    TYPE_NULL,
+    TYPE_INLINE,
+    TYPE_ERROR,
+    TYPE_FORMULA_CACHE_STRING,
+)
+_TYPES = {int: "n", float: "n", str: "s", bool: "b"}
+
+
+def get_type(t, value):
+    if isinstance(value, NUMERIC_TYPES):
+        dt = "n"
+    elif isinstance(value, STRING_TYPES):
+        dt = "s"
+    elif isinstance(value, TIME_TYPES):
+        dt = "d"
+    elif isinstance(value, (DataTableFormula, ArrayFormula)):
+        dt = "f"
+    else:
+        return None
+    _TYPES[t] = dt
+    return dt
+
+
+def get_time_format(t):
+    value = TIME_FORMATS.get(t)
+    if value:
+        return value
+    for base in t.mro()[1:]:
+        value = TIME_FORMATS.get(base)
+        if value:
+            TIME_FORMATS[t] = value
+            return value
+    raise ValueError(f"Could not get time format for {value!r}")
+
+
+class Cell(StyleableObject):
+    """Describes cell associated properties.
+
+    Properties of interest include style, type, value, and address.
+
+    """
+
+    __slots__ = ("_coord", "_value", "data_type", "parent", "_hyperlink", "_comment")
+
+    def __init__(self, worksheet, row=None, column=None, value=None, style_array=None):
+        super().__init__(worksheet, style_array)
+        self._coord = Coordinate(row, column)  # 1-based index
+        self._value = None
+        self._hyperlink = None
+        self.data_type = "n"
+        if value is not None:
+            self.value = value
+        self._comment = None
+
+    @property
+    def column(self):
+        return self._coord.column
+
+    col_idx = column
+
+    @property
+    def row(self):
+        return self._coord.row
+
+    @property
+    def coordinate(self):
+        """This cell's coordinate (ex. 'A5')"""
+        return str(self._coord)
+
+    @property
+    def column_letter(self):
+        return self._coord.column_letter
+
+    @property
+    def encoding(self):
+        return self.parent.encoding
+
+    @property
+    def base_date(self):
+        return self.parent.parent.epoch
+
+    def __repr__(self):
+        return f"<Cell {self.parent.title!r}.{self.coordinate}>"
+
+    def check_string(self, value):
+        """Check string coding, length, and line break character"""
+        if value is None:
+            return None
+        # convert to str string
+        if not isinstance(value, str):
+            value = str(value, self.encoding)
+        value = str(value)
+        # string must never be longer than 32,767 characters
+        # truncate if necessary
+        value = value[:32767]
+        if next(ILLEGAL_CHARACTERS_RE.finditer(value), None):
+            raise IllegalCharacterError(f"{value} cannot be used in worksheets.")
+        return value
+
+    def check_error(self, value):
+        """Tries to convert Error" else N/A"""
+        try:
+            return str(value)
+        except UnicodeDecodeError:
+            return "#N/A"
+
+    @property
+    def value(self):
+        """Get or set the value held in the cell.
+
+        :type: depends on the value (string, float, int or
+            :class:`datetime.datetime`)
+        """
+        return self._value
+
+    @value.setter
+    def value(self, value):
+        """Set the value and infer type and display options."""
+        self.data_type = "n"
+        t = type(value)
+        try:
+            dt = _TYPES[t]
+        except KeyError:
+            dt = get_type(t, value)
+
+        if dt is None and value is not None:
+            raise ValueError(f"Cannot convert {value!r} to Excel")
+        if dt:
+            self.data_type = dt
+        if dt == "d":
+            if not is_date_format(self.number_format):
+                self.number_format = get_time_format(t)
+        elif dt == "s" and not isinstance(value, CellRichText):
+            value = self.check_string(value)
+            if len(value) > 1 and value.startswith("="):
+                self.data_type = "f"
+            elif value in ERROR_CODES:
+                self.data_type = "e"
+        self._value = value
+
+    @property
+    def hyperlink(self):
+        """Return the hyperlink target or an empty string"""
+        return self._hyperlink
+
+    @hyperlink.setter
+    def hyperlink(self, val):
+        """Set value and display for hyperlinks in a cell.
+        Automatically sets the `value` of the cell with link text,
+        but you can modify it afterward by setting the `value`
+        property, and the hyperlink will remain.
+        Hyperlink is removed if set to ``None``."""
+        if val is None:
+            self._hyperlink = None
+        else:
+            if not isinstance(val, Hyperlink):
+                val = Hyperlink(ref="", target=val)
+            val.ref = self.coordinate
+            self._hyperlink = val
+            if self._value is None:
+                self.value = val.target or val.location
+
+    @property
+    def is_date(self):
+        """True if the value is formatted as a date
+
+        :type: bool
+        """
+        con1 = self.data_type == "d"
+        con2 = self.data_type == "n" and is_date_format(self.number_format)
+        return con1 or con2
+
+    def offset(self, row=0, column=0):
+        """Returns a cell location relative to this cell.
+
+        :param row: number of rows to offset
+        :type row: int
+
+        :param column: number of columns to offset
+        :type column: int
+
+        :rtype: :class:`openpyxl.cell.Cell`
+        """
+        row = self._coord.row + row
+        column = self._coord.column + column
+        return self.parent.cell(row=row, column=column)
+
+    @property
+    def comment(self):
+        """Returns the comment associated with this cell
+
+        :type: :class:`openpyxl.comments.Comment`
+        """
+        return self._comment
+
+    @comment.setter
+    def comment(self, value):
+        """
+        Assign a comment to a cell
+        """
+
+        if value is not None:
+            if value.parent:
+                value = copy.copy(value)
+            value.bind(self)
+        elif value is None and self._comment:
+            self._comment.unbind()
+        self._comment = value
+
+    def set_style_to_merged_cells(self, key, value):
+        if not hasattr(self.parent, "merged_cells"):
+            return
+        for merged in self.parent.merged_cells:
+            if (self.row, self.column) != (merged.min_row, merged.min_col):
+                continue
+            if key == "border":
+                merged._apply_border(value)
+                return
+            for row, column in merged.cells:
+                cell = self.parent._cells[(row, column)]
+                if cell is self:
+                    continue
+                if key == "style":
+                    NamedStyleDescriptor().__set__(cell, value)
+                else:
+                    setattr(cell, key, value)
+            if key == "style":
+                merged._apply_border(copy.copy(self.border))
+            return
+
+    @property
+    def alignment(self):
+        return self._alignment
+
+    @alignment.setter
+    def alignment(self, value):
+        self._alignment = value
+        self.set_style_to_merged_cells("alignment", value)
+
+    @alignment.deleter
+    def alignment(self):
+        self._alignment = Alignment()
+        self.set_style_to_merged_cells("alignment", Alignment())
+
+    @property
+    def border(self):
+        return self._border
+
+    @border.setter
+    def border(self, value):
+        self._border = value
+        self.set_style_to_merged_cells("border", value)
+
+    @border.deleter
+    def border(self):
+        self._border = Border()
+        self.set_style_to_merged_cells("border", Border())
+
+    @property
+    def fill(self):
+        return self._fill
+
+    @fill.setter
+    def fill(self, value):
+        self._fill = value
+        self.set_style_to_merged_cells("fill", value)
+
+    @fill.deleter
+    def fill(self):
+        self._fill = PatternFill()
+        self.set_style_to_merged_cells("fill", PatternFill())
+
+    @property
+    def font(self):
+        return self._font
+
+    @font.setter
+    def font(self, value):
+        self._font = value
+        self.set_style_to_merged_cells("font", value)
+
+    @font.deleter
+    def font(self):
+        self._font = Font()
+        self.set_style_to_merged_cells("font", Font())
+
+    @property
+    def number_format(self):
+        return self._number_format
+
+    @number_format.setter
+    def number_format(self, value):
+        self._number_format = value
+        self.set_style_to_merged_cells("number_format", value)
+
+    @number_format.deleter
+    def number_format(self):
+        self._number_format = FORMAT_GENERAL
+        self.set_style_to_merged_cells("number_format", FORMAT_GENERAL)
+
+    @property
+    def protection(self):
+        return self._protection
+
+    @protection.setter
+    def protection(self, value):
+        self._protection = value
+        self.set_style_to_merged_cells("protection", value)
+
+    @protection.deleter
+    def protection(self):
+        self._protection = Protection()
+        self.set_style_to_merged_cells("protection", Protection())
+
+    @property
+    def style(self):
+        return NamedStyleDescriptor().__get__(self, None)
+
+    @style.setter
+    def style(self, value):
+        NamedStyleDescriptor().__set__(self, value)
+        self.set_style_to_merged_cells("style", value)
+
+    @style.deleter
+    def style(self):
+        NamedStyleDescriptor().__set__(self, "Normal")
+        self.set_style_to_merged_cells("style", "Normal")
+
+
+class MergedCell(StyleableObject):
+    """
+    Describes the properties of a cell in a merged cell and helps to
+    display the borders of the merged cell.
+
+    The value of a MergedCell is always None.
+    """
+
+    __slots__ = ("_coord",)
+
+    _value = None
+    data_type = "n"
+    comment = None
+    hyperlink = None
+
+    def __init__(self, worksheet, row=None, column=None):
+        super().__init__(worksheet)
+        self._coord = Coordinate(row, column)
+
+    def __repr__(self):
+        return f"<MergedCell {self.parent.title!r}.{self.coordinate}>"
+
+    coordinate = Cell.coordinate
+    row = Cell.row
+    column = Cell.column
+    _comment = comment
+    value = _value
+
+
+def WriteOnlyCell(ws=None, value=None):
+    return Cell(worksheet=ws, column=1, row=1, value=value)

openpyxl/cell/coordinate.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2010-2025 openpyxl
+"""
+Represent a cell's coordinate in any collection
+"""
+from openpyxl.utils.cell import coordinate_to_tuple
+from openpyxl.utils.cell import get_column_letter
+
+
+class Coordinate:
+    __slots__ = ("row", "column")
+
+    def __init__(self, row, column):
+        self.row = row
+        self.column = column
+
+    def __str__(self):
+        return f"{get_column_letter(self.column)}{self.row}"
+
+    @property
+    def column_letter(self):
+        return get_column_letter(self.column)
+
+    @classmethod
+    def from_string(cls, coord):
+        row, column = coordinate_to_tuple(coord)
+        return cls(row, column)
+
+    def __eq__(self, other):
+        return self.row == other.row and self.column == other.column
+
+    def __ne__(self, other):
+        return not self == other

openpyxl/cell/read_only.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2010-2025 openpyxl
+from openpyxl.cell.cell import Cell
+from openpyxl.cell.coordinate import Coordinate
+from openpyxl.styles.numbers import BUILTIN_FORMATS
+from openpyxl.styles.numbers import BUILTIN_FORMATS_MAX_SIZE
+
+
+class ReadOnlyCell:
+    __slots__ = ("parent", "_coord", "_value", "data_type", "_style_id")
+
+    def __init__(self, sheet, row, column, value, data_type="n", style_id=0):
+        self.parent = sheet
+        self._value = None
+        self._coord = Coordinate(row, column)
+        self.data_type = data_type
+        self._value = value
+        self._style_id = style_id
+
+    def __eq__(self, other):
+        for a in self.__slots__:
+            if getattr(self, a) != getattr(other, a):
+                return False
+        return True
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __repr__(self):
+        return f"<ReadOnlyCell {self.parent.title!r}.{self.coordinate}>"
+
+    row = Cell.row
+    column = Cell.column
+    column_letter = Cell.column_letter
+    coordinate = Cell.coordinate
+    is_date = Cell.is_date
+
+    @property
+    def style_array(self):
+        return self.parent.parent._cell_styles[self._style_id]
+
+    @property
+    def has_style(self):
+        return self._style_id != 0
+
+    @property
+    def number_format(self):
+        _id = self.style_array.numFmtId
+        if _id < BUILTIN_FORMATS_MAX_SIZE:
+            return BUILTIN_FORMATS.get(_id, "General")
+        else:
+            return self.parent.parent._number_formats[_id - BUILTIN_FORMATS_MAX_SIZE]
+
+    @property
+    def font(self):
+        _id = self.style_array.fontId
+        return self.parent.parent._fonts[_id]
+
+    @property
+    def fill(self):
+        _id = self.style_array.fillId
+        return self.parent.parent._fills[_id]
+
+    @property
+    def border(self):
+        _id = self.style_array.borderId
+        return self.parent.parent._borders[_id]
+
+    @property
+    def alignment(self):
+        _id = self.style_array.alignmentId
+        return self.parent.parent._alignments[_id]
+
+    @property
+    def protection(self):
+        _id = self.style_array.protectionId
+        return self.parent.parent._protections[_id]
+
+    @property
+    def value(self):
+        return self._value
+
+
+class EmptyCell:
+    __slots__ = ()
+    value = None
+    is_date = False
+    font = None
+    border = None
+    fill = None
+    number_format = None
+    alignment = None
+    data_type = "n"
+
+    def __repr__(self):
+        return "<EmptyCell>"
+
+
+EMPTY_CELL = EmptyCell()