Metadata-Version: 2.4
Name: arccos-api
Version: 0.6.0
Summary: Unofficial Python CLI and client library for the Arccos Golf API
Author: Paul Frederiksen
License-Expression: MIT
Project-URL: Homepage, https://github.com/pfrederiksen/arccos-api
Project-URL: Repository, https://github.com/pfrederiksen/arccos-api
Project-URL: Issues, https://github.com/pfrederiksen/arccos-api/issues
Project-URL: PyPI, https://pypi.org/project/arccos-api/
Project-URL: Changelog, https://github.com/pfrederiksen/arccos-api/blob/main/CHANGELOG.md
Keywords: golf,arccos,api,cli,golf-stats
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: click<9,>=8.1
Requires-Dist: rich<16,>=13.0
Provides-Extra: keyring
Requires-Dist: keyring<27,>=25; extra == "keyring"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: openapi-spec-validator<0.8,>=0.7; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/pfrederiksen/arccos-api/main/assets/banner.png" alt="arccos-api banner" width="100%">
</p>

# arccos-api

[![PyPI](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Farccos-api%2Fjson&query=%24.info.version&label=PyPI&color=orange)](https://pypi.org/project/arccos-api/)
[![Tests](https://github.com/pfrederiksen/arccos-api/actions/workflows/tests.yml/badge.svg)](https://github.com/pfrederiksen/arccos-api/actions/workflows/tests.yml)
[![Python](https://img.shields.io/pypi/pyversions/arccos-api)](https://pypi.org/project/arccos-api/)
[![License](https://img.shields.io/pypi/l/arccos-api)](https://github.com/pfrederiksen/arccos-api/blob/main/LICENSE)

Your Arccos Golf data, from the terminal or Python.

`arccos-api` is an unofficial, read-only client for exploring your own rounds,
handicap, club distances, strokes gained, pace of play, and more.

> **Important:** Arccos does not provide a public API. This project is not affiliated with
> Arccos Golf LLC, and upstream changes may occasionally require a library update.

## What you can do

- Browse rounds and hole-by-hole scoring
- Track handicap, scoring, and strokes-gained trends
- Inspect smart distances, club shots, and dispersion
- Compare rounds and review personal bests
- Explore courses, pace of play, and hole imagery metadata
- Export data as JSON, CSV, or NDJSON
- Use the same data through a Python client

Golf data access is **read-only by design**. The client only sends `GET` requests
to the Arccos data API. Login and token refresh use the authentication service's
required `POST` requests, but never create, edit, or delete golf or account data.

## Install

Requires Python 3.11 or newer.

```bash
pip install arccos-api
```

For the CLI on macOS or Linux, Homebrew is also available:

```bash
brew install pfrederiksen/tap/arccos-api
```

Optional operating-system keyring support:

```bash
pip install 'arccos-api[keyring]'
```

## Quick start

Authenticate once, then start exploring:

```bash
arccos login
arccos rounds
arccos handicap
arccos clubs
```

Some useful next steps:

```bash
arccos round 12345678            # hole-by-hole round detail
arccos stats --dashboard         # strokes-gained dashboard
arccos trends                    # handicap trend
arccos pace                      # pace of play by course
arccos export -f csv -o rounds.csv
```

Most display commands support `--json`, and every command supports `--help`.
See the [CLI guide](https://github.com/pfrederiksen/arccos-api/blob/main/docs/cli.md) for the complete command list, filtering,
profiles, shell completion, and export examples.

## Use it from Python

`arccos login` caches credentials, so Python can reuse them without putting a
password in source code:

```python
from arccos import ArccosClient

with ArccosClient() as client:
    rounds = client.rounds.list(limit=5)
    handicap = client.handicap.current()
    distances = client.clubs.smart_distances()

    print(f"Handicap: {handicap['userHcp']:.1f}")
    for round_ in rounds:
        print(round_["startTime"][:10], round_["noOfShots"])
```

You can also authenticate directly:

```python
client = ArccosClient(email="you@example.com", password="your_password")
```

See the [Python client guide](https://github.com/pfrederiksen/arccos-api/blob/main/docs/python-api.md) for resources and examples, or
browse the complete [OpenAPI 3.1 specification](https://github.com/pfrederiksen/arccos-api/blob/main/docs/openapi.yaml).

## Documentation

| Guide | Contents |
|---|---|
| [CLI guide](https://github.com/pfrederiksen/arccos-api/blob/main/docs/cli.md) | Commands, filters, exports, profiles, and environment variables |
| [Python client](https://github.com/pfrederiksen/arccos-api/blob/main/docs/python-api.md) | Authentication, resources, and usage examples |
| [OpenAPI specification](https://github.com/pfrederiksen/arccos-api/blob/main/docs/openapi.yaml) | Complete endpoint and schema reference |
| [Examples](https://github.com/pfrederiksen/arccos-api/tree/main/examples) | Runnable Python scripts |
| [Contributing](https://github.com/pfrederiksen/arccos-api/blob/main/CONTRIBUTING.md) | Local setup, tests, style, and releases |
| [Security](https://github.com/pfrederiksen/arccos-api/blob/main/SECURITY.md) | Credential handling and vulnerability reporting |
| [Changelog](https://github.com/pfrederiksen/arccos-api/blob/main/CHANGELOG.md) | Release history |

## Credentials and privacy

- Credentials are cached with owner-only permissions in your platform's config
  directory. Legacy `~/.arccos_creds.json` files migrate automatically.
- Named profiles are available through `ARCCOS_PROFILE` or command options.
- Set `ARCCOS_KEYRING=true` to use the optional OS keyring integration.
- `arccos logout` clears local credentials but cannot revoke upstream tokens;
  change your Arccos password if credentials may be compromised.
- Use your own account and avoid aggressive polling.

Run `arccos doctor` to check configuration, credentials, and API connectivity.
See [SECURITY.md](https://github.com/pfrederiksen/arccos-api/blob/main/SECURITY.md) to report a vulnerability privately.

## Development

```bash
git clone https://github.com/pfrederiksen/arccos-api.git
cd arccos-api
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest
```

Tests use mocked and sanitized responses; no Arccos account is required.
See [CONTRIBUTING.md](https://github.com/pfrederiksen/arccos-api/blob/main/CONTRIBUTING.md) for the full development workflow.

## Disclaimer

Not affiliated with, endorsed by, or connected to Arccos Golf LLC. Use your own
account credentials only. This project is intended for personal data access and
research.

Released under the [MIT License](https://github.com/pfrederiksen/arccos-api/blob/main/LICENSE).
