Metadata-Version: 2.5
Name: jupyter-storage-explorer-pandas-support
Version: 0.17.0
Summary: pandas support for Storage Explorer
Project-URL: Homepage, https://github.com/sugibuchi/jupyter-storage-explorer/tree/main/plugins/pandas-support
Project-URL: Source, https://github.com/sugibuchi/jupyter-storage-explorer
Project-URL: Issues, https://github.com/sugibuchi/jupyter-storage-explorer/issues
Author: Tsuyoshi SUGIBUCHI
License-Expression: MIT
License-File: LICENSE
Keywords: jupyter,jupyter-storage-explorer,pandas,parquet
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Jupyter
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: jupyter-storage-explorer==0.17.0
Provides-Extra: full
Requires-Dist: openpyxl>=3.1; extra == 'full'
Requires-Dist: pandas>=2.0; extra == 'full'
Requires-Dist: pyarrow>=14; extra == 'full'
Description-Content-Type: text/markdown

# jupyter-storage-explorer-pandas-support

pandas support for Storage Explorer,
the [Jupyter Storage Explorer](https://github.com/sugibuchi/jupyter-storage-explorer) plugin for
pandas as an engine: the data browser on the first rows of Parquet, CSV, JSON Lines and Excel files, and code loading
them.

```bash
pip install "jupyter-storage-explorer[pandas]"          # the plugin and its libraries
pip install "jupyter-storage-explorer[pandas-support]"  # the plugin only, with the libraries you have
```

Its libraries (`pandas`, `pyarrow`, `openpyxl`) are not its dependencies, so that installing it never
changes those of a shared environment: the first command (or `jupyter-storage-explorer-pandas-support[full]`) installs
them too.
Explorers use every plugin installed, unless their `plugin_options` disable it: `{"pandas-support": {"enabled": False}}`
(see [Plugins](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/docs/storage-explorer.md#plugins)).

## Plugin options

`plugin_options={"pandas-support": {...}}` (in the launcher's tabs, `plugin_options()` in `launcher.py`):

| Option     | Default | Meaning                                                                                                  |
|------------|---------|----------------------------------------------------------------------------------------------------------|
| `enabled`  | `True`  | Whether explorers use the plugin. `False`: not even imported.                                            |
| `priority` | lowest  | Plugins of a higher priority come first: their supports are tried before the others'. Equal ones by key. |

## Format options

The supports' options, in `format_options["pandas"]` (by format, or `"*"` for all), for the data browser and the code:

```python
StorageExplorer(
    "s3://my-bucket/lake",
    format_options={
        "pandas": {
            "*": {"storage_options": {"anon": False}},
            "csv": {"na_values": ["NA"], "dtype_backend": "pyarrow"},
            "excel": {"sheet_name": "Summary"},
        },
    },
)
```

Every format takes:

| Option            | Default | Meaning                                                                                                                                                        |
|-------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `storage_options` | `None`  | pandas' `storage_options`, `fsspec.open`'s keyword arguments, in the code. The data browser reads through the explorer's filesystem, with its own credentials. |

The other options are each format's reader's arguments, of the same names, with their descriptions from pandas' API
documentation. Those not set are not passed: pandas' defaults, shown, apply, but where the explorer gives its own. The
data browser reads at most `max_memory_rows` rows (see `view_limits`), of each sheet of a workbook. Values that are
Python objects (e.g. data types such as `np.float64` in `dtype`; strings such as `"Int64"` are fine) are used in the
data
browser but left out of the code, as are options that look like credentials.

### CSV (`csv`)

`CsvByPandasOptions`: the arguments of
[`pd.read_csv`](https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html).

| Option             | Default                                         | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
|--------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `sep`              | detected                                        | Character or regex pattern to treat as the delimiter. `sep=None` detects the separator from the first valid row of the file with Python's builtin sniffer tool, `csv.Sniffer`; it is supported only by the Python parsing engine, which will be used automatically. In addition, separators longer than 1 character and different from `'\s+'` will be interpreted as regular expressions and will also force the use of the Python parsing engine. Note that regex delimiters are prone to ignoring quoted data. Regex example: `'\r\t'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `header`           | `'infer'`                                       | Row number(s) containing column labels and marking the start of the data (zero-indexed). Default behavior is to infer the column names: if no `names` are passed the behavior is identical to `header=0` and column names are inferred from the first line of the file, if column names are passed explicitly to `names` then the behavior is identical to `header=None`. Explicitly pass `header=0` to be able to replace existing names. The header can be a list of integers that specify row locations for a `MultiIndex` on the columns e.g. `[0, 1, 3]`. Intervening rows that are not specified will be skipped (e.g. 2 in this example is skipped). Note that this parameter ignores commented lines and empty lines if `skip_blank_lines=True`, so `header=0` denotes the first line of data rather than the first line of the file.<br>When inferred from the file contents, headers are kept distinct from each other by renaming duplicate names with a numeric suffix of the form `".{count}"` starting from 1, e.g. `"foo"` and `"foo.1"`. Empty headers are named `"Unnamed: {i}"` or ` "Unnamed: {i}_level_{level}"` in the case of MultiIndex columns.                  |
| `names`            | (none)                                          | Sequence of column labels to apply. If the file contains a header row, then you should explicitly pass `header=0` to override the column names. Duplicates in this list are not allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `index_col`        | `None`                                          | Column(s) to use as row label(s), denoted either by column labels or column indices.  If a sequence of labels or indices is given, `MultiIndex` will be formed for the row labels.<br>Note: `index_col=False` can be used to force pandas to *not* use the first column as the index, e.g., when you have a malformed file with delimiters at the end of each line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `usecols`          | `None`                                          | Subset of columns to select, denoted either by column labels or column indices. If list-like, all elements must either be positional (i.e. integer indices into the document columns) or strings that correspond to column names provided either by the user in `names` or inferred from the document header row(s). If `names` are given, the document header row(s) are not taken into account. For example, a valid list-like `usecols` parameter would be `[0, 1, 2]` or `['foo', 'bar', 'baz']`. Element order is ignored, so `usecols=[0, 1]` is the same as `[1, 0]`. To instantiate a `DataFrame` from `data` with element order preserved use `pd.read_csv(data, usecols=['foo', 'bar'])[['foo', 'bar']]` for columns in `['foo', 'bar']` order or `pd.read_csv(data, usecols=['foo', 'bar'])[['bar', 'foo']]` for `['bar', 'foo']` order.<br>If callable, the callable function will be evaluated against the column names, returning names where the callable function evaluates to `True`. An example of a valid callable argument would be `lambda x: x.upper() in ['AAA', 'BBB', 'DDD']`. Using this parameter results in much faster parsing time and lower memory usage. |
| `dtype`            | `None`                                          | Data type(s) to apply to either the whole dataset or individual columns. E.g., `{'a': np.float64, 'b': np.int32, 'c': 'Int64'}` Use `str` or `object` together with suitable `na_values` settings to preserve and not interpret `dtype`. If `converters` are specified, they will be applied INSTEAD of `dtype` conversion. Specify a `defaultdict` as input where the default determines the `dtype` of the columns which are not explicitly listed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `engine`           | `None`                                          | Parser engine to use. The C and pyarrow engines are faster, while the python engine is currently more feature-complete. Multithreading is currently only supported by the pyarrow engine. Some features of the "pyarrow" engine are unsupported or may not work correctly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `true_values`      | `None`                                          | Values to consider as `True` in addition to case-insensitive variants of 'True'.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `false_values`     | `None`                                          | Values to consider as `False` in addition to case-insensitive variants of 'False'.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `skipinitialspace` | `False`                                         | Skip spaces after delimiter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `skiprows`         | `None`                                          | Line numbers to skip (0-indexed) or number of lines to skip (`int`) at the start of the file.<br>If callable, the callable function will be evaluated against the row indices, returning `True` if the row should be skipped and `False` otherwise. An example of a valid callable argument would be `lambda x: x in [0, 2]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `skipfooter`       | `0`                                             | Number of lines at bottom of file to skip (Unsupported with `engine='c'`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `nrows`            | `None`; data browser: at most `max_memory_rows` | Number of rows of file to read. Useful for reading pieces of large files. Refers to the number of data rows in the returned DataFrame, excluding:<br>• The header row containing column names.<br>• Rows before the header row, if `header=1` or larger.<br>Example usage:<br>• To read the first 999,999 (non-header) rows: `read_csv(..., nrows=999999)`<br>• To read rows 1,000,000 through 1,999,999: `read_csv(..., skiprows=1000000, nrows=999999)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `na_values`        | `None`                                          | Additional strings to recognize as `NA`/`NaN`. If `dict` passed, specific per-column `NA` values.  By default the following values are interpreted as `NaN`: empty string, "NaN", "N/A", "NULL", and other common representations of missing data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `keep_default_na`  | `True`                                          | Whether or not to include the default `NaN` values when parsing the data. Depending on whether `na_values` is passed in, the behavior is as follows:<br>• If `keep_default_na` is `True`, and `na_values` are specified, `na_values` is appended to the default `NaN` values used for parsing.<br>• If `keep_default_na` is `True`, and `na_values` are not specified, only the default `NaN` values are used for parsing.<br>• If `keep_default_na` is `False`, and `na_values` are specified, only the `NaN` values specified `na_values` are used for parsing.<br>• If `keep_default_na` is `False`, and `na_values` are not specified, no strings will be parsed as `NaN`.<br>Note that if `na_filter` is passed in as `False`, the `keep_default_na` and `na_values` parameters will be ignored.                                                                                                                                                                                                                                                                                                                                                                                    |
| `na_filter`        | `True`                                          | Detect missing value markers (empty strings and the value of `na_values`). In data without any `NA` values, passing `na_filter=False` can improve the performance of reading a large file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `skip_blank_lines` | `True`                                          | If `True`, skip over blank lines rather than interpreting as `NaN` values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `parse_dates`      | `None`                                          | The behavior is as follows:<br>• `bool`. If `True` -> try parsing the index.<br>• `None`. Behaves like `True` if `date_format` is specified.<br>• `list` of `int` or names. e.g. If `[1, 2, 3]` -> try parsing columns 1, 2, 3 each as a separate date column.<br>If a column or index cannot be represented as an array of `datetime`, say because of an unparsable value or a mixture of timezones, the column or index will be returned unaltered as an `object` data type. For non-standard `datetime` parsing, use `to_datetime` after `read_csv`.<br>Note: A fast-path exists for iso8601-formatted dates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `date_format`      | `None`                                          | Format to use for parsing dates and/or times when used in conjunction with `parse_dates`. The strftime to parse time, e.g. `"%d/%m/%Y"`. See [strftime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior) for more information on choices, though note that `"%f"` will parse all the way up to nanoseconds. You can also pass:<br>• "ISO8601", to parse any [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) time string (not necessarily in exactly the same format);<br>• "mixed", to infer the format for each element individually. This is risky, and you should probably use it along with `dayfirst`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `dayfirst`         | `False`                                         | DD/MM format dates, international and European format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `cache_dates`      | `True`                                          | If `True`, use a cache of unique, converted dates to apply the `datetime` conversion. May produce significant speed-up when parsing duplicate date strings, especially ones with timezone offsets.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `compression`      | `'infer'`                                       | For on-the-fly decompression of on-disk data. If 'infer' and 'filepath_or_buffer' is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', '.tar.xz' or '.tar.bz2' (otherwise no compression). If using 'zip' or 'tar', the ZIP file must contain only one data file to be read in. Set to `None` for no decompression. Can also be a dict with key `'method'` set to one of {`'zip'`, `'gzip'`, `'bz2'`, `'zstd'`, `'xz'`, `'tar'`} and other key-value pairs are forwarded to `zipfile.ZipFile`, `gzip.GzipFile`, `bz2.BZ2File`, `zstandard.ZstdDecompressor`, `lzma.LZMAFile` or `tarfile.TarFile`, respectively. As an example, the following could be passed for Zstandard decompression using a custom compression dictionary: `compression={'method': 'zstd', 'dict_data': my_compression_dict}`.                                                                                                                                                                                                                                                                                                            |
| `thousands`        | `None`                                          | Character acting as the thousands separator in numerical values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `decimal`          | `'.'`                                           | Character to recognize as decimal point (e.g., use ',' for European data).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `lineterminator`   | `None`                                          | Character used to denote a line break. Only valid with C parser.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `quotechar`        | `'"'`                                           | Character used to denote the start and end of a quoted item. Quoted items can include the `delimiter` and it will be ignored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `quoting`          | `0`                                             | Control field quoting behavior per `csv.QUOTE_*` constants: 0 (`QUOTE_MINIMAL`, the default: only fields containing special characters are quoted, e.g. characters defined in `quotechar`, `delimiter`, or `lineterminator`), 1 (`QUOTE_ALL`), 2 (`QUOTE_NONNUMERIC`) or 3 (`QUOTE_NONE`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `doublequote`      | `True`                                          | When `quotechar` is specified and `quoting` is not `QUOTE_NONE`, indicate whether or not to interpret two consecutive `quotechar` elements INSIDE a field as a single `quotechar` element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `escapechar`       | `None`                                          | Character used to escape other characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `comment`          | `None`                                          | Character indicating that the remainder of line should not be parsed. If found at the beginning of a line, the line will be ignored altogether. This parameter must be a single character. Like empty lines (as long as `skip_blank_lines=True`), fully commented lines are ignored by the parameter `header` but not by `skiprows`. For example, if `comment='#'`, parsing `#empty\na,b,c\n1,2,3` with `header=0` will result in `'a,b,c'` being treated as the header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `encoding`         | `None`                                          | Encoding to use for UTF when reading/writing (ex. `'utf-8'`). [List of Python standard encodings](https://docs.python.org/3/library/codecs.html#standard-encodings) .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `encoding_errors`  | `'strict'`                                      | How encoding errors are treated. [List of possible values](https://docs.python.org/3/library/codecs.html#error-handlers) .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `on_bad_lines`     | `'error'`                                       | Specifies what to do upon encountering a bad line (a line with too many fields). Allowed values are:<br>• `'error'`, raise an Exception when a bad line is encountered.<br>• `'warn'`, raise a warning when a bad line is encountered and skip that line.<br>• `'skip'`, skip bad lines without raising or warning when they are encountered.<br>• Callable, function that will process a single bad line.<br>• With `engine='python'`, function with signature `(bad_line: list[str]) -> list[str] \| None`. `bad_line` is a list of strings split by the `sep`. If the function returns `None`, the bad line will be ignored. If the function returns a new `list` of strings with more elements than expected, a `ParserWarning` will be emitted while dropping extra elements.<br>• With `engine='pyarrow'`, function with signature as described in pyarrow documentation: [invalid_row_handler](https://arrow.apache.org/docs/python/generated/pyarrow.csv.ParseOptions.html#pyarrow.csv.ParseOptions.invalid_row_handler).                                                                                                                                                        |
| `low_memory`       | `True`                                          | Internally process the file in chunks, resulting in lower memory use while parsing, but possibly mixed type inference.  To ensure no mixed types either set `False`, or specify the type with the `dtype` parameter. Note that the entire file is read into a single `DataFrame` regardless, use the `chunksize` or `iterator` parameter to return the data in chunks. (Only valid with C parser).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `memory_map`       | `False`                                         | If a filepath is provided for `filepath_or_buffer`, map the file object directly onto memory and access the data directly from there. Using this option can improve performance because there is no longer any I/O overhead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `float_precision`  | `None`                                          | Specifies which converter the C engine should use for floating-point values. The options are `None` or `'high'` for the ordinary converter, `'legacy'` for the original lower precision pandas converter, and `'round_trip'` for the round-trip converter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `dtype_backend`    | (none)                                          | Back-end data type applied to the resultant `DataFrame` (still experimental). If not specified, the default behavior is to not use nullable data types. If specified, the behavior is as follows:<br>• `"numpy_nullable"`: returns nullable-dtype-backed `DataFrame`<br>• `"pyarrow"`: returns pyarrow-backed nullable `ArrowDtype` `DataFrame`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### JSON Lines (`json-lines`)

`JsonLinesByPandasOptions`: the arguments of
[`pd.read_json`](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html).

| Option               | Default                                         | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|----------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dtype`              | `None`                                          | If True, infer dtypes; if a dict of column to dtype, then use those; if False, then don't infer dtypes at all, applies only to the data.<br>For all `orient` values except `'table'`, default is True.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `convert_axes`       | `None`                                          | Try to convert the axes to the proper dtypes.<br>For all `orient` values except `'table'`, default is True.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `convert_dates`      | `True`                                          | If True then default datelike columns may be converted (depending on keep_default_dates). If False, no dates will be converted. If a list of column names, then those columns will be converted and default datelike columns may also be converted (depending on keep_default_dates).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `keep_default_dates` | `True`                                          | If parsing dates (convert_dates is not False), then try to parse the default datelike columns. A column label is datelike if<br>• it ends with `'_at'`,<br>• it ends with `'_time'`,<br>• it begins with `'timestamp'`,<br>• it is `'modified'`, or<br>• it is `'date'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `precise_float`      | `False`                                         | Set to enable usage of higher precision (strtod) function when decoding string to double values. Default (False) is to use fast but less precise builtin functionality.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `date_unit`          | `None`                                          | The timestamp unit to detect if converting dates. The default behaviour is to try and detect the correct precision, but if this is not desired then pass one of 's', 'ms', 'us' or 'ns' to force parsing only seconds, milliseconds, microseconds or nanoseconds respectively.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `encoding`           | `None`                                          | The encoding to use to decode py3 bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `encoding_errors`    | `'strict'`                                      | How encoding errors are treated. [List of possible values](https://docs.python.org/3/library/codecs.html#error-handlers) .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `compression`        | `'infer'`                                       | For on-the-fly decompression of on-disk data. If 'infer' and 'path_or_buf' is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', '.tar.xz' or '.tar.bz2' (otherwise no compression). If using 'zip' or 'tar', the ZIP file must contain only one data file to be read in. Set to `None` for no decompression. Can also be a dict with key `'method'` set to one of {`'zip'`, `'gzip'`, `'bz2'`, `'zstd'`, `'xz'`, `'tar'`} and other key-value pairs are forwarded to `zipfile.ZipFile`, `gzip.GzipFile`, `bz2.BZ2File`, `zstandard.ZstdDecompressor`, `lzma.LZMAFile` or `tarfile.TarFile`, respectively. As an example, the following could be passed for Zstandard decompression using a custom compression dictionary: `compression={'method': 'zstd', 'dict_data': my_compression_dict}`. |
| `nrows`              | `None`; data browser: at most `max_memory_rows` | The number of lines from the line-delimited jsonfile that has to be read. This can only be passed if `lines=True`. If this is None, all the rows will be returned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `dtype_backend`      | (none)                                          | Back-end data type applied to the resultant `DataFrame` (still experimental). If not specified, the default behavior is to not use nullable data types. If specified, the behavior is as follows:<br>• `"numpy_nullable"`: returns nullable-dtype-backed `DataFrame`<br>• `"pyarrow"`: returns pyarrow-backed nullable `ArrowDtype` `DataFrame`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `engine`             | `'ujson'`                                       | Parser engine to use. The `"pyarrow"` engine is only available when `lines=True`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### JSON (`json`)

`JsonByPandasOptions`: the arguments of
[`pd.read_json`](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html).

| Option               | Default    | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|----------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `orient`             | `None`     | Indication of expected JSON string format. Compatible JSON strings can be produced by `to_json()` with a corresponding orient value. The set of possible orients is:<br>• `'split'` : dict like `{index -> [index], columns -> [columns], data -> [values]}`<br>• `'records'` : list like `[{column -> value}, ... , {column -> value}]`<br>• `'index'` : dict like `{index -> {column -> value}}`<br>• `'columns'` : dict like `{column -> {index -> value}}`<br>• `'values'` : just the values array<br>• `'table'` : dict like `{'schema': {schema}, 'data': {data}}`<br>The allowed and default values depend on the value of the `typ` parameter.<br>• when `typ == 'series'`,<br>• allowed orients are `{'split','records','index'}`<br>• default is `'index'`<br>• The Series index must be unique for orient `'index'`.<br>• when `typ == 'frame'`,<br>• allowed orients are `{'split','records','index', 'columns','values', 'table'}`<br>• default is `'columns'`<br>• The DataFrame index must be unique for orients `'index'` and `'columns'`.<br>• The DataFrame columns must be unique for orients `'index'`, `'columns'`, and `'records'`. |
| `typ`                | `'frame'`  | The type of object to recover.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `dtype`              | `None`     | If True, infer dtypes; if a dict of column to dtype, then use those; if False, then don't infer dtypes at all, applies only to the data.<br>For all `orient` values except `'table'`, default is True.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `convert_axes`       | `None`     | Try to convert the axes to the proper dtypes.<br>For all `orient` values except `'table'`, default is True.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `convert_dates`      | `True`     | If True then default datelike columns may be converted (depending on keep_default_dates). If False, no dates will be converted. If a list of column names, then those columns will be converted and default datelike columns may also be converted (depending on keep_default_dates).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `keep_default_dates` | `True`     | If parsing dates (convert_dates is not False), then try to parse the default datelike columns. A column label is datelike if<br>• it ends with `'_at'`,<br>• it ends with `'_time'`,<br>• it begins with `'timestamp'`,<br>• it is `'modified'`, or<br>• it is `'date'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `precise_float`      | `False`    | Set to enable usage of higher precision (strtod) function when decoding string to double values. Default (False) is to use fast but less precise builtin functionality.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `date_unit`          | `None`     | The timestamp unit to detect if converting dates. The default behaviour is to try and detect the correct precision, but if this is not desired then pass one of 's', 'ms', 'us' or 'ns' to force parsing only seconds, milliseconds, microseconds or nanoseconds respectively.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `encoding`           | `None`     | The encoding to use to decode py3 bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `encoding_errors`    | `'strict'` | How encoding errors are treated. [List of possible values](https://docs.python.org/3/library/codecs.html#error-handlers) .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `compression`        | `'infer'`  | For on-the-fly decompression of on-disk data. If 'infer' and 'path_or_buf' is path-like, then detect compression from the following extensions: '.gz', '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', '.tar.xz' or '.tar.bz2' (otherwise no compression). If using 'zip' or 'tar', the ZIP file must contain only one data file to be read in. Set to `None` for no decompression. Can also be a dict with key `'method'` set to one of {`'zip'`, `'gzip'`, `'bz2'`, `'zstd'`, `'xz'`, `'tar'`} and other key-value pairs are forwarded to `zipfile.ZipFile`, `gzip.GzipFile`, `bz2.BZ2File`, `zstandard.ZstdDecompressor`, `lzma.LZMAFile` or `tarfile.TarFile`, respectively. As an example, the following could be passed for Zstandard decompression using a custom compression dictionary: `compression={'method': 'zstd', 'dict_data': my_compression_dict}`.                                                                                                                                                                                                                                                                                    |
| `dtype_backend`      | (none)     | Back-end data type applied to the resultant `DataFrame` (still experimental). If not specified, the default behavior is to not use nullable data types. If specified, the behavior is as follows:<br>• `"numpy_nullable"`: returns nullable-dtype-backed `DataFrame`<br>• `"pyarrow"`: returns pyarrow-backed nullable `ArrowDtype` `DataFrame`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `engine`             | `'ujson'`  | Parser engine to use. The `"pyarrow"` engine is only available when `lines=True`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### Excel (`excel`)

`ExcelByPandasOptions`: the arguments of
[`pd.read_excel`](https://pandas.pydata.org/docs/reference/api/pandas.read_excel.html). The data browser shows a
workbook's sheets on tabs below the table (only one sheet: that one), each read when chosen; with `sheet_name`, the
sheet it gives (several, or `None` for all: on tabs).

| Option            | Default                                         | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|-------------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `sheet_name`      | `0`                                             | Strings are used for sheet names. Integers are used in zero-indexed sheet positions (chart sheets do not count as a sheet position). Lists of strings/integers are used to request multiple sheets. When `None`, will return a dictionary containing DataFrames for each sheet.<br>Available cases:<br>• Defaults to `0`: 1st sheet as a `DataFrame`<br>• `1`: 2nd sheet as a `DataFrame`<br>• `"Sheet1"`: Load sheet with name "Sheet1"<br>• `[0, 1, "Sheet5"]`: Load first, second and sheet named "Sheet5" as a dict of `DataFrame`<br>• `None`: Returns a dictionary containing DataFrames for each sheet.                                                                                                                                                                                                              |
| `header`          | `0`                                             | Row (0-indexed) to use for the column labels of the parsed DataFrame. If a list of integers is passed those row positions will be combined into a `MultiIndex`. Use None if there is no header.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `names`           | `None`                                          | List of column names to use. If file contains no header row, then you should explicitly pass header=None.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `index_col`       | `None`                                          | Column (0-indexed) to use as the row labels of the DataFrame. Pass None if there is no such column.  If a list is passed, those columns will be combined into a `MultiIndex`.  If a subset of data is selected with `usecols`, index_col is based on the subset.<br>Missing values will be forward filled to allow roundtripping with `to_excel` for `merged_cells=True`. To avoid forward filling the missing values use `set_index` after reading the data instead of `index_col`.                                                                                                                                                                                                                                                                                                                                        |
| `usecols`         | `None`                                          | • If None, then parse all columns.<br>• If str, then indicates comma separated list of Excel column letters and column ranges (e.g. "A:E" or "A,C,E:F"). Ranges are inclusive of both sides.<br>• If list of int, then indicates list of column numbers to be parsed (0-indexed).<br>• If list of string, then indicates list of column names to be parsed.<br>• If callable, then evaluate each column name against it and parse the column if the callable returns `True`.<br>Returns a subset of the columns according to behavior above.                                                                                                                                                                                                                                                                                |
| `dtype`           | `None`                                          | Data type for data or columns. E.g. {'a': np.float64, 'b': np.int32} Use `object` to preserve data as stored in Excel and not interpret dtype, which will necessarily result in `object` dtype. If converters are specified, they will be applied INSTEAD of dtype conversion. If you use `None`, it will infer the dtype of each column based on the data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `engine`          | `None`; data browser: `'openpyxl'`              | If io is not a buffer or path, this must be set to identify io. Engine compatibility :<br>• `openpyxl` supports newer Excel file formats.<br>• `calamine` supports Excel (.xls, .xlsx, .xlsm, .xlsb) and OpenDocument (.ods) file formats.<br>• `odf` supports OpenDocument file formats (.odf, .ods, .odt).<br>• `pyxlsb` supports Binary Excel files.<br>• `xlrd` supports old-style Excel files (.xls).<br>When `engine=None`, the following logic will be used to determine the engine:<br>• If `path_or_buffer` is an OpenDocument format (.odf, .ods, .odt), then [odf](https://pypi.org/project/odfpy/) will be used.<br>• Otherwise if `path_or_buffer` is an xls format, `xlrd` will be used.<br>• Otherwise if `path_or_buffer` is in xlsb format, `pyxlsb` will be used.<br>• Otherwise `openpyxl` will be used. |
| `true_values`     | `None`                                          | Values to consider as True.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `false_values`    | `None`                                          | Values to consider as False.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `skiprows`        | `None`                                          | Line numbers to skip (0-indexed) or number of lines to skip (int) at the start of the file. If callable, the callable function will be evaluated against the row indices, returning True if the row should be skipped and False otherwise. An example of a valid callable argument would be `lambda x: x in [0, 2]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `nrows`           | `None`; data browser: at most `max_memory_rows` | Number of rows to parse. Does not include header rows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `na_values`       | `None`                                          | Additional strings to recognize as NA/NaN. If dict passed, specific per-column NA values. By default the following values are interpreted as NaN: '', '#N/A', '#N/A N/A', '#NA', '-1.#IND', '-1.#QNAN', '-NaN', '-nan', '1.#IND', '1.#QNAN', '<NA>', 'N/A', 'NA', 'NULL', 'NaN', 'None', 'n/a', 'nan', 'null'.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `keep_default_na` | `True`                                          | Whether or not to include the default NaN values when parsing the data. Depending on whether `na_values` is passed in, the behavior is as follows:<br>• If `keep_default_na` is True, and `na_values` are specified, `na_values` is appended to the default NaN values used for parsing.<br>• If `keep_default_na` is True, and `na_values` are not specified, only the default NaN values are used for parsing.<br>• If `keep_default_na` is False, and `na_values` are specified, only the NaN values specified `na_values` are used for parsing.<br>• If `keep_default_na` is False, and `na_values` are not specified, no strings will be parsed as NaN.<br>Note that if `na_filter` is passed in as False, the `keep_default_na` and `na_values` parameters will be ignored.                                           |
| `na_filter`       | `True`                                          | Detect missing value markers (empty strings and the value of na_values). In data without any NAs, passing `na_filter=False` can improve the performance of reading a large file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `parse_dates`     | `False`                                         | The behavior is as follows:<br>• `bool`. If True -> try parsing the index.<br>• `list` of int or names. e.g. If [1, 2, 3] -> try parsing columns 1, 2, 3 each as a separate date column.<br>• `list` of lists. e.g.  If [[1, 3]] -> combine columns 1 and 3 and parse as a single date column.<br>• `dict`, e.g. {'foo' : [1, 3]} -> parse columns 1, 3 as date and call result 'foo'<br>If a column or index contains an unparsable date, the entire column or index will be returned unaltered as an object data type. If you don`t want to parse some cells as date just change their type in Excel to "Text". For non-standard datetime parsing, use `pd.to_datetime` after `pd.read_excel`.<br>Note: A fast-path exists for iso8601-formatted dates.                                                                   |
| `date_format`     | `None`                                          | If used in conjunction with `parse_dates`, will parse dates according to this format. For anything more complex, please read in as `object` and then apply `to_datetime` as-needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `thousands`       | `None`                                          | Thousands separator for parsing string columns to numeric.  Note that this parameter is only necessary for columns stored as TEXT in Excel, any numeric columns will automatically be parsed, regardless of display format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `decimal`         | `'.'`                                           | Character to recognize as decimal point for parsing string columns to numeric. Note that this parameter is only necessary for columns stored as TEXT in Excel, any numeric columns will automatically be parsed, regardless of display format.(e.g. use ',' for European data).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `comment`         | `None`                                          | Comments out remainder of line. Pass a character or characters to this argument to indicate comments in the input file. Any data between the comment string and the end of the current line is ignored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `skipfooter`      | `0`                                             | Rows at the end to skip (0-indexed).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `dtype_backend`   | (none)                                          | Back-end data type applied to the resultant `DataFrame` (still experimental). If not specified, the default behavior is to not use nullable data types. If specified, the behavior is as follows:<br>• `"numpy_nullable"`: returns nullable-dtype-backed `DataFrame`<br>• `"pyarrow"`: returns pyarrow-backed nullable `ArrowDtype` `DataFrame`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `engine_kwargs`   | `None`                                          | Arbitrary keyword arguments passed to excel engine.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### Parquet (`parquet`)

`ParquetByPandasOptions`: the arguments of
[`pd.read_parquet`](https://pandas.pydata.org/docs/reference/api/pandas.read_parquet.html).

| Option             | Default                         | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|--------------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `engine`           | `'auto'`; data browser: pyarrow | Parquet library to use. If 'auto', then the option `io.parquet.engine` is used. The default `io.parquet.engine` behavior is to try 'pyarrow', falling back to 'fastparquet' if 'pyarrow' is unavailable.<br>When using the `'pyarrow'` engine and no storage options are provided and a filesystem is implemented by both `pyarrow.fs` and `fsspec` (e.g. "s3://"), then the `pyarrow.fs` filesystem is attempted first. Use the filesystem keyword with an instantiated fsspec filesystem if you wish to use its implementation.                                                                                                                                                         |
| `columns`          | `None`                          | If not None, only these columns will be read from the file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `dtype_backend`    | (none)                          | Back-end data type applied to the resultant `DataFrame` (still experimental). If not specified, the default behavior is to not use nullable data types. If specified, the behavior is as follows:<br>• `"numpy_nullable"`: returns nullable-dtype-backed `DataFrame`<br>• `"pyarrow"`: returns pyarrow-backed nullable `ArrowDtype` `DataFrame`                                                                                                                                                                                                                                                                                                                                           |
| `filters`          | `None`                          | To filter out data. Filter syntax: [[(column, op, val), ...],...] where op is [==, =, >, >=, <, <=, !=, in, not in] The innermost tuples are transposed into a set of filters applied through an `AND` operation. The outer list combines these sets of filters through an `OR` operation. A single list of tuples can also be used, meaning that no `OR` operation between set of filters is to be conducted.<br>Using this argument will NOT result in row-wise filtering of the final partitions unless `engine="pyarrow"` is also specified.  For other engines, filtering is only performed at the partition level, that is, to prevent the loading of some row-groups and/or files. |
| `to_pandas_kwargs` | `None`                          | Keyword arguments to pass through to `to_pandas` when `engine="pyarrow"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
