Metadata-Version: 2.5
Name: planarjl-py
Version: 1.8.0
Summary: Python driver for the Planar trading framework (Julia engine)
Author: Planar contributors
License: MIT
Keywords: backtesting,ccxt,crypto,julia,planar,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: ccxt-gateway>=1.8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# planarjl-py

Python driver for the [Planar](https://github.com/BubbleParticles/Planar.jl)
trading framework. Planar is a Julia framework for building trading bots —
backtesting, paper and live execution on 100+ exchanges through CCXT.

`pip install planarjl-py` gives you the `planar` command, which bootstraps a
Planar project and runs strategies from Python by driving the Julia engine.

> The PyPI name `planar` is taken by an unrelated package, hence `planarjl-py`.
> Native *strategy authoring in Python* is the open milestone of
> [issue #7](https://github.com/BubbleParticles/Planar.jl/issues/7); today
> strategies are written in Julia and executed through this CLI.

## Requirements

- Julia ≥ 1.12 on `PATH` (https://julialang.org/downloads/)
- Python ≥ 3.10

## Usage

```bash
pip install planarjl-py

# Bootstrap a project: adds the Planar registry, installs the Planar package,
# and creates the user/ layout (first run downloads packages).
planar init mybot
cd mybot

# Run a strategy in backtest (sim) mode
planar run MyStrategy --mode sim --exchange binanceusdm --sandbox

# Paper or live trading
planar run MyStrategy --mode paper
planar run MyStrategy --mode live

planar version
```

Strategies live in `user/strategies/` and are registered in `user/planar.toml`:

```toml
[sources]
MyStrategy = "strategies/MyStrategy/Project.toml"
```

Create a strategy with the `planar`-provided template (see the Planar.jl docs on
strategy authoring), or copy any strategy from the
[Planar.jl examples](https://github.com/BubbleParticles/Planar.jl/tree/master/examples).

## Development

```bash
cd planarjl-py
uv sync --extra dev    # or: pip install -e .[dev]
pytest
uv build              # build the sdist + wheel
```

## Publishing

See `PACKAGING.md` at the repository root. CI publishes to TestPyPI on `py-v*`
tags and to PyPI on `v*` tags; the version is synced to the Planar Julia
release (same `vX.Y.Z`), and the workflow verifies the built wheel version
matches the tag. Auth is OIDC trusted publishing (`PYPI_API_TOKEN` /
`TESTPYPI_API_TOKEN` secrets are the token fallback):

```bash
git tag py-v1.8.0 && git push origin py-v1.8.0
```
