Dapi examples 0.5.0

Author: kks32

README.md

@@ -5,7 +5,7 @@
 [![PyPI version](https://badge.fury.io/py/dapi.svg)](https://badge.fury.io/py/dapi)
 [![Docs](https://img.shields.io/badge/view-docs-8A2BE2?color=8A2BE2)](https://designsafe-ci.github.io/dapi/)
 
-`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.
+`dapi` is a Python library for 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 the command line.
 
 <img src="https://raw.githubusercontent.com/DesignSafe-CI/dapi/main/dapi.png" alt="dapi" width="300">
 
@@ -50,10 +50,29 @@ For e.g., to add the environment variable `NGL_DB_USER` edit `~/.bashrc`, `~/.zs
 pip install dapi
 ```
 
-To install the current development version:
+To install the development version:
 
 ```shell
-pip install git+https://github.com/DesignSafe-CI/dapi.git --quiet
+pip install git+https://github.com/DesignSafe-CI/dapi.git@dev --quiet
+```
+
+In Jupyter notebooks:
+
+```python
+%pip install dapi --quiet
+```
+
+To test the latest dev branch in a notebook:
+
+```python
+%pip uninstall dapi --yes
+%pip install git+https://github.com/DesignSafe-CI/dapi.git@dev --quiet
+```
+
+For local development (editable install — changes to source are reflected immediately):
+
+```shell
+pip install -e .
 ```
 
 ## Quick Start

_toc.yml

@@ -1,56 +1,26 @@
-"""Dapi - A Python wrapper for interacting with DesignSafe resources via the Tapis API.
+"""Python client for submitting, monitoring, and managing TAPIS v3 jobs on DesignSafe.
 
-This package provides a high-level, user-friendly interface for working with DesignSafe
-resources through the Tapis V3 API. It simplifies complex operations and provides
-organized access to different service areas including authentication, file operations,
-job submission and monitoring, application discovery, system information, and database access.
+Also provides access to DesignSafe research databases (NGL, Earthquake Recovery, VP)
+and file operations (path translation, upload, download).
 
-Key Features:
-    - Simplified authentication with credential resolution hierarchy
-    - DesignSafe path translation (MyData, projects, etc.) to Tapis URIs
-    - High-level job submission with automatic app parameter mapping
-    - Job monitoring with progress bars and status interpretation
-    - File upload/download with automatic directory creation
-    - Application discovery and detailed retrieval
-    - System queue information and resource limits
-    - Database access for DesignSafe research databases
-    - Comprehensive error handling with descriptive exceptions
+Classes:
+    DSClient: Entry point. Provides access to jobs, files, apps, systems, and databases.
+    SubmittedJob: Returned by ``DSClient.jobs.submit()``. Used to monitor and inspect a job.
 
-Main Components:
-    DSClient: Main client class providing organized access to all services
-    SubmittedJob: Class for managing and monitoring submitted Tapis jobs
-    Exception classes: Specific exceptions for different error types
+Example::
 
-Example:
-    Basic usage with automatic authentication:
+    from dapi import DSClient
 
-    >>> from dapi import DSClient
-    >>> client = DSClient()
-    Enter DesignSafe Username: myuser
-    Enter DesignSafe Password: [hidden]
-    Authentication successful.
+    client = DSClient()
+    job_request = client.jobs.generate(
+        app_id="matlab-r2023a",
+        input_dir_uri="/MyData/analysis/input/",
+        script_filename="run_analysis.m",
+    )
+    job = client.jobs.submit(job_request)
+    final_status = job.monitor()
 
-    >>> # File operations
-    >>> client.files.upload("/local/file.txt", "/MyData/uploads/file.txt")
-    >>> files = client.files.list("/MyData/uploads/")
-
-    >>> # Job submission and monitoring
-    >>> job_request = client.jobs.generate(
-    ...     app_id="matlab-r2023a",
-    ...     input_dir_uri="/MyData/analysis/input/",
-    ...     script_filename="run_analysis.m",
-    ... )
-    >>> job = client.jobs.submit(job_request)
-    >>> final_status = job.monitor()
-
-    >>> # Database access
-    >>> df = client.db.ngl.read_sql("SELECT * FROM earthquake_data LIMIT 10")
-
-Attributes:
-    __version__ (str): The version number of the dapi package.
-    DSClient: Main client class for DesignSafe API interactions.
-    SubmittedJob: Class for managing submitted Tapis jobs.
-    Exception classes: Custom exceptions for specific error conditions.
+    df = client.db.ngl.read_sql("SELECT * FROM SITE LIMIT 10")
 """
 
 from .client import DSClient