Metadata-Version: 2.4
Name: pytkc
Version: 0.3.0
Summary: A fast, pure Python reader for MetaTrader 5 .tkc tick history files
Author: pytkc contributors
License: MIT
Project-URL: Homepage, https://github.com/user/pytkc
Project-URL: Documentation, https://github.com/user/pytkc#readme
Project-URL: Repository, https://github.com/user/pytkc
Project-URL: Issues, https://github.com/user/pytkc/issues
Keywords: metatrader,mt5,tick-data,forex,trading,backtesting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"
Provides-Extra: numpy
Requires-Dist: numpy>=1.23; extra == "numpy"
Provides-Extra: arrow
Requires-Dist: pyarrow>=10.0; extra == "arrow"
Provides-Extra: all
Requires-Dist: pandas>=1.5; extra == "all"
Requires-Dist: numpy>=1.23; extra == "all"
Requires-Dist: pyarrow>=10.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# pytkc

[![PyPI version](https://img.shields.io/pypi/v/pytkc.svg)](https://pypi.org/project/pytkc/)
[![Python versions](https://img.shields.io/pypi/pyversions/pytkc.svg)](https://pypi.org/project/pytkc/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/user/pytkc/actions/workflows/tests.yml/badge.svg)](https://github.com/user/pytkc/actions)

Pure Python reader for MetaTrader 5 `.tkc` tick history files.

## Features

- Pure Python, no compiled dependencies required
- Streaming iterator for memory-efficient processing
- Dataset API for multi-file access
- Export to CSV, Pandas, NumPy, Apache Arrow, Parquet, and Feather
- Custom exceptions for clear error handling
- Validated against MT5 for XAUUSD, GBPUSD, EURUSD

## Installation

```bash
pip install pytkc
```

For optional export formats:

```bash
pip install pytkc[pandas]    # Pandas support
pip install pytkc[numpy]     # NumPy support
pip install pytkc[arrow]     # Arrow/Parquet/Feather support
pip install pytkc[all]       # All export formats
```

## Quick Start

```python
from pytkc import TKCFile

tkc = TKCFile("201901.tkc")

# Iterate over ticks
for tick in tkc:
    print(tick.timestamp, tick.bid, tick.ask)

# Export to Pandas
df = tkc.to_pandas()
```

## Dataset API

```python
from pytkc import Dataset
from datetime import datetime, timezone

ds = Dataset("D:/MT5/Samples")

# List symbols
print(ds.symbols())

# Iterate over ticks
for tick in ds.ticks("XAUUSD"):
    print(tick.timestamp, tick.bid)

# Date range
start = datetime(2019, 1, 1, tzinfo=timezone.utc)
end = datetime(2019, 12, 31, tzinfo=timezone.utc)
ticks = ds.between("XAUUSD", start, end)
```

## Command Line

```bash
# Show file info
pytkc 201901.tkc --info

# Show first 20 ticks
pytkc 201901.tkc --head 20

# Export to CSV
pytkc 201901.tkc -o output.csv
```

## Supported Python Versions

- Python 3.10+
- Tested on 3.10, 3.11, 3.12, 3.13

## Validated Against MT5

| Symbol | Tick Count | Prices | Status |
|--------|------------|--------|--------|
| XAUUSD | 45,021 | Exact match | ✓ |
| GBPUSD | 46,262 | Exact match | ✓ |
| EURUSD | 41,940 | Exact match | ✓ |

## License

MIT License - see [LICENSE](LICENSE) for details.

## Disclaimer

`pytkc` is an independent implementation for reading `.tkc` files. It is not affiliated with, endorsed by, or supported by MetaQuotes Ltd. MetaTrader is a trademark of MetaQuotes Ltd.
