leaf_engine.io
==============

.. py:module:: leaf_engine.io


Subpackages
-----------

.. toctree::
   :maxdepth: 1

   /autoapi/leaf_engine/io/api/index
   /autoapi/leaf_engine/io/gdrive/index


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/leaf_engine/io/local/index
   /autoapi/leaf_engine/io/memory/index
   /autoapi/leaf_engine/io/read/index


Functions
---------

.. autoapisummary::

   leaf_engine.io.read_csv
   leaf_engine.io.read_data
   leaf_engine.io.read_dataset
   leaf_engine.io.read_drive
   leaf_engine.io.read_excel
   leaf_engine.io.read_params
   leaf_engine.io.to_drive
   leaf_engine.io.upload_to_drive


Package Contents
----------------

.. py:function:: read_csv(input_path, **kwargs) -> pandas.DataFrame

.. py:function:: read_data(company_params: dict) -> Dict[str, pandas.DataFrame]

   Reads all data specified in company_params.

   :returns: Dictionary mapping dataset labels to DataFrames that
             can be passed to `pd.concat` directly to create one DataFrame.
   :rtype: Dict[str, pd.DataFrame]


.. py:function:: read_dataset(dataset_params) -> pandas.DataFrame | Dict[Any, pandas.DataFrame]

.. py:function:: read_drive(url: Optional[str] = None, path: Optional[str] = None, cache: bool = True, **kwargs) -> pandas.DataFrame

   Reads CSV, Excel, or Google Spreadsheet file from Google Drive either by
   url or path.

   :param url: File URL. Can be copied from browser navigation bar.
               Defaults to None.
   :type url: Optional[str], optional
   :param path: File path. First part needs to be drive name.
                Defaults to None.
   :type path: Optional[str], optional
   :param cache: Whether to cache the result to disk. Defaults to True. This
                 makes subsequent calls to read_drive faster.
   :type cache: bool, optional
   :param \*\*kwargs: Keyword arguments passed to pandas.read_csv or pandas.read_excel.

   Examples:
   >>> df = read_drive(url="https://drive.google.com/file/d/XXYYZZ/view?usp=sharing")
   >>> df = read_drive(path="Data Science/folder1/folder2/file.csv")

   :raises LeafGoogleDriveException: If both url and path are None or both are not None.
   :raises LeafGoogleDriveException: If file is not found on Google Drive.
   :raises LeafGoogleDriveException: If unable to download file from Google Drive.
   :raises ValueError: If neither pd.read_csv nor pd.read_excel can read the file.

   :returns: DataFrame read from file.
   :rtype: pd.DataFrame


.. py:function:: read_excel(input_path, **kwargs) -> pandas.DataFrame

.. py:function:: read_params(params_path: Union[str, pathlib.Path]) -> dict

.. py:function:: to_drive(df: pandas.DataFrame, path: str, overwrite: bool = False, **kwargs) -> str

   Write a DataFrame to a file on Google Drive, at the specified path.

   :param df: DataFrame to write.
   :type df: pd.DataFrame
   :param path: Path to write to. First part of path is the drive name.
   :type path: str
   :param overwrite: Overwrite existing file. Defaults to False.
   :type overwrite: bool, optional

   Examples:
   >>> df.pipe(gdrive.to_drive, "drive_name/folder1/folder2/file_name.csv")
   >>> df.pipe(gdrive.to_drive, "drive_name/folder1/folder2/file_name.xlsx")

   :raises LeafGoogleDriveException: Raised if `overwrite` is False and file exists.
   :raises LeafGoogleDriveException: Raised if path is invalid.
   :raises LeafGoogleDriveException: Raised if write response does not contain file ID.

   :returns: Google Drive file URL.
   :rtype: str


.. py:function:: upload_to_drive(local_path: Union[str, pathlib.Path], drive_path: str, overwrite: bool = False) -> str

   Uploads file to Google Drive.

   :param local_path: Local path of file to upload.
   :type local_path: Union[str, Path]
   :param drive_path: Google Drive path to uploaded to. First part of path is the drive name.
                      Must include file name: "drive_name/folder1/folder2/file_name.zip".
   :type drive_path: str
   :param overwrite: Overwrite existing file. Defaults to False.
   :type overwrite: bool

   :raises LeafGoogleDriveException: Raised if `overwrite` is False and file exists.
   :raises LeafGoogleDriveException: Raised if unable to upload file.

   :returns: Google Drive URL of uploaded file.
   :rtype: str