Metadata-Version: 2.4
Name: arcticsecurity
Version: 0.1.0
Summary: Library to access Arctic Security APIs
Author: Arctic Security
Author-email: Arctic Security <pypi@arcticsecurity.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
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 :: Only
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.28.1
Requires-Python: >=3.9
Project-URL: Home, https://github.com/arcticsecurity/arcticsecurity-python
Project-URL: Issues, https://github.com/arcticsecurity/arcticsecurity-python/issues
Description-Content-Type: text/markdown

# Arctic Security Library

A Python library to access Arctic Security's Sharing API endpoints and retrieve event data.

## Installation

```bash
pip install arcticsecurity
```

Python >= 3.9 is required.

## Quick Start

The library supports two distinct ways to retrieve events from the Sharing API: `Query` and `Sync`.

### Query

Use the `Query` class to perform one-off queries for specific events.

```python
from arcticsecurity.sharing_api import Query

url = "https://example.com/shares/v2/share-id?apikey=YOUR_API_KEY"
for event in Query(url).query(filter='"network owner"="Example Co"', max_events=50):
    print(event)
```

### Sync

Use the `Sync` class to reliably fetch all event data. It uses pagination with opaque continuation tokens to ensure no events are missed.

```python
from arcticsecurity.sharing_api import Sync

url = "https://example.com/shares/v2/share-id?apikey=YOUR_API_KEY"
sync = Sync(url, filter='"network owner"="Example Co"')

# Fetch token from previous run
token = ...

while True:
    res = sync.read(token=token, pagesize=1000)
    if not res.events:
        break
    # process res.events...

    token = res.token

    if not res.has_more:
       break

# store the token for the next run
```

## Common features

- Robust error handling with specific exceptions (`ConfigError`, `NetworkError`, `Retry`, `TimeoutError`, `InvalidTokenError`, `ServerError`).
- Optional timeout and user-agent customization

## Versioning

Follows [Semantic Versioning v2](https://semver.org/spec/v2.0.0.html).

## Development

[uv](https://docs.astral.sh/uv/) is required.

```bash
uv sync --group dev

uv run ruff check .
uv run pytest --doctest-modules

uv run mypy --config-file pyproject.toml -p arcticsecurity
uv run ty check

uv run mkdocs build
uv run mkdocs serve
```

## Contributing

Issues and pull requests are welcome. Please add tests for any new behavior.

## Status

Experimental (`0.1.x`); the API may evolve. Pin the library version for production use.
