Metadata-Version: 2.5
Name: vnfinancialdata
Version: 0.1.0
Summary: Python interface for Vietnamese listed-company financial statement data.
Author: Ngo Phu Thanh
Requires-Python: >=3.10
Requires-Dist: huggingface-hub>=1.0
Requires-Dist: pandas>=2.0
Requires-Dist: pyarrow>=14
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == 'polars'
Description-Content-Type: text/markdown

# vnfinancialdata

Python interface for Vietnamese listed-company financial statement data.

## Current Development Status

Package version:

```text
0.1.0
```

Dataset revision:

```text
v1.0.0
```

The dataset is currently hosted as a private Hugging Face dataset.

## Installation

For local development:

```bash
pip install -e .
```

## Authentication

Access to the private dataset requires Hugging Face authentication.

Run:

```bash
hf auth login
```

before accessing the dataset.

## Basic Usage

```python
import vnfinancialdata as vnf

vnf.check_access()

df = vnf.load(
    exchange="HSX",
    statement="balance_sheet"
)

print(df.head())
```

## Supported Exchanges

- HSX
- HNX

## Supported Financial Statements

- `balance_sheet`
- `cash_flow`
- `income_statement`

## Dataset Versioning

The package version and dataset revision are managed separately.

Current package version:

```text
0.1.0
```

Current dataset revision:

```text
v1.0.0
```

Current dataset schema version:

```text
1.0
```

## Data Source

The package retrieves financial-statement data from a version-pinned Hugging Face dataset repository.

The dataset is stored in Parquet format and organized by:

- exchange
- financial statement type

## Current Access Status

The dataset is currently private.

Users must have permission to access the Hugging Face dataset repository and must authenticate locally before using the package.
