ideas-python 1.1.1
IDEAS Python library and CLI
Requires Python: >=3.10

# IDEAS Python

This package provides a python API and a CLI to interact with the [IDEAS platform](https://inscopix.cloud/).

1. [Installation](#installation)
2. [Running](#running)
3. [Configuration](#configuration)
    * [With config file](#configuring-with-config-file)
    * [Through arguments](#configuring-through-arguments)
4. [Shell completion](#shell-completion)

---

## Installation

Requirements:
- `python >= 3.11`

### Installing

The recommended way to install IDEAS Python is with [pip](https://pip.pypa.io/en/stable/) in a virtualenv:

```shell
python3 -m venv venv
pip install ideas-python
```

### Running

Installing adds the `ideas` command to the virtualenv. You can either run it directly from the
virtualenv with `venv/bin/ideas`, or symlink it to a directory in your shell's `PATH` variable:

```bash
# by activating the virtualenv
source venv/bin/activate
# OR, manually
ln -sf $(pwd)/venv/bin/ideas ~/.local/bin/ideas
```

**Note on Windows**: For windows, run these commands instead in a [git-bash](https://git-scm.com/downloads) to make `ideas` available in your path:

```bash
mkdir -p ~/.local/bin && touch ~/.bash_profile && echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bash_profile && source ~/.bash_profile
ln -sf $(pwd)/venv/Scripts/ideas.exe ~/.local/bin/ideas.exe
```

Now you can run the CLI directly:
```bash
ideas
```

## Configuration

As `ideas` interfaces with the IDEAS platform, it must authenticate, and we provide two ways to
do so: through CLI parameters (like `--username`), or through a configuration wizard.

### Configuration wizard

`ideas` offers a handy shortcut to edit your configuration interactively:

```bash
ideas configure
```

You will be asked for:
- Which region are you in: this corresponds to which region you specified as your home region when you signed up for your IDEAS account.
- Your credentials: use the email address and password you sign into IDEAS with.
- [Optional] You may be asked which tenant you would like to use, if you belong to multiple tenants.

You may call `ideas configure` again at any point to change these values.

### Configuring and using profiles

It is possible also to configure multiple profiles, with arbitrary names. This could be for accessing different regions, using separate accounts, or selecting another tenant ID.

```bash
ideas --profile us configure
ideas --profile jp configure
```

A given profile can then be used by specifying the profile:

```commandline
ideas --profile jp tenants
```

### Configuring through arguments

Alternatively, you can configure `ideas` through arguments. If no configuration file exists,
`ideas` will exclusively use arguments. If you have a configuration file, these arguments will
override the file:

| CLI argument     | Config file name | Description                                                                                 |
|------------------|------------------|---------------------------------------------------------------------------------------------|
| `-e/--env`       | `env`            | Which environment to use. List supported environments with `ideas environments`.        |
| `-u/--username`  | `username`       | Your IDEAS username/email address.                                                          |
| `-p/--password`  | `password`       | The password you log into IDEAS with.                                                       |
| `-t/--tenant-id` | `tenant_id`      | The numerical ID of the tenant you want to use. List your tenants with `ideas tenants`. |

## Shell completion

You can optionally enable shell completion for the `ideas` command. We provide tab completion support for Bash (version 4.4 and up), Zsh, and Fish shells.

### Bash

```bash
# Save the script somewhere
_IDEAS_COMPLETE=bash_source ideas > ~/.ideas-complete.bash

# Source the file in ~/.bashrc
. ~/.ideas-complete.bash
```

### Zsh

```zsh
# Save the script somewhere.
_IDEAS_COMPLETE=zsh_source ideas > ~/.ideas-complete.zsh

# Source the file in ~/.zshrc.
. ~/.ideas-complete.zsh

```

### Fish

```fish
# Save the script to ~/.config/fish/completions/ideas.fish:
_IDEAS_COMPLETE=fish_source ideas > ~/.config/fish/completions/ideas.fish
```

After modifying the shell config, you need to start a new shell in order for the changes to be loaded.