Metadata-Version: 2.4
Name: vicalerts
Version: 0.3.0
Summary: Track & archive Victoria's live emergency alerts
Project-URL: Homepage, https://github.com/lnxd/python-vicalerts
Project-URL: Source, https://github.com/lnxd/python-vicalerts
Project-URL: Issues, https://github.com/lnxd/python-vicalerts/issues
Author-email: lnxd <48756329+lnxd@users.noreply.github.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlite-utils>=3.36
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# VicAlerts

Track and archive VicEmergency incidents to a local SQLite database.

## Purpose

VicAlerts polls the public VicEmergency GeoJSON feed, stores every version of every event, and exposes a small CLI for querying the result. Useful for incident timelines, post-event analysis, or keeping your own history for when events expire from the feed. It is designed to run 24/7 to collect data.

## Installation

```bash
uv pip install vicalerts
```

Requires Python 3.10 or newer.

## Quick start

```bash
# Continuous polling (60 s default)
vicalerts run

# One-off fetch (handy in cron)
vicalerts run --once
```

## CLI reference

| Command              | Description                          | Key options                                                                                                                            |
| -------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `run`                | Poll feed and write to the DB        | `--once`, `--interval <seconds>` (>=10), `--db <path>`, `--no-progress`                                                                |
| `events`             | List events (active only by default) | `--all`, `--type incident\|warning`, `--status <text>`, `--category <text>`, `--limit <n>`, `--format table\|json\|csv`, `--db <path>` |
| `history <EVENT_ID>` | Show full version history            | `--db <path>`                                                                                                                          |
| `stats`              | Print DB totals                      | `--db <path>`                                                                                                                          |

All commands accept `--help`.

## Defaults

| Setting      | Value                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| Feed URL     | [https://emergency.vic.gov.au/public/events-geojson.json](https://emergency.vic.gov.au/public/events-geojson.json) |
| Interval     | 60 s                                                                                                               |
| HTTP timeout | 30 s                                                                                                               |
| Retries      | 3 (1 s, then 2 s, then 4 s)                                                                                        |
| Database     | `./vicalerts.sqlite`                                                                                               |

## Example workflows

```bash
# 1. Nightly stats
vicalerts stats --db /data/vic.sqlite

# 2. Export active incidents as JSON
vicalerts events --type incident --format json > incidents.json

# 3. Inspect how an event evolved
vicalerts history 123456 --db /data/vic.sqlite
```

## Notes and limitations

* Disk growth is roughly 10–20 MB per month (feeds are compressed).
* Memory use is modest (< 50 MB typical).
* Geometry is reduced to centroids; polygons are not preserved.
* Tested on Linux and macOS; Windows untested.
* 60s interval is based on VicEmergency website; impact is no different to having the site open.

## Attribution

Data © State of Victoria (EMV) - data licensed under CC BY 4.0 AU
