from __future__ import annotations from typing import ( Any, MutableMapping, ) from pandas.compat._optional import import_optional_dependency from pandas.core.dtypes.common import ( is_integer, is_list_like, ) _writers: MutableMapping[str, str] = {} def register_writer(klass): """ Add engine to the excel writer registry.io.excel. You must use this method to integrate with ``to_excel``. Parameters ---------- klass : ExcelWriter """ if not callable(klass): raise ValueError("Can only register callables as engines") engine_name = klass.engine _writers[engine_name] = klass def get_default_engine(ext, mode="reader"): """ Return the default reader/writer for the given extension. Parameters ---------- ext : str The excel file extension for which to get the default engine. mode : str {'reader', 'writer'} Whether to get the default engine for reading or writing. Either 'reader' or 'writer' Returns ------- str The default engine for the extension. """ _default_readers = { "xlsx": "openpyxl", "xlsm": "openpyxl", "xlsb": "pyxlsb", "xls": "xlrd", "ods": "odf", } _default_writers = { "xlsx": "openpyxl", "xlsm": "openpyxl", "xlsb": "pyxlsb", "xls": "xlwt", "ods": "odf", } assert mode in ["reader", "writer"] if mode == "writer": # Prefer xlsxwriter over openpyxl if installed xlsxwriter = import_optional_dependency("xlsxwriter", errors="warn") if xlsxwriter: _default_writers["xlsx"] = "xlsxwriter" return _default_writers[ext] else: return _default_readers[ext] def get_writer(engine_name): try: return _writers[engine_name] except KeyError as err: raise ValueError(f"No Excel writer '{engine_name}'") from err def _excel2num(x: str) -> int: """ Convert Excel column name like 'AB' to 0-based column index. Parameters ---------- x : str The Excel column name to convert to a 0-based column index. Returns ------- num : int The column index corresponding to the name. Raises ------ ValueError Part of the Excel column name was invalid. """ index = 0 for c in x.upper().strip(): cp = ord(c) if cp < ord("A") or cp > ord("Z"): raise ValueError(f"Invalid column name: {x}") index = index * 26 + cp - ord("A") + 1 return index - 1 def _range2cols(areas: str) -> list[int]: """ Convert comma separated list of column names and ranges to indices. Parameters ---------- areas : str A string containing a sequence of column ranges (or areas). Returns ------- cols : list A list of 0-based column indices. Examples -------- >>> _range2cols('A:E') [0, 1, 2, 3, 4] >>> _range2cols('A,C,Z:AB') [0, 2, 25, 26, 27] """ cols: list[int] = [] for rng in areas.split(","): if ":" in rng: rngs = rng.split(":") cols.extend(range(_excel2num(rngs[0]), _excel2num(rngs[1]) + 1)) else: cols.append(_excel2num(rng)) return cols def maybe_convert_usecols(usecols): """ Convert `usecols` into a compatible format for parsing in `parsers.py`. Parameters ---------- usecols : object The use-columns object to potentially convert. Returns ------- converted : object The compatible format of `usecols`. """ if usecols is None: return usecols if is_integer(usecols): raise ValueError( "Passing an integer for `usecols` is no longer supported. " "Please pass in a list of int from 0 to `usecols` inclusive instead." ) if isinstance(usecols, str): return _range2cols(usecols) return usecols def validate_freeze_panes(freeze_panes): if freeze_panes is not None: if len(freeze_panes) == 2 and all( isinstance(item, int) for item in freeze_panes ): return True raise ValueError( "freeze_panes must be of form (row, column) " "where row and column are integers" ) # freeze_panes wasn't specified, return False so it won't be applied # to output sheet return False def fill_mi_header(row, control_row): """ Forward fill blank entries in row but only inside the same parent index. Used for creating headers in Multiindex. Parameters ---------- row : list List of items in a single row. control_row : list of bool Helps to determine if particular column is in same parent index as the previous value. Used to stop propagation of empty cells between different indexes. Returns ------- Returns changed row and control_row """ last = row[0] for i in range(1, len(row)): if not control_row[i]: last = row[i] if row[i] == "" or row[i] is None: row[i] = last else: control_row[i] = False last = row[i] return row, control_row def pop_header_name(row, index_col): """ Pop the header name for MultiIndex parsing. Parameters ---------- row : list The data row to parse for the header name. index_col : int, list The index columns for our data. Assumed to be non-null. Returns ------- header_name : str The extracted header name. trimmed_row : list The original data row with the header name removed. """ # Pop out header name and fill w/blank. i = index_col if not is_list_like(index_col) else max(index_col) header_name = row[i] header_name = None if header_name == "" else header_name return header_name, row[:i] + [""] + row[i + 1 :] def combine_kwargs(engine_kwargs: dict[str, Any] | None, kwargs: dict) -> dict: """ Used to combine two sources of kwargs for the backend engine. Use of kwargs is deprecated, this function is solely for use in 1.3 and should be removed in 1.4/2.0. Also _base.ExcelWriter.__new__ ensures either engine_kwargs or kwargs must be None or empty respectively. Parameters ---------- engine_kwargs: dict kwargs to be passed through to the engine. kwargs: dict kwargs to be psased through to the engine (deprecated) Returns ------- engine_kwargs combined with kwargs """ if engine_kwargs is None: result = {} else: result = engine_kwargs.copy() result.update(kwargs) return result