Learning Outcomes
- Install and configure the Via Foundry Python SDK
- Authenticate with the Via Foundry platform
- Use the main client to interact with API endpoints
- Manage projects, pipelines, and runs programmatically
- Handle authentication tokens and configuration
Via Foundry Python SDK
SDK Version
This documentation covers Via Foundry Python SDK v1.0.19
The Via Foundry Python SDK provides a comprehensive, Pythonic interface for interacting with the Via Foundry platform programmatically. This SDK enables you to authenticate, manage projects, run pipelines, access reports, and perform all major operations available through the Via Foundry API.
Key Features
- Robust Authentication - Token-based auth with automatic refresh
- Simple Client Interface - Intuitive methods for all API operations
- Project Management - Create, update, and manage projects and pipelines
- Run Management - Execute and monitor pipeline runs
- Report Access - Retrieve and process run reports and results
- Configuration Management - Handle platform and user configurations
Installation
Install the SDK using pip: pip install viafoundry-sdk
Development Installation
For development or to get the latest features, install directly from the source repository.
Checking Your Version
You can check which version of the SDK you have installed:
import viafoundry as vf
print(vf.__version__)
Or from the command line:
python -c "import viafoundry as vf; print(vf.__version__)"
Authentication
The SDK provides a comprehensive authentication system that handles token management, automatic refresh, and multiple authentication methods. All authentication methods and examples are documented in the class methods below.
Initialize the Auth class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config_path
|
str
|
Path to the configuration file. Defaults to None. |
None
|
load_config() -> Dict
Load configuration from the config file.
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
The loaded configuration. |
save_config() -> None
Save hostname and bearer token to the config file.
configure(hostname: str, username: Optional[str] = None, password: Optional[str] = None, token: Optional[str] = None, identity_type: int = 1, redirect_uri: str = 'https://viafoundry.com/user') -> None
Prompt user for credentials if necessary and authenticate.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hostname
|
str
|
The hostname for authentication. |
required |
username
|
str
|
The username for authentication. Defaults to None. |
None
|
password
|
str
|
The password for authentication. Defaults to None. |
None
|
token
|
str
|
Pre-generated personal access token. Defaults to None. |
None
|
identity_type
|
int
|
The identity type. Defaults to 1. |
1
|
redirect_uri
|
str
|
The redirect URI. Defaults to "https://viafoundry.com/user". |
'https://viafoundry.com/user'
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If hostname or token is empty. |
configure_token(hostname: str, token: str) -> None
Configure authentication using a pre-generated personal access token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hostname
|
str
|
The hostname for authentication. |
required |
token
|
str
|
Pre-generated personal access token. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If hostname or token is empty. |
login(username: str, password: str, identity_type: int = 1, redirect_uri: str = 'https://viafoundry.com/user') -> str
Authenticate and get the token from the Set-Cookie header.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
username
|
str
|
The username for authentication. |
required |
password
|
str
|
The password for authentication. |
required |
identity_type
|
int
|
The identity type. Defaults to 1. |
1
|
redirect_uri
|
str
|
The redirect URI. Defaults to "https://viafoundry.com/user". |
'https://viafoundry.com/user'
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The authentication token. |
calculate_expiration_date() -> str
Calculate an expiration date one month from now.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The expiration date in YYYY-MM-DD format. |
get_bearer_token(cookie_token: str, name: str = 'token') -> str
Request a bearer token using the existing cookie token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cookie_token
|
str
|
The cookie token for authentication. |
required |
name
|
str
|
The name of the token. Defaults to "token". |
'token'
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The bearer token. |
get_headers() -> Dict
Return headers with the bearer token.
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Headers containing the bearer token. |
Main Client
The ViaFoundryClient is the primary interface for interacting with the Via Foundry API. It provides organized access to all platform functionalities. All available methods, parameters, and usage patterns are documented in the class reference below.
A client for interacting with the ViaFoundry API.
Attributes:
| Name | Type | Description |
|---|---|---|
auth |
Auth
|
The authentication handler. |
reports |
Reports
|
The reports handler. |
process |
Process
|
The process handler. |
metadata |
Metadata
|
The metadata handler. # ← Add this line |
endpoints_cache |
Optional[Dict]
|
Cache for discovered endpoints. |
Initializes the ViaFoundryClient.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config_path
|
Optional[str]
|
Path to the configuration file. Defaults to None. |
None
|
enable_session_history
|
bool
|
Whether to enable session history for reports. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If initialization fails. |
configure_auth(hostname: str, username: str = None, password: str = None, token: str = None, identity_type: int = 1, redirect_uri: str = 'http://localhost/user') -> None
Configures authentication by setting up the token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hostname
|
str
|
The hostname for authentication. |
required |
username
|
str
|
The username for authentication. |
None
|
password
|
str
|
The password for authentication. |
None
|
token
|
str
|
Pre-generated personal access token. |
None
|
identity_type
|
int
|
The identity type. Defaults to 1. |
1
|
redirect_uri
|
str
|
The redirect URI. Defaults to "http://localhost/user". |
'http://localhost/user'
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If authentication configuration fails. |
Examples:
Using username and password: client.configure_auth(hostname="https://api.example.com", username="user", password="pass")
Using personal access token: client.configure_auth(hostname="https://api.example.com", token="your_pat_token")
configure_auth_token(hostname: str, token: str) -> None
Configures authentication using a pre-generated personal access token. This is a convenience method for token-only authentication.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hostname
|
str
|
The hostname for authentication. |
required |
token
|
str
|
Pre-generated personal access token. |
required |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If authentication configuration fails. |
Examples:
client.configure_auth_token(hostname="https://api.example.com", token="your_pat_token")
discover(search: Optional[str] = None, as_json: bool = False) -> Union[Dict, str]
Fetches all available endpoints from Swagger.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
search
|
Optional[str]
|
Filter endpoints containing a search string or in |
None
|
as_json
|
bool
|
Whether to return the output as a JSON-formatted string. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
Union[Dict, str]
|
Union[Dict, str]: A dictionary or JSON-formatted string of endpoints. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If endpoint discovery fails. |
call(method: str, endpoint: str, params: Optional[Dict] = None, data: Optional[Dict] = None, files: Optional[Dict] = None) -> Union[Dict, str]
Sends a request to a specific endpoint.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
The HTTP method to use for the request. |
required |
endpoint
|
str
|
The endpoint to call. |
required |
params
|
Optional[Dict]
|
Query parameters for the request. Defaults to None. |
None
|
data
|
Optional[Dict]
|
Data to send in the request body. Defaults to None. |
None
|
files
|
Optional[Dict]
|
Files to upload. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
Union[Dict, str]
|
Union[Dict, str]: The response data as a dictionary or raw text. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the request fails. |
API Reference
The complete API reference is automatically generated from the source code docstrings. All available methods, parameters, return values, and usage examples are documented directly in the class references above.
Module Structure
The SDK organizes functionality through the main client interface. All API operations are accessible through the ViaFoundryClient class methods and properties.
Configuration
The SDK configuration options and methods are documented in the package. Refer to the authentication and client documentation above for all available configuration parameters and environment variables.
Best Practices
Authentication Security
Always use environment variables or secure configuration files for credentials. The authentication class provides secure methods for handling tokens and credentials.
Troubleshooting
Common issues and their solutions are documented within each method's docstrings. For additional help:
- Documentation: Comprehensive method documentation is available in each class reference above
- GitHub Issues: Report bugs or request features
- Support: Contact Via Foundry support through the platform