Metadata-Version: 2.1
Name: natscale
Version: 0.1.2
Author-Email: "TX.Mao" <mtianxiang@gmail.com>
License: MIT
Requires-Python: >=3.12
Requires-Dist: loguru>=0.7.0
Requires-Dist: typer>=0.15.2
Requires-Dist: nats-py>=2.12.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: faststream>=0.6.4
Requires-Dist: anyio>=4.12.0
Description-Content-Type: text/markdown

# natscale

A high-performance Python framework for HPC task distribution, load balancing, and monitoring powered by NATS.

# Install NATS
## deploy a NATS service

``` sh
go install github.com/nats-io/nats-server/v2@latest

export PATH=$PATH:$(go env GOPATH)/bin

# -js 表示开启 JetStream 持久化功能
# -m 8222 (可选) 开启 HTTP 监控面板，方便在浏览器看状态
nats-server -js
```

## create a NATS stream

``` sh
nats stream add NATSCALE --subjects "hpc.tasks.>" --storage=file --ack --retention=work --discard new   --max-msgs 100000 --replicas 1
```

## useful commands

check the stream info
``` sh
watch -n 10 nats stream info NATSCALE
```


view the stream graph
``` sh
nats stream graph
```

# Usage

Manually send an ACK signal to confirm that the task has been successfully received and processed.

``` python
import time
import natscale as ns

cfg = ns.Config(
    nats_server="nats://127.0.0.1:4222",
    subject="netscale.tasks.*",
    timeout=3,
    retry = 4,
    auto_ack=False,
)

# manually do ack
with ns.Iterator(cfg) as tasks:
    for data, done in tasks:
        print(f"{data.id} --> {data}")
        time.sleep(1)
        done()
```

Auto send an ACK signal to confirm that the task has been successfully received and processed.

``` python
import time
import natscale as ns
from natscale.task.iter import NatsIterator as Iterator

cfg = ns.Config(
    nats_server="nats://127.0.0.1:4222",
    subject="netscale.tasks.*",
    timeout=3,
    retry = 4,
    auto_ack=True,
)

with Iterator(cfg) as tasks:
    for data in tasks:
        print(f"{data.id} --> {data}")
        time.sleep(1)
```




# template-pdm-base

This project is generated by pdm template of https://github.com/POFK/template-pdm-base by command:
```
pdm init https://github.com/POFK/template-pdm-base <project_name>
```

also a non-interactive command is:
```
pdm init --name <project_name> --dist -n  https://github.com/POFK/template-pdm-base
```

# first run after initialization
```
pdm install
detect-secrets scan > .secrets.baseline

git add .
pre-commit run -a
```
