pd.ExcelWriter: Source Code

Walkthrough

This code snippet is part of a class called ExcelWriter and seems to be defining a framework for writing data into Excel files. Let's walk through the main components and functions in this code:

1. Class Definition: The code starts with the definition of the ExcelWriter class. It uses the metaclass abc.ABCMeta which indicates that this class is an abstract base class and should not be instantiated directly. It provides a common interface for different concrete implementations of Excel writing engines.
2. Class Attributes:
   • _engine (str): The name of the engine being used for writing Excel files.
   • _supported_extensions (tuple[str, ...]): A tuple of supported file extensions for the chosen engine.
3. __new__ Method: This method is responsible for creating a new instance of the class. It takes various arguments including path, engine, date_format, etc. It determines the appropriate engine to use based on the given file extension and the default engine for that extension. It handles switching to a specific writer class based on the chosen engine.
4. Properties:
   • supported_extensions (property): Returns a tuple of file extensions supported by the writer engine.
   • engine (property): Returns the name of the engine being used.
   • sheets (abstract property): Represents a mapping of sheet names to sheet objects.
   • book (abstract property): Represents the book instance, depending on the engine used.
5. Methods:
   • write_cells: A method for writing formatted cells into an Excel sheet. Deprecated in version 1.5.0.
   • _write_cells: An abstract method for writing formatted cells into an Excel sheet.
   • save: A method for saving the workbook to disk. Deprecated in version 1.5.0.
   • _save: An abstract method for saving the workbook to disk.
   • __init__: The constructor for initializing the class instance. It handles various parameters like path, engine, date_format, etc. It also validates parameters and sets internal attributes accordingly.
   • _deprecate: A method to raise a FutureWarning about deprecated attributes or methods.
   • _deprecate_set_book: A method to deprecate setting the book attribute.
   • _get_sheet_name: A helper method for getting the sheet name.
   • _value_with_fmt: A method for converting values to appropriate types for writing into Excel cells.
   • check_extension: A class method to check if a given extension is supported by the writer engine.
   • __enter__ and __exit__: Methods to enable using the class as a context manager.
   • close: A method to save the workbook and close the underlying handles.

Overall, this code defines a foundation for creating Excel writers, allowing for flexibility in choosing different engines and handling Excel file writing operations in a structured manner. It makes use of abstract methods and properties to ensure that concrete subclasses implement required functionality.

Usage of __new__()

The __new__ method is a built-in method in Python that is responsible for creating and returning a new instance of a class. It's called before the __init__ method and is often used to customize object creation. In the code you provided, the __new__ method is used to handle the creation of instances of the ExcelWriter class in a way that allows for dynamic selection of different engines based on the file extension.

Let's break down how the __new__ method is used in this context

def __new__(
    cls: type[ExcelWriter],
    path: FilePath | WriteExcelBuffer | ExcelWriter,
    engine: str | None = None,
    date_format: str | None = None,
    datetime_format: str | None = None,
    mode: str = "w",
    storage_options: StorageOptions = None,
    if_sheet_exists: Literal["error", "new", "replace", "overlay"] | None = None,
    engine_kwargs: dict | None = None,
    **kwargs,
) -> ExcelWriter:
    # ...

1. The __new__ method starts with a signature similar to other methods, but it has a special first argument, cls, which represents the class itself.
2. Other arguments follow, which are used to determine the behavior of the new instance being created. For example, path is the path to the Excel file, engine is the engine to be used for writing, date_format and datetime_format are formats for date and datetime values, etc.
3. The method checks for the presence of additional keyword arguments (*kwargs). If they are present, it raises an error since both engine_kwargs and *kwargs cannot be used together.
4. The method then checks whether the current class being instantiated is the base ExcelWriter class. If it is, it proceeds with determining the appropriate engine to use based on the given information.
5. If the engine is not specified or set to "auto", it determines the file extension of the provided path and attempts to get the engine from configuration options. If the engine is set to "auto", it tries to get a default engine based on the extension. If no engine is found, it raises an error.
6. The code handles special cases when engine is set to "xlwt", issuing a FutureWarning about the deprecation of the xlwt engine.
7. If the class is not the base ExcelWriter class (i.e., it's a subclass), it doesn't change the class and instead calls get_writer(engine) to get the appropriate writer class based on the engine.