Metadata-Version: 2.4
Name: vcti-fieldset-export
Version: 1.0.0
Summary: DataFrame generation, CSV/HTML/chart export, and template rendering for numpy arrays and FieldSet containers
Author: Visual Collaboration Technologies Inc.
License: Proprietary
Project-URL: Homepage, https://github.com/vcti/vcti-python-fieldset-export
Project-URL: Repository, https://github.com/vcti/vcti-python-fieldset-export
Project-URL: Changelog, https://github.com/vcti/vcti-python-fieldset-export/blob/main/CHANGELOG.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: jinja2>=3.0
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"
Provides-Extra: fieldset
Requires-Dist: vcti-fieldset>=1.0.0; extra == "fieldset"
Provides-Extra: styled
Requires-Dist: pandas>=2.0; extra == "styled"
Requires-Dist: beautifulsoup4>=4.12; extra == "styled"
Provides-Extra: all
Requires-Dist: pandas>=2.0; extra == "all"
Requires-Dist: vcti-fieldset>=1.0.0; extra == "all"
Requires-Dist: beautifulsoup4>=4.12; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pandas>=2.0; extra == "test"
Requires-Dist: vcti-fieldset>=1.0.0; extra == "test"
Requires-Dist: beautifulsoup4>=4.12; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# FieldSet Export

DataFrame generation, CSV/HTML/chart export, and template rendering for numpy arrays and FieldSet containers.

**pandas is optional** — CSV, table, and chart exporters work with just numpy. Only `StyledExporter` requires pandas.

## Installation

```bash
pip install vcti-fieldset-export>=1.0.0
```

With pandas support (for StyledExporter):

```bash
pip install vcti-fieldset-export[pandas]>=1.0.0
```

With all optional dependencies:

```bash
pip install vcti-fieldset-export[all]>=1.0.0
```

---

## Quick Start

All exporters accept **numpy arrays**, **dicts of numpy arrays**, or **pandas DataFrames**.

### CSV Export

```python
import numpy as np
from vcti.fieldsetexport import CsvExporter

# From a dict of numpy arrays (no pandas needed)
CsvExporter({"stress": np.array([100, 200]), "disp": np.array([0.1, 0.2])}).export("output.csv")

# From a 2-D numpy array with field names
CsvExporter(np.array([[100, 0.1], [200, 0.2]]), field_names=["stress", "disp"]).export("output.csv")

# From a pandas DataFrame (requires pandas)
import pandas as pd
CsvExporter(pd.DataFrame({"stress": [100, 200], "disp": [0.1, 0.2]})).export("output.csv")
```

### HTML Table (Tabulator)

```python
from vcti.fieldsetexport import TableExporter

TableExporter({"stress": np.array([100, 200])}).export("output.html")
```

### Styled HTML (requires pandas)

```python
from vcti.fieldsetexport import StyledExporter

(
    StyledExporter({"stress": np.array([100, 200])})
    .set_caption("Results")
    .set_format(precision=2)
    .export_html("styled.html")
)
```

### Interactive Chart

```python
from vcti.fieldsetexport import ChartExporter, Trace, FigType, Fig

exporter = ChartExporter({"x": np.array([1, 2, 3])})
exporter.plot.title = "Stress vs Displacement"
exporter.plot.x_axis_title = "Index"
exporter.plot.y_axis_title = "Value"

fig = Fig(FigType.XY)
fig.add_trace(Trace("Stress", np.array([100, 200, 300]), color="blue"))
fig.add_trace(Trace("Displacement", np.array([0.1, 0.2, 0.3]), color="red"))
exporter.add_fig(fig)

exporter.export("chart.html")
```

### Export Result and Dry-Run Validation

Every `export()` call returns an `ExportResult` with statistics:

```python
result = CsvExporter({"stress": np.array([100, 200])}).export("output.csv")
print(result)  # ExportResult: 2 rows × 1 cols in 1.2ms, 34 bytes

# Dry-run: validate data + template without writing a file
result = CsvExporter(data).export("output.csv", validate_only=True)
assert result.dry_run is True
```

### Error Handling

All export errors inherit from `ExportError` for easy catch-all handling:

```python
from vcti.fieldsetexport import CsvExporter, ExportError, InvalidDataError

try:
    CsvExporter(data).export("output.csv")
except InvalidDataError as e:
    print(f"Bad data: {e}")       # empty array, wrong shape, etc.
except ExportError as e:
    print(f"Export failed: {e}")  # catches any export error
```

Exception hierarchy: `ExportError` > `InvalidDataError`, `TemplateRenderError`, `FileWriteError`.

---

## Dependencies

- [numpy](https://numpy.org/) (>=1.24) — required
- [jinja2](https://jinja.palletsprojects.com/) (>=3.0) — required
- [pandas](https://pandas.pydata.org/) (>=2.0) — optional (for StyledExporter)
- [vcti-fieldset](https://pypi.org/project/vcti-fieldset/) — optional (for FieldSet integration)
- [beautifulsoup4](https://pypi.org/project/beautifulsoup4/) — optional (for styled HTML export)
