viqi-api 0.6.25
ViQi Python API
Requires Python: >=3.8

# ViQi API

Low level interface to ViQi services


## Install


`pip install viqi-api `

## Configuration

For command line tools create `~/.config/viqi/profiles`  or `~/config/viqi/profiles`` (windows) with the following

```
[default]
host=https://science.viqiai.cloud
user=myuser
password=mysecret

[science-user2]
host=https://science.viqiai.cloud
user=myuser2
password=mysecret2

# Admin can switch to another user
[science-secret-user]
host=https://science.viqiai.cloud
user=admin@viqi.org
password=admin_secret
alias=secret-user@viqi.org
```

## Documentation
* [viqi-api](https://viqi.gitlab.io/viqi-common/bisque-api/)
  1. [Service-oriented API](https://viqi.gitlab.io/viqi-common/bisque-api/soapi.html)
  1. [Object-oriented API](https://viqi.gitlab.io/viqi-common/bisque-api/ooapi.html)


## Usage & Initialization

The `viqi_session` helper provides a flexible way to initialize a session, whether from command line arguments, configuration files, or direct parameters in Python.

### 1. From Command Line Arguments (Scripts)

When used in a script without arguments, `viqi_session()` automatically parses `sys.argv`. This is the standard way to write scripts that can be configured via flags or config files.

**myscript.py**:
```python
from vqapi import viqi_session
session = viqi_session()

if session:
    # Session is ready and connected
    print(f"Connected to {session.bqServer} as {session.user}")

    # Access services
    meta = session.service("meta")
    # ...
```

**Run it:**
```bash
# Using explicit credentials
python myscript.py --host https://science.viqiai.cloud --user myuser --password mysecret

# Using a profile defined in ~/.config/viqi/profiles
python myscript.py --profile default
```

### 2. From Python Parameters (Interactive/Library)

You can pass arguments directly as keyword arguments. This is useful for interactive sessions (like IPython/Jupyter) or when embedding the library.

```python
from vqapi import viqi_session

# Using a profile defined in ~/.config/viqi/profiles
session = viqi_session(profile="science-user2")

# Using explicit credentials
session = viqi_session(
    host="https://science.viqiai.cloud",
    user="myuser",
    password="mysecret"
)

# Using an auth token
session = viqi_session(
    host="https://science.viqiai.cloud",
    authtoken="YOUR_AUTH_TOKEN"
)
```

### 3. Simulating Command Line Arguments

You can pass a list of strings to `args` to simulate command line input.

```python
session = viqi_session(args=["--host", "https://science.viqiai.cloud", "--user", "admin", "--password", "secret"])
```

### 4. Custom Argument Parser

If your script requires its own custom arguments, you can extend the standard ViQi parser.

```python
import argparse
from vqapi import viqi_session, viqi_argument_parser

# 1. Start with the standard ViQi parser
parser = viqi_argument_parser()

# 2. Add your custom arguments
parser.add_argument("--dataset-id", required=True, help="ID of dataset to process")

# 3. Parse args (handles both ViQi args and custom args)
args = parser.parse_args()

# 4. Initialize session using the parsed arguments
session = viqi_session(args=args)

# 5. Use your custom argument
print(f"Processing dataset: {args.dataset_id}")
```