armis-sdk 1.1.0
The Armis SDK is a package that encapsulates common use-cases for interacting with the Armis platform.
Requires Python: >=3.9

# Armis SDK for Python 3.9+
[![Run tests](https://github.com/ArmisSecurity/armis-sdk-python/actions/workflows/test.yml/badge.svg)](https://github.com/ArmisSecurity/armis-sdk-python/actions/workflows/test.yml)
[![Run formatter](https://github.com/ArmisSecurity/armis-sdk-python/actions/workflows/format.yml/badge.svg)](https://github.com/ArmisSecurity/armis-sdk-python/actions/workflows/format.yml)
[![Run linter](https://github.com/ArmisSecurity/armis-sdk-python/actions/workflows/lint.yml/badge.svg)](https://github.com/ArmisSecurity/armis-sdk-python/actions/workflows/lint.yml)

The Armis SDK is a package that encapsulates common use-cases for interacting with the [Armis platform](https://www.armis.com/).

## Installation
Use your favourite package manager to install the SDK, for example:
```shell
pip install armis_sdk
```

## Documentation
For full documentation, please visit our [dedicated](https://armis-python-sdk.readthedocs.io) site.

## Usage

All interaction with the SDK happens through the `ArmisSdk` class. You'll need five things:

1. **Audience**: The url of the tenant you want to interact with, including trailing slash (e.g. `https://acme.armis.com/`).
2. **Client ID**: The email address of the user account within the tenant that was used to generate the Client Secret.
3. **Client Secret**: The confidential credential generated by your customer within Armis, paired with the Client ID.
4. **Vendor ID**: An identifier unique to your developer account or integration, obtained when you register on our developer portal.
5. **Scopes**: The specific permissions required by your access token to interact with the desired API endpoints.

You can either provide these values using the environment variables `ARMIS_AUDIENCE`, `ARMIS_CLIENT_ID`, `ARMIS_CLIENT_SECRET`, `ARMIS_VENDOR_ID`, and `ARMIS_CLIENT_ID`:
```python
from armis_sdk import ArmisSdk

armis_sdk = ArmisSdk()
```

or by passing them explicitly:
```python
from armis_sdk import ArmisSdk
from armis_sdk import ClientCredentials

credentials = ClientCredentials(
    audience="<audience>",
    client_id="<client_id>",
    client_secret="<client_secret>",
    vendor_id="<vendor_id>",
    scopes=["scope1", "scope2"],
)
armis_sdk = ArmisSdk(credentials=credentials)
```

> [!TIP]
> If you're building an application that interacts with multiple tenants, you can populate only the `ARMIS_VENDOR_ID` and `ARMIS_SCOPES` environment variable and pass the `audience`, `client_id` and `client_secret` explicitly:
> ```python
> from armis_sdk import ArmisSdk
> from armis_sdk import ClientCredentials
>
> credentials = ClientCredentials(
>     audience="<audience>",
>     client_id="<client_id>",
>     client_secret="<client_secret>",
> )
> armis_sdk = ArmisSdk(credentials=credentials)
> ```

## Entity clients
Once you have an instance of `ArmisSdk`, you can start interacting with the various clients. Each handles use-cases of a specific entity.


> [!NOTE]
> Note that all functions in this SDK that eventually make HTTP requests are asynchronous.
> 
> However, for convenience, all public asynchronous functions can also be executed in a synchronous way. 

For example, if you want to update a site's location:
```python
import asyncio

from armis_sdk import ArmisSdk
from armis_sdk.entities.site import Site

armis_sdk = ArmisSdk()

async def main():
    site = Site(id=1, location="new location")
    await armis_sdk.sites.update(site)

asyncio.run(main())
```