Metadata-Version: 2.5
Name: aa-wanderer-leaderboard
Version: 0.3.0
Summary: Mapping contribution leaderboard for Wanderer
Project-URL: Changelog, https://github.com/ryanrolds/aa-wanderer-leaderboard/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/ryanrolds/aa-wanderer-leaderboard
Project-URL: Issues, https://github.com/ryanrolds/aa-wanderer-leaderboard/issues
Project-URL: Source, https://github.com/ryanrolds/aa-wanderer-leaderboard
Author-email: "Ryan R. Olds" <ryanrolds@gmail.com>
License-Expression: GPL-2.0-only
License-File: LICENSE
Keywords: allianceauth,leaderboard,wanderer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.10
Requires-Dist: allianceauth<6,>=4.0.0
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# aa-wanderer-leaderboard

Mapping contribution leaderboard for a
[Wanderer](https://github.com/wanderer-industries/wanderer) map, by month or by
week, as an Alliance Auth app.

Wanderer already totals mapping contributions — but it totals them per
character, and it has no way of knowing that six characters are one person.
Alliance Auth does: it is the authoritative record of mains and alts. This app
reads Wanderer's audit API and rolls the numbers up per main, so a scanning
reward program pays out from one table instead of being reconciled by hand.

## Features

- Contributions credited to the person, not the character — alts roll up to
  their Alliance Auth main, with each character listed under the row
- Characters Alliance Auth does not know get their own row, marked unlinked
- Systems, connections and signatures, each split into created, updated and
  deleted, plus a total
- One month or one week at a time, ranked, with the previous and next period a
  click away. Weeks run from Monday downtime to the next Monday downtime
  (11:00 UTC), so a week never turns over mid-session
- Optionally limited to your own alliances: an admin lists the tickers, and the
  board shows only people whose Alliance Auth main is in one of them. Configure
  none and it shows everyone, as before
- Track several maps and pick between them on the page

## For server admins

Nothing runs in the background and nothing is stored. Opening the page makes at
most one call to Wanderer for the selected map, and both that response and the
finished table are cached for five minutes
(`WANDERER_LEADERBOARD_CACHE_TTL`). Paging between months or weeks inside that
window costs no further calls, and the cache is shared, so a hundred people
watching the leaderboard cost the same as one. Editing a map's URL or API key
discards what the old ones fetched.

Wanderer only serves a rolling three month window, so older months and weeks
cannot be shown; the page says so rather than displaying a misleading zero.

## Installation

```bash
pip install -U aa-wanderer-leaderboard
```

Add `wanderer_leaderboard` to `INSTALLED_APPS`, then:

```bash
python manage.py migrate
```

Optional settings in `local.py`:

```python
WANDERER_LEADERBOARD_API_TIMEOUT = 30   # seconds
WANDERER_LEADERBOARD_CACHE_TTL = 300    # seconds a response is reused
```

Everything else is per map and lives in the admin. No database link to Wanderer
is required.

## Setup

1. Copy a map's **API key** from Wanderer's map settings.
2. In the Django admin, add a tracked map: its slug or map ID, the base URL of
   the Wanderer instance, and the API key. The **Test the API key against
   Wanderer** action confirms it works.
3. Grant users `wanderer_leaderboard | general | Can access the Wanderer
   Leaderboard`. The menu entry appears for them.
4. Optional: to limit the board to your own alliances, add their tickers under
   **Wanderer Leaderboard → Tracked alliances** (e.g. `GEESE`, `THUGS`). Leave
   this list empty to rank everyone who shows up in the audit log.

The base URL is called from the Alliance Auth server, not from your browser, so
it has to be reachable from there — behind Docker that is usually the Wanderer
service name rather than the localhost address you use in the browser.

Pick a map, then Month or Week, on the page. One map is shown at a time.

### Limiting the board to your alliances

With at least one active entry under **Tracked alliances**, the board shows only
contributors whose Alliance Auth *main character* is in one of those alliances.
Everyone else is left off, and the page says how many were hidden rather than
pretending the map was quiet.

For a contributor Auth knows, the alliance is read from their main, never from
the character that did the scanning, so an alt parked in a holding alliance does
not move its main off the board. For a contributor Auth has no main for, the
alliance Wanderer reports for the scanning character is used instead, and the
row keeps its `unlinked` badge. Most people who scan for an alliance never
register in Auth, so judging them by a main they do not have would hide most of
the alliance.

One consequence: if Auth's copy of someone's main is stale and carries no
alliance, that registered person drops off a filtered board while unregistered
characters stay on it. Running Auth's character update fixes it.

Tickers are matched case-insensitively and stored upper case. Nothing validates
that a ticker exists — a typo simply matches nobody — so the admin list shows a
**Registered mains** count beside each entry, which reads `0 — check the ticker`
when nothing matches.

## Tests

```bash
DJANGO_SETTINGS_MODULE=testauth.settings.local python runtests.py wanderer_leaderboard
```

Needs `allianceauth` and a reachable Redis; override with
`TESTAUTH_REDIS_URL=redis://aa_redis:6379/15`.

## Credits

Counts events produced by [Wanderer](https://github.com/wanderer-industries/wanderer).
Project layout follows allianceauth-workflows and Kalkoken's aa-example-app.
