Metadata-Version: 2.4
Name: nubra-volume-breakout
Version: 0.1.0
Summary: Volume breakout scanner built on top of the Nubra Python SDK.
Keywords: nubra,scanner,volume,breakout,trading
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: nubra-sdk>=0.4.0
Requires-Dist: pandas>=2.0

# nubra-volume-breakout

`nubra-volume-breakout` is a small Python library for running a volume breakout scan using the Nubra Python SDK.

It fetches historical OHLCV data through `MarketData.historical_data(...)`, derives candle volume safely for intraday intervals, calculates average lookback volume, computes `volume_ratio = current_volume / average_volume`, and returns a ranked pandas DataFrame.

## Installation

From the project folder:

```bash
pip install .
```

For editable development installs:

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

## Quickstart

See [example/quickstart.py](example/quickstart.py).

Example usage:

```python
from nubra_python_sdk.marketdata.market_data import MarketData
from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv
from nubra_volume_breakout import run_volume_breakout

nubra = InitNubraSdk(NubraEnv.PROD, env_creds=True)
market_data = MarketData(nubra)

stocks = ["ABB", "ADANIENSOL", "ADANIENT", "ADANIGREEN", "ADANIPORTS"]

volume_breakout = run_volume_breakout(
    market_data=market_data,
    stocks=stocks,
    lookback_days=10,
    interval="1d",
    rank=10,
)

print(volume_breakout.head(10))
```

## Returned DataFrame

The scanner returns only these columns:

- `symbol`
- `candle_time`
- `current_volume`
- `average_volume`
- `volume_ratio`

The results are sorted by:

1. `volume_ratio` descending
2. `current_volume` descending
3. `symbol` ascending

## Function Signature

```python
run_volume_breakout(
    market_data,
    stocks,
    lookback_days,
    interval,
    rank,
    *,
    exchange="NSE",
    instrument_type="STOCK",
    baseline_mode="same_slot",
    lookback_candles=None,
    timezone_name="Asia/Kolkata",
    convert_prices=True,
    request_volume_delta=False,
    request_pause_seconds=0.0,
)
```

## Notes

- Nubra historical requests are rate-limited.
- Nubra historical requests support small symbol batches, so the scanner automatically batches requests.
- For intraday intervals, the scanner falls back to `diff(cumulative_volume)` if `cumulative_volume_delta` is unavailable or unstable.
- Prices are typically returned by Nubra in paise for NSE instruments; this library converts OHLC prices for internal comparisons where needed.

## Build The Package

Install build tools:

```bash
pip install build twine
```

Build source and wheel distributions:

```bash
python -m build
```

This creates artifacts under `dist/`.

## Publish To PyPI

1. Create accounts on [PyPI](https://pypi.org/) and optionally [TestPyPI](https://test.pypi.org/).
2. Make sure the package name `nubra-volume-breakout` is available. If it is already taken, change the `name` field in [pyproject.toml](pyproject.toml).
3. Build the package:

   ```bash
   python -m build
   ```

4. Upload to TestPyPI first:

   ```bash
   python -m twine upload --repository testpypi dist/*
   ```

5. Upload to PyPI:

   ```bash
   python -m twine upload dist/*
   ```

6. Test installation:

   ```bash
   pip install nubra-volume-breakout
   ```

## Recommended Before Public Release

- Add a license file that matches how you want to distribute the package.
- Add unit tests for volume derivation and ranking behavior.
- Consider adding CI to build and validate the package automatically.

