Metadata-Version: 2.1
Name: slivka-client
Version: 1.2.1b1
Summary: A Python client for Slivka services
Home-page: https://github.com/bartongroup/slivka-python-client
Author: Mateusz Warowny
Author-email: m.m.z.warowny@dundee.ac.uk
Maintainer: Stuart MacGowan
Maintainer-email: smacgowan@dundee.ac.uk
Project-URL: Documentation, https://github.com/bartongroup/slivka-python-client#readme
Project-URL: Source, https://github.com/bartongroup/slivka-python-client
Project-URL: Tracker, https://github.com/bartongroup/slivka-python-client/issues
Project-URL: Organization, https://www.compbio.dundee.ac.uk/drsasp.html
Keywords: slivka,client,bioinformatics,computational biology,REST API
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: attrs>=19.3
Requires-Dist: click>=7.0
Requires-Dist: requests>=2.13.0


# Slivka Python Client

[![PyPI version](https://badge.fury.io/py/slivka-client.svg)](https://badge.fury.io/py/slivka-client)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

Slivka Python client is a convenience wrapper around the popular [requests](https://requests.readthedocs.io/en/latest/) library. It provides an interface for communicating with the Slivka REST API using Python.

## Features

- Programmatic access to Slivka API with simple objects.
- Command-line interface.
- Interactive widgets for Jupyter notebooks.

---

## Installation

The easiest way to install the Slivka client is via `pip` from PyPI:

```bash
pip install slivka-client
```

Alternatively, if you prefer to use the conda package manager, you can install it from the Slivka channel:

```bash
conda install -c slivka slivka-client
```

To install it from the source code, clone the Git repository to your machine and run:

```bash
python setup.py install
```

---

## Getting Started

After installing the Slivka client, you can begin by importing it and connecting to a Slivka server:

```python
import slivka_client

# Replace with your actual server URL
client = slivka_client.SlivkaClient("https://your-slivka-server-url/")
```

You can verify the connection by checking the server version:

```python
print(client.version)
```

---

## Usage

### Accessing Services

To retrieve the list of available services from the Slivka server:

```python
services = client.services
```

Each element in the list is a `Service` object containing details such as the service's `id`, `name`, and `description`.

To access a specific service by its ID, use:

```python
service = client.get_service('example_service_id')
# Or
service = client['example_service_id']
```

---

### Starting Jobs

Once you've selected the desired service, you can submit jobs using the `submit_job()` method. This requires providing parameters in the form of dictionaries.

Here’s an example of submitting a job:

```python
data = {
    'param0': 13,
    'param1': 'foobar'
}

files = {
    'input0': open("input-file.txt", "rb"),
    'input1': b"data data data data\n"
}

job = service.submit_job(data=data, files=files)
```

This method returns a `Job` object that allows you to monitor the status and retrieve results.

### Polling Jobs and Retrieving Results

You can check the status of a submitted job using:

```python
print(job.status)
```

To retrieve the results:

```python
for result in job.results:
    result.dump("output_file.txt")
```

### File Handling

The `File` object provides a convenient way to download results:

```python
result = job.results[0]
result.dump("output_file.txt")
```

The `File` object properties include:

- **url**: Location of the resource.
- **content_url**: Location of the file content.
- **id**: Identifier of the file (can be used as input for other jobs).
- **job_id**: ID of the job this file is a result of.
- **path**: Real path and name of the file.
- **label**: Name describing the file.
- **media_type**: Media type of the file.

---

## Command-Line Interface (CLI)

The `slivka-cli` command-line tool allows for interaction with the Slivka API without writing Python scripts.

To get started:

```bash
slivka-cli --help
```

This will provide you with usage instructions and available commands.

---

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

---

## Support

If you have any questions or need assistance, please open an issue on our [GitHub repository](https://github.com/bartongroup/slivka-python-client/issues).
