Metadata-Version: 2.4
Name: stare
Version: 0.3.0rc4
Summary: Python library and CLI for the CERN ATLAS Glance/Fence API
Project-URL: Documentation, https://stare-atlas.readthedocs.io/
Project-URL: Homepage, https://github.com/kratsg/stare
Project-URL: Bug Tracker, https://github.com/kratsg/stare/issues
Project-URL: Discussions, https://github.com/kratsg/stare/discussions
Project-URL: Changelog, https://github.com/kratsg/stare/releases
Author-email: Giordon Stark <kratsg@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: filelock>=3.13
Requires-Dist: hishel>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: lark>=1.2
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic-settings>=2
Requires-Dist: pydantic>=2
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: rich>=13
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer[all]>=0.12
Description-Content-Type: text/markdown

# stare

Python library and CLI for the
[CERN ATLAS Glance/Fence API](https://atlas-glance.cern.ch/atlas/analysis/api/docs/).

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]
[![PyPI version][pypi-version]][pypi-link]

[actions-badge]:
  https://github.com/kratsg/stare/actions/workflows/ci.yml/badge.svg
[actions-link]: https://github.com/kratsg/stare/actions/workflows/ci.yml
[rtd-badge]: https://readthedocs.org/projects/stare-atlas/badge/?version=latest
[rtd-link]: https://stare-atlas.readthedocs.io/en/latest/?badge=latest
[pypi-version]: https://img.shields.io/pypi/v/stare.svg
[pypi-link]: https://pypi.org/project/stare/

## Installation

```bash
python -m pip install stare
```

## Authentication

`stare` uses PKCE (no passwords stored). Run once to authenticate:

```bash
stare auth login
```

Your browser will open CERN SSO. After approval, tokens are stored locally and
refreshed automatically.

## CLI usage

```bash
# Search analyses — Rich table in terminal, JSON when piped
stare analysis search
stare analysis search --query 'referenceCode = ANA-HION-2018-01'
stare analysis search -q 'keywords contain Higgs' --limit 20
stare analysis search -q 'shortTitle = "Phase Closed"'

# Pipe to jq for field selection (JSON is auto-emitted)
stare analysis search | jq '.results[].referenceCode'
stare analysis search -q 'referenceCode contain HION' \
  | jq -r '.results[] | select(.status == "Active") | .referenceCode'

# Search papers
stare paper search --query 'referenceCode = HDBS-2018-33'

# Get individual resources
stare analysis get ANA-HION-2018-01
stare paper get HDBS-2018-33

# CONF notes / PUB notes
stare confnote get ATLAS-CONF-2024-001
stare pubnote get ATL-PHYS-PUB-2024-001

# List metadata
stare groups
stare subgroups

# Auth management
stare auth login
stare auth logout
stare auth status

# Cache management
stare cache info
stare cache clear --yes
```

Output is a Rich table when stdout is a terminal and JSON when piped or
redirected. Use `--json` / `--no-json` to override. Commands that expose
`--no-cache` bypass the 8-hour on-disk response cache for that invocation.

## Library usage

```python
from stare import Glance

g = Glance()

# Search analyses
result = g.analyses.search(query="referenceCode = ANA-HION-2018-01")
print(f"Found {result.number_of_results} analyses")
for analysis in result.results:
    print(analysis.reference_code, analysis.short_title)

# Search papers
paper_result = g.papers.search(query="referenceCode = HDBS-2018-33")
print(f"Found {paper_result.number_of_results} papers")
for paper in paper_result.results:
    print(paper.reference_code, paper.short_title)

# Fetch individual records (search-based under the hood)
analysis = g.analyses.get("ANA-HION-2018-01")
paper = g.papers.get("HDBS-2018-33")
conf_note = g.confnotes.get("ATLAS-CONF-2024-001")
pub_note = g.pubnotes.get("ATL-PHYS-PUB-2024-001")
groups = g.groups.list()
```

Use as a context manager for explicit connection lifecycle:

```python
with Glance() as g:
    result = g.analyses.search(query="status = Active")
```

Inject a token directly (useful in CI/automated scripts):

```python
g = Glance(token="your-access-token")
```

## Configuration

Override defaults via environment variables:

| Variable              | Default                                           |
| --------------------- | ------------------------------------------------- |
| `STARE_BASE_URL`      | `https://atlas-glance.cern.ch/atlas/analysis/api` |
| `STARE_CLIENT_ID`     | `stare`                                           |
| `STARE_AUTH_URL`      | CERN Keycloak auth endpoint                       |
| `STARE_TOKEN_URL`     | CERN Keycloak token endpoint                      |
| `STARE_CALLBACK_PORT` | `8182` (must match Keycloak registration)         |

## Development

```bash
git clone https://github.com/kratsg/stare
cd stare
pixi install
pixi run pre-commit-install
pixi run stare auth login
pixi run test
```
