Skip to content

Commit 1bacb76

Browse files
kks32kks32
committed
Update README for uv, TMS credentials, and Jupyter Book v2
1 parent de97f14 commit 1bacb76

1 file changed

Lines changed: 66 additions & 74 deletions

File tree

‎README.md‎

Lines changed: 66 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,36 @@
22

33
[![build and test](https://github.com/DesignSafe-CI/dapi/actions/workflows/build-test.yml/badge.svg)](https://github.com/DesignSafe-CI/dapi/actions/workflows/build-test.yml)
44
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
5-
[![Docs](https://img.shields.io/badge/view-docs-8A2BE2?color=8A2BE2)](https://designsafe-ci.github.io/dapi/dapi/index.html)
5+
[![PyPI version](https://badge.fury.io/py/dapi.svg)](https://badge.fury.io/py/dapi)
6+
[![Docs](https://img.shields.io/badge/view-docs-8A2BE2?color=8A2BE2)](https://designsafe-ci.github.io/dapi/)
67

7-
`dapi` is a library that simplifies the process of submitting, running, and monitoring [TAPIS v3](https://tapis.readthedocs.io/en/latest/) jobs on [DesignSafe](https://designsafe-ci.org) via [Jupyter Notebooks](https://jupyter.designsafe-ci.org).
8+
`dapi` is a Python library that simplifies the process of submitting, running, and monitoring [TAPIS v3](https://tapis.readthedocs.io/en/latest/) jobs on [DesignSafe](https://designsafe-ci.org) via [Jupyter Notebooks](https://jupyter.designsafe-ci.org) or from the command line.
89

910
<img src="https://raw.githubusercontent.com/DesignSafe-CI/dapi/main/dapi.png" alt="dapi" width="300">
1011

11-
1212
## Features
1313

1414
### Jobs
15+
- Generate TAPIS v3 job requests with automatic app parameter mapping
16+
- Submit, monitor (with progress bars), and manage jobs
17+
- Access and download job outputs
18+
- Discover and explore available DesignSafe applications
1519

16-
* Get TAPIS v3 templates for jobs: No need to fiddle with complex API requests. `dapi` abstracts away the complexities.
20+
### TMS Credentials
21+
- Establish, check, and revoke SSH keys on TACC execution systems (Frontera, Stampede3, LS6)
22+
- Works from any environment -- DesignSafe JupyterHub, command line, CI/CD
1723

18-
* Seamless Integration with DesignSafe Jupyter Notebooks: Launch DesignSafe applications directly from the Jupyter environment.
24+
### Files
25+
- Translate DesignSafe paths (`/MyData`, `/CommunityData`, `/projects`) to TAPIS URIs
26+
- Upload, download, and list files on DesignSafe storage
1927

2028
### Database
21-
2229
Connects to SQL databases on DesignSafe:
2330

2431
| Database | dbname | env_prefix |
2532
|----------|--------|------------|
2633
| NGL | `ngl`| `NGL_` |
27-
| Earthake Recovery | `eq` | `EQ_` |
34+
| Earthquake Recovery | `eq` | `EQ_` |
2835
| Vp | `vp` | `VP_` |
2936

3037
Define the following environment variables:
@@ -37,115 +44,100 @@ Define the following environment variables:
3744

3845
For e.g., to add the environment variable `NGL_DB_USER` edit `~/.bashrc`, `~/.zshrc`, or a similar shell-specific configuration file for the current user and add `export NGL_DB_USER="dspublic"`.
3946

40-
4147
## Installation
4248

43-
Install `dapi` via pip
44-
4549
```shell
46-
pip3 install dapi
50+
pip install dapi
4751
```
4852

49-
To install the current development version of the library use:
53+
To install the current development version:
5054

5155
```shell
5256
pip install git+https://github.com/DesignSafe-CI/dapi.git --quiet
5357
```
5458

55-
## Example usage:
59+
## Quick Start
5660

57-
### Storing credentials
61+
### Authentication
5862

59-
Dapi uses the Tapis v3 SDK to authenticate with the DesignSafe API. To store your credentials, create a `.env` file in the root of your project with the following content:
63+
Create a `.env` file with your DesignSafe credentials:
6064

6165
```shell
62-
DESIGNSAFE_USERNAME=<your_designsafe_username>
63-
DESIGNSAFE_PASSWORD=<your_designsafe_password>
66+
DESIGNSAFE_USERNAME=your_username
67+
DESIGNSAFE_PASSWORD=your_password
6468
```
6569

66-
### Jobs
67-
68-
* [Jupyter Notebook Templates](example-notebooks/template-mpm-run.ipynb) using dapi.
69-
70-
* View [dapi API doc](https://designsafe-ci.github.io/dapi/dapi/index.html)
71-
72-
On [DesignSafe Jupyter](https://jupyter.designsafe-ci.org/):
73-
74-
Install the latest version of `dapi` and restart the kernel (Kernel >> Restart Kernel):
70+
### Setup and submit a job
7571

7672
```python
77-
# Remove any previous installations
78-
!pip uninstall dapi -y
79-
# Install
80-
!pip install dapi --quiet
81-
```
82-
83-
* Import `dapi` library
84-
```python
85-
import dapi
86-
```
87-
88-
* To list all functions in `dapi`
89-
```python
90-
dir(dapi)
73+
from dapi import DSClient
74+
75+
# Authenticate
76+
client = DSClient()
77+
78+
# Establish TMS credentials (one-time per system)
79+
client.systems.establish_credentials("frontera")
80+
81+
# Submit a job
82+
job_request = client.jobs.generate_request(
83+
app_id="matlab-r2023a",
84+
input_dir_uri="/MyData/analysis/input/",
85+
script_filename="run_analysis.m",
86+
max_minutes=30,
87+
allocation="your_allocation"
88+
)
89+
job = client.jobs.submit_request(job_request)
90+
final_status = job.monitor()
9191
```
9292

9393
### Database
94+
9495
```python
95-
from dapi.db import DSDatabase
96+
from dapi import DSClient
9697

97-
db = DSDatabase("ngl")
98-
sql = 'SELECT * FROM SITE'
99-
df = db.read_sql(sql)
98+
client = DSClient()
99+
df = client.db.ngl.read_sql("SELECT * FROM SITE LIMIT 10")
100100
print(df)
101-
102-
# Optionally, close the database connection when done
103-
db.close()
104101
```
105102

106-
107103
## Support
108104

109-
For any questions, issues, or feedback submit an [issue](https://github.com/DesignSafe-CI/dapi/issues/new)
105+
For any questions, issues, or feedback submit an [issue](https://github.com/DesignSafe-CI/dapi/issues/new).
110106

111107
## Development
112108

113-
To develop or test the library locally. Install [Poetry](https://python-poetry.org/docs/#installation). In the current repository run the following commands
109+
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
114110

115111
```shell
116-
poetry shell
117-
poetry install
118-
poetry build
112+
uv venv
113+
uv pip install -e ".[dev]"
119114
```
120115

121-
To run the unit test
116+
Run tests:
122117
```shell
123-
poetry run pytest -v
118+
pytest tests/ -v
124119
```
125120

121+
Build the package:
122+
```shell
123+
uv build
124+
```
126125

127-
## License
128-
129-
`dapi` is licensed under the [MIT License](LICENSE.md).
130-
131-
## Authors
132-
133-
* Krishna Kumar, University of Texas at Austin
134-
* Prof. Pedro Arduino, University of Washington
135-
* Prof. Scott Brandenberg, University of California Los Angeles
136-
126+
### Documentation
137127

138-
## Documentation
128+
Documentation uses [Jupyter Book v2](https://mystmd.org). To build and serve locally:
139129

140-
View [dapi API doc](https://designsafe-ci.github.io/dapi/dapi/index.html)
130+
```shell
131+
uv pip install -e ".[docs]"
132+
jupyter-book start
133+
```
141134

142-
### Running documentation locally
135+
## License
143136

144-
To serve the MkDocs documentation locally:
137+
`dapi` is licensed under the [MIT License](LICENSE.md).
145138

146-
```shell
147-
poetry install
148-
poetry run mkdocs serve
149-
```
139+
## Authors
150140

151-
This will start a local server at `http://127.0.0.1:8000/dapi/` where you can view the documentation.
141+
- Krishna Kumar, University of Texas at Austin
142+
- Prof. Pedro Arduino, University of Washington
143+
- Prof. Scott Brandenberg, University of California Los Angeles

0 commit comments

Comments
 (0)