load_csv

pyhelpers.store.load_csv(path_to_file, delimiter=',', header=0, index_col=None, verbose=False, prt_kwargs=None, raise_error=False, encoding='utf-8', **kwargs)[source]

Load data from a CSV file.

A single header row (or none) read from an actual file on disk is parsed manually via csv.reader() for efficiency; a multi-row header or an in-memory file-like object (e.g. io.StringIO) is instead passed directly to pandas.read_csv(), which supports both natively. Which backend is used determines which of kwargs are accepted, since csv.reader() and pandas.read_csv() recognize different keyword arguments.

Parameters:

  • path_to_file (str | os.PathLike | io.StringIO) – Pathname of the CSV file, or an in-memory file-like object (e.g. io.StringIO).

  • delimiter (str) – Delimiter used between values in the data file; defaults to ','.

  • header (int | List[int] | None) – Index number of the row(s) used as column names; a single integer (or None, for no header) is handled via csv.reader(), while a list of integers is handled via pandas.read_csv()’s native multi-row header support. Defaults to 0.

  • index_col (str | int | list | None) – Index number of the column(s) to use as the row labels of the dataframe; defaults to None.

  • verbose (bool | int) – Whether to print relevant information to the console; defaults to False.

  • prt_kwargs (dict | None) – [Optional] Additional parameters for the function _check_loading_path(); defaults to None.

  • raise_error (bool) – Whether to raise an exception if the data fails to load; if raise_error=False (default), the error is suppressed instead.

  • encoding (str) – Character encoding used to read path_to_file; defaults to 'utf-8'.

  • kwargs – [Optional] Additional parameters for csv.reader() or pandas.read_csv(), depending on which backend is used (see above).

Returns:

Data retrieved from the specified path path_to_file.

Return type:

pandas.DataFrame | None

Note

Example data can be referred to in save_spreadsheet().

Examples:

>>> from pyhelpers.store import load_csv
>>> from pyhelpers.dirs import cd

>>> csv_pathname = cd("tests", "data", "dat.csv")
>>> csv_dat = load_csv(csv_pathname, index_col=0, verbose=True)
Loading "tests/data/dat.csv" ... Done.
>>> csv_dat
             Longitude    Latitude
City
London      -0.1276474  51.5073219
Birmingham  -1.9026911  52.4796992
Manchester  -2.2451148  53.4794892
Leeds       -1.5437941  53.7974185

>>> csv_pathname = cd("tests", "data", "dat.txt")
>>> csv_dat = load_csv(csv_pathname, index_col=0, verbose=True)
Loading "tests/data/dat.txt" ... Done.
>>> csv_dat
             Longitude    Latitude
City
London      -0.1276474  51.5073219
Birmingham  -1.9026911  52.4796992
Manchester  -2.2451148  53.4794892
Leeds       -1.5437941  53.7974185

>>> csv_dat = load_csv(csv_pathname, header=[0, 1], verbose=True)
Loading "tests/data/dat.txt" ... Done.
>>> csv_dat
         City Easting Northing
       London  530034   180381
0  Birmingham  406689   286822
1  Manchester  383819   398052
2       Leeds  582044   152953