Merge pull request #77 from runpod/api_functions

Api functions

Author: justinmerrell

README.md

@@ -22,9 +22,9 @@ Official Python library for RunPod API & SDK.
 - [SDK - Serverless Worker](#sdk---serverless-worker)
   - [Quick Start](#quick-start)
   - [Local Test Worker](#local-test-worker)
-- [API Language Library](#api-language-library)
+- [API Language Library (GraphQL Wrapper)](#api-language-library-graphql-wrapper)
   - [Endpoints](#endpoints)
-  - [GPU Pod Control](#gpu-pod-control)
+  - [GPU Cloud (Pods)](#gpu-cloud-pods)
 - [Directory](#directory)
 - [Community and Contributing](#community-and-contributing)
 
@@ -79,7 +79,7 @@ You can also test your worker locally before deploying it to RunPod. This is use
 python my_worker.py --rp_serve_api
 ```
 
-## API Language Library
+## API Language Library (GraphQL Wrapper)
 
 When interacting with the RunPod API you can use this library to make requests to the API.
 
@@ -118,7 +118,7 @@ run_request = endpoint.run_sync(
 print(run_request )
 ```
 
-### GPU Pod Control
+### GPU Cloud (Pods)
 
 ```python
 import runpod
@@ -143,7 +143,10 @@ runpod.terminate_pod(pod.id)
 ```BASH
 .
 ├── docs               # Documentation
+├── examples           # Examples
 ├── runpod             # Package source code
+│   ├── api_wrapper    # Language library - API (GraphQL)
+|   ├── cli            # Command Line Interface Functions
 │   ├── endpoint       # Language library - Endpoints
 │   └── serverless     # SDK - Serverless Worker
 └── tests              # Package tests

docs/serverless/functions/error_handling.md

@@ -0,0 +1,16 @@
+## Error Handling
+
+The worker is designed to handle errors raised by the handler gracefully. If the handler raises an error, the worker will capture this error and return it as the job output along with the stack trace.
+
+If you want to return a custom error within the handler, this can be accomplished by returning a dictionary with a top-level key of `error` and a value of the error message. The worker will then return this error message as the job output.
+
+### Example
+
+```python
+def handler_with_custom_error(job):
+    if job["id"] == "invalid_job":
+        return {"error": "Invalid job ID"}
+    else:
+        # Handle the job and return the output
+        return {"output": "Job completed successfully"}
+```

docs/serverless/functions/logging.md

@@ -0,0 +1,25 @@
+## Logging
+
+The worker outputs logs to the console at different points in the workers lifecycle. These logs can be used to debug issues with the worker or handler. There are four logging levels that can be used to control the verbosity of the logs:
+
+   0. `NOTSET` - Does not output any logs.
+
+   1. `DEBUG` (Default) - Outputs all logs, including debug logs.
+
+   2. `INFO` - Outputs all logs except debug logs.
+
+   3. `WARNING` - Outputs only warning and error logs.
+
+   4. `ERROR` - Outputs only error logs.
+
+### Setting the Logging Level
+
+There are two ways to set the logging level:
+
+   1. Set the `RUNPOD_DEBUG_LEVEL` environment variable to one of the above logging levels.
+
+   2. Set the `rp_log_level` argument when calling the file with your handler. If this value is set, it will override the `RUNPOD_DEBUG_LEVEL` environment variable.
+
+        ```python
+        python worker.py --rp_log_level='INFO'
+        ```

docs/serverless/worker.md

@@ -1,47 +1,30 @@
 # The Serverless Worker
 
-## Logging
+Both RunPod official endpoints as well as custom built endpoints function by means of a worker that fetches available jobs, passes them into a handler and then returns the output.
 
-The worker outputs logs to the console at different points in the workers lifecycle. These logs can be used to debug issues with the worker or handler. There are four logging levels that can be used to control the verbosity of the logs:
+A worker entry point is a python file containing the command `runpod.serverless.start(config)`. An minimal worker file is shown below:
 
-   0. `NOTSET` - Does not output any logs.
-
-   1. `DEBUG` (Default) - Outputs all logs, including debug logs.
-
-   2. `INFO` - Outputs all logs except debug logs.
-
-   3. `WARNING` - Outputs only warning and error logs.
-
-   4. `ERROR` - Outputs only error logs.
-
-### Setting the Logging Level
-
-There are two ways to set the logging level:
-
-   1. Set the `RUNPOD_DEBUG_LEVEL` environment variable to one of the above logging levels.
+```python
+import runpod
 
-   2. Set the `rp_log_level` argument when calling the file with your handler. If this value is set, it will override the `RUNPOD_DEBUG_LEVEL` environment variable.
+def handler(job):
+    # Handle the job and return the output
+    return {"output": "Job completed successfully"}
 
-        ```python
-        python worker.py --rp_log_level='INFO'
-        ```
+runpod.serverless.start({"handler": handler})
+```
 
-## Error Handling
+## config
 
-The worker is designed to handle errors raised by the handler gracefully. If the handler raises an error, the worker will capture this error and return it as the job output along with the stack trace.
+The `config` parameter is a dictionary containing the following keys:
 
-If you want to return a custom error within the handler, this can be accomplished by returning a dictionary with a top-level key of `error` and a value of the error message. The worker will then return this error message as the job output.
+| Key       | Type       | Description                                                  |
+|-----------|------------|--------------------------------------------------------------|
+| `handler` | `function` | The handler function that will be called with the job input. |
 
-### Example
+### handler
 
-```python
-def handler_with_custom_error(job):
-    if job["id"] == "invalid_job":
-        return {"error": "Invalid job ID"}
-    else:
-        # Handle the job and return the output
-        return {"output": "Job completed successfully"}
-```
+The handler function can either had a standard return or be a generator function. If the handler is a generator function, it will be called with the job input and the generator will be iterated over until it is exhausted.
 
 ## Worker Refresh
 

requirements.txt

@@ -6,6 +6,7 @@ pillow >= 9.5.0
 py-cpuinfo == 9.0.0
 python-dotenv >= 1.0.0
 requests >= 2.31.0
+tomli >= 2.0.1
 tqdm-loggable == 0.1.4
 setuptools_scm == 7.1.0
 

runpod/__init__.py

@@ -9,6 +9,7 @@
     get_gpus, get_gpu,
     create_pod, stop_pod, resume_pod, terminate_pod
 )
+from .cli.config import set_credentials, check_credentials, get_credentials
 
 api_key = None  # pylint: disable=invalid-name
 

runpod/cli/__init__.py

@@ -0,0 +1 @@
+''' Allows the CLI to be imported as a module. '''

runpod/cli/config.py

@@ -0,0 +1,65 @@
+'''
+runpod | cli | config.py
+
+A collection of functions to set and validate configurations.
+Configurations are TOML files located under ~/.runpod/
+'''
+
+import os
+
+import tomli as toml
+
+CREDENTIAL_FILE = os.path.expanduser('~/.runpod/credentials.toml')
+
+def set_credentials(api_key: str) -> None:
+    '''
+    Sets the user's credentials in ~/.runpod/credentials.toml
+
+    Args:
+        api_key (str): The user's API key.
+
+
+    --- File Structure ---
+
+    [default]
+    api_key = "RUNPOD_API_KEY"
+    '''
+    with open(CREDENTIAL_FILE, 'w', encoding="UTF-8") as cred_file:
+        cred_file.write('[default]\n')
+        cred_file.write('api_key = "' + api_key + '"\n')
+
+
+def check_credentials():
+    '''
+    Checks if the credentials file exists and is valid.
+    '''
+    if not os.path.exists(CREDENTIAL_FILE):
+        return False, 'Error: ~/.runpod/credentials.toml does not exist.'
+
+    # Check for default api_key
+    try:
+        config = toml.load(CREDENTIAL_FILE)
+
+        if 'default' not in config:
+            return False, 'Error: ~/.runpod/credentials.toml is missing default section.'
+
+        if 'api_key' not in config['default']:
+            return False, 'Error: ~/.runpod/credentials.toml is missing api_key.'
+
+    except (TypeError, ValueError):
+        return False, 'Error: ~/.runpod/credentials.toml is not a valid TOML file.'
+
+    return True, None
+
+
+def get_credentials(profile='default'):
+    '''
+    Returns the credentials for the specified profile from ~/.runpod/credentials.toml
+    '''
+    with open(CREDENTIAL_FILE, 'r', encoding="UTF-8") as cred_file:
+        credentials = toml.load(cred_file)
+
+    if profile not in credentials:
+        return None
+
+    return credentials[profile]

setup.cfg

@@ -33,6 +33,7 @@ install_requires =
     py-cpuinfo >= 9.0.0
     python-dotenv >= 1.0.0
     requests >= 2.31.0
+    tomli >= 2.0.1
     tqdm-loggable >= 0.1.4
     fastapi[all] >= 0.99.0
 

setup.py

@@ -9,5 +9,11 @@
     setup(
         name='runpod',
         use_scm_version=True,
-        setup_requires=['setuptools_scm']
+        setup_requires=['setuptools_scm'],
+
+        entry_points={
+            'console_scripts': [
+                'runpod = runpod.cli:main'
+            ]
+        }
     )