Metadata-Version: 2.4
Name: xlsx2dict
Version: 0.1.1
Summary: A Python library for reading and writing Excel files, converting between xlsx and dictionaries or text.
Author-email: hhhpy <huanghuanhuanhdu@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: python-calamine
Requires-Dist: tabulate
Requires-Dist: xlsxwriter
Description-Content-Type: text/markdown

# xlsx2dict

A Python library for reading and writing Excel files, converting between xlsx and dictionaries or text.

## Installation

```bash
pip install xlsx2dict
```

## Usage

### Reading sheets

```python
from xlsx2dict import sheets

sheet_names = sheets('example.xlsx')
print(sheet_names)
```

#### Parameters

| Parameter  | Type       | Description                  |
|------------|------------|------------------------------|
| xlsx_file  | str or Path| Path to the Excel file       |

### Reading data as list of lists

```python
from xlsx2dict import read

table = read('example.xlsx', 'Sheet1')
print(table)
```

#### Parameters

| Parameter     | Type        | Default | Description                                      |
|---------------|-------------|---------|--------------------------------------------------|
| xlsx_file     | str or Path | -       | Path to the Excel file                           |
| sheet_name    | str or int  | -       | Name or index of the sheet to read               |
| remove_comment| bool        | True    | Whether to remove rows starting with '#'         |

### Reading data as dictionary

```python
from xlsx2dict import read_dict

data = read_dict('example.xlsx', 'Sheet1')
print(data)
```

#### Parameters

| Parameter     | Type        | Default | Description                                      |
|---------------|-------------|---------|--------------------------------------------------|
| xlsx_file     | str or Path | -       | Path to the Excel file                           |
| sheet_name    | str or int  | None    | Name or index of the sheet to read (default: first sheet) |
| strip         | bool        | True    | Whether to strip whitespace from cell values     |
| key_map       | dict        | None    | Mapping to rename column headers                 |
| remove_comment| bool        | True    | Whether to remove rows starting with '#'         |
| save_list     | bool        | False   | Whether to save the entire row as '__list__'    |
| head_rows     | int         | 1       | Number of header rows                            |

#### Return data format
```json
{
    row_number: {header: value, ...},
    ...
}
```

### Writing data

```python
from xlsx2dict import write

table = [['A', 'B'], [1, 2], [3, 4]]
write(table, 'output.xlsx', 'Sheet1')
```

#### Parameters

| Parameter  | Type        | Default | Description                          |
|------------|-------------|---------|--------------------------------------|
| table      | list        | -       | Data as list of lists                |
| xlsx_file  | str or Path | -       | Path to the output Excel file        |
| sheet_name | str         | None    | Name of the sheet (default: 'Sheet1')|

### Writing dictionary data

```python
from xlsx2dict import write_dict

data = {'Sheet1': [['A', 'B'], [1, 2]]}
write_dict('output.xlsx', data)
```

#### Parameters

| Parameter  | Type        | Description                          |
|------------|-------------|--------------------------------------|
| xlsx_file  | str or Path | Path to the output Excel file        |
| data       | dict        | Dictionary with sheet names as keys  |

#### Input data format
```json
{
    "sheet1_name": [[...], [...], ...],
    "sheet2_name": [[...], [...], ...],
    ...
}
```

### Converting to text

```bash
xlsx2text example.xlsx -o output.txt
```

#### Parameters

| Parameter   | Type        | Default | Description                                      |
|-------------|-------------|---------|--------------------------------------------------|
| xlsx_file   | str or Path | -       | Path to the Excel file                           |
| index       | int or str  | None    | Index of the sheet to convert (1-based, default: all) |
| output_file | str or Path | None    | Path to the output text file (default: print to console) |

## License

MIT