Metadata-Version: 2.1
Name: edmgr
Version: 0.6.0
Summary: Entitlements and Download Manager
Author: Digital Delivery
Author-email: digital-delivery@arm.com
Maintainer: Arm Ltd.
License: MIT
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Environment :: Console
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click (~=8.1)
Requires-Dist: msal (~=1.18)
Requires-Dist: pyjwt (~=2.4)
Requires-Dist: requests (~=2.28)
Requires-Dist: tabulate (~=0.8)
Requires-Dist: tqdm (~=4.64)

# Entitlements and Download Manager

This package installs a CLI that allows users to see their entitlements,
released products for those entitlements and to download those products.


## Installation

```bash
$ python -m pip install edmgr
```
Python 3.7+ supported. Recommended Python 3.9+.


## Usage - API Wrapper

```python
from edmgr import Client
import os

# Instanciate a Client using a JWT
client = Client(token=os.getenv('access_token'))

# NOTE: Client will look for EDM_ACCESS_TOKEN environment variable, if set it
# will use its value as a token thus a Client instance could be created
# without passing any argument.

client = Client()

# NOTE: Creating a Client instance with token keyword takes precedence over
# EDM_ACCESS_TOKEN environment variable.

# Instanciate a Client using username and password
client = Client(username=os.getenv('username'), password=os.getenv('password'))

# NOTE: When creating a Client instance with username and password, the
# client will obtain an access token and automatically refresh it once
# expired.

# NOTE: When EDM_ACCESS_TOKEN environment variable is set, its value will take
# precendence over username and password login method and won't be refreshedonce expired.

# Get a list of entitlements
response: list = client.get_entitlements()

# Get a paginated list of entitlements
response: list = client.get_entitlements(params={'offset': 1, 'limit': 10})

# Get a list with a single entitlement
response: list = client.get_entitlements(entitlement_id=388295)


# Get a list of releases
response: list = client.get_releases(entitlement_id=388295)

# Get a list with a single release
response: list = client.get_releases(
  entitlement_id=388295, release_id="9456330a-54c6-48b9-a92d-990f9c302b42"
)

# Get a list of artifacts
response: list = client.get_artifacts(
  entitlement_id=388295, release_id="9456330a-54c6-48b9-a92d-990f9c302b42"
)

# Get a list with a single artifact
response: list = client.get_artifacts(
  entitlement_id=388295, release_id="9456330a-54c6-48b9-a92d-990f9c302b42",
  artifact_id="942b3b7d-d6fc-4fb6-ac6f-5afbf898514c"
)

# Get artifact's download url
response: dict = client.get_artifact_download_url(
  entitlement_id=388295, release_id="9456330a-54c6-48b9-a92d-990f9c302b42",
  artifact_id="942b3b7d-d6fc-4fb6-ac6f-5afbf898514c"
)

# Download all artifacts for a release (in the current directory)
artifacts: list = client.get_artifacts(
  entitlement_id=388295, release_id="9456330a-54c6-48b9-a92d-990f9c302b42",
)
for file_name, artifact_id in map(lambda x: (x['fileName'], x['id']), artifacts):
    with open(file_name, "wb") as file:
        client.download_artifact(
          file,
          entitlement_id=388295,
          release_id="9456330a-54c6-48b9-a92d-990f9c302b42",
          artifact_id=artifact_id
        )
```


## Usage - CLI

### Help

```
 $ edmgr --help
Usage: edmgr [OPTIONS] COMMAND [ARGS]...

Options:
  -k, --environment [prod|sandbox|qa]
                                  Configuration environment  [default: prod]
  -v, --verbose
  --help                          Show this message and exit.

Commands:
  artifacts           Print a list of artifacts for a particular release.
  download-artifacts  Download all artifacts for a particular release or...
  entitlements        Print a list of available entitlements.
  login               Login using credentials/token
  logout              Logout by deleting cached token
  releases            Print a list of releases for a particular entitlement.
  show-config         Print configuration
```


### Login

There are three ways to authenticate on EDM.

1. Using a JWT token from the command line: Use `edmgr login token TOKEN`. The
   token will be persisted on disk and used until its expiration. Once the token
   has expired, a new one must be obtained by the user.
2. Using username and password (credentials): Use `edmgr login credentials`
   and press enter. You will be prompted for username and password, or use
   `edmgr login credentials --username USERNAME` and only the password will
   be prompted. An access token will be persisted on disk and refreshed
   automatically when expired.
3. Using a JWT token in an environment variable: Set `EDM_ACCESS_TOKEN="<JWT string>"`.
   The token will **not** be persisted on disk. Once the token has expired, a new
   one must be obtained by the user.

In case more than one authentication method is set, the above order also
determine the precedence of the method used by edmgr.

```
$ edmgr login --help
Usage: edmgr login [OPTIONS] COMMAND [ARGS]...

  Login using credentials/token

Options:
  --help  Show this message and exit.

Commands:
  credentials  Login using username and password
  show-token   Print Access Token as JWT string with some extra information.
  token        Login using JWT string
```


### Entitlements

```
$ edmgr entitlements --help
Usage: edmgr entitlements [OPTIONS]

  Print a list of available entitlements.

Options:
  -e, --entitlement-id INTEGER    Entitlement ID to retrieve one
  -o, --offset INTEGER            Page number to paginate output
  -l, --limit INTEGER             Number of records per page to be displayed.
                                  By default it shows 10 records per page
  -f, --format [table|json|jsonpp]
                                  Output format -> tabular, json or json
                                  prettify  [default: table]
  --help                          Show this message and exit.
```


### Releases

```
$ edmgr releases --help
Usage: edmgr releases [OPTIONS]

  Print a list of releases for a particular entitlement.

Options:
  -e, --entitlement-id INTEGER    Entitlement ID  [required]
  -r, --release-id TEXT           Release ID to retrieve one
  -f, --format [table|json|jsonpp]
                                  Output format -> tabular, json or json
                                  prettify  [default: table]
  --help                          Show this message and exit.
```


### Artifacts

```
$ edmgr artifacts --help
Usage: edmgr artifacts [OPTIONS]

  Print a list of artifacts for a particular release.

Options:
  -e, --entitlement-id INTEGER    Entitlement ID  [required]
  -r, --release-id TEXT           Release ID  [required]
  -a, --artifact-id TEXT          Artifact ID to retrieve one
  -f, --format [table|json|jsonpp]
                                  Output format -> tabular, json or json
                                  prettify  [default: table]
  --help                          Show this message and exit.
```


### Download Artifacts

```
$ edmgr download-artifacts --help
Usage: edmgr download-artifacts [OPTIONS]

  Download all artifacts for a particular release or only a specific one.

Options:
  -e, --entitlement-id INTEGER  Entitlement ID  [required]
  -r, --release-id TEXT         Release ID  [required]
  -a, --artifact-id TEXT        Artifact ID
  -d, --download-dir TEXT       Directory in which artifacts are downloaded.
                                Default: $HOME/Artifacts
  --help                        Show this message and exit.
```

### Shell Completions

Tab completions for Bash (version 4.4 and up), Zsh, and Fish can be enabled by
running the following command in your shell:

```bash
eval "$(_EDMGR_COMPLETE=<shell>_source edmgr)"
```
Where `<shell>` is either `bash`, `zsh` or `fish`


## Environment Variables

The following environment variables can be used to configure both API Wrapper and CLI.

- `EDM_ACCESS_TOKEN`: API authentication JWT, please refer to the above sections for more information
- `EDM_ROOT`: Directory in which EDM will store cached files. If not set, the default is `$HOME/.edm`
- `EDM_DOWNLOADS`: Directory in which EDM will save downloaded artifacts. If not set, the default is `$HOME/Artifacts`
- `EDM_LOG_LEVEL`: EDM log level. Options: critical, error, warning, info, debug. If not set, the default is `info`
- `EDM_ENV`: The name of the configuration environment used. Options: prod, sandbox, qa. If not set, the default is `prod`
