strangeworks package¶

Subpackages¶

strangeworks.core package

Submodules¶

strangeworks.sw_client module¶

client.py.

class strangeworks.sw_client.SWClient(cfg: ConfigSource, headers: Dict[str, str] | None = None, rest_client: StrangeworksRestClient | None = None, **kwargs)¶

Bases: object

Strangeworks client object.

add_tags(job_slug: str, tags: List[str]) → List[str]¶

Add tags to a job.

Parameters:

job_slug (str) – The slug of the job.
tags (List[str]) – The tags to add to the job.

Returns:

The tags linked to the job.

Return type:

List[str]

authenticate(api_key: str | None = None, url: str | None = None, profile: str | None = None, store_credentials: bool = True, overwrite: bool = False, **kwargs) → None¶

Authenticate with Strangeworks.

Obtains an authorization token from the platform using the api_key. The auth token is used to make calls to the platform. Access to platform interfaces are initialized.

Parameters:

api_key (Optional[str]) – The API key.
url (Optional[str]) – The base URL to the Strangeworks API.
profile (Optional[str]) – The profile name to use for configuration.
store_credentials (bool) – Indicates whether credentials (api key an url) should be saved. Defaults to True.
overwrite (bool) – Indicates whether to overwrite credentials if they already exist. Defaults to False.
**kwargs – Additional arguments.

download_job_files(file_paths: str | list, resource_slugs: List[str] | None = None, product_slugs: List[str] | None = None, statuses: List[str] | None = None) → List[File]¶

download_job_files(file_paths: str, resource_slugs: List[str] | None = None, product_slugs: List[str] | None = None, statuses: List[str] | None = None) → List[File]

download_job_files(file_paths: list, resource_slugs: List[str] | None = None, product_slugs: List[str] | None = None, statuses: List[str] | None = None) → List[File]

Download files associated with a job.

Parameters:: file_paths (Union[str, list]) – either the job slug (str) or a list of URLs associated with a Job object.
Return type:: A List of File objects.

execute(res: Resource, payload: Dict[str, Any] | None = None, endpoint: str | None = None)¶

Execute a job request.

Parameters:

res (Resource) – the resource that has the function to call.
payload (Optiona;[Dict[str, Any]]) – the payload to send with the request.
endpoint – additional endpoint to append to the proxy path for the resource.

execute_get(product_slug: str, endpoint: str | None = None)¶

Execute GET.

Parameters:

product_slug (str) – string used to identify a product entry on the platform.
endpoint (str | None = None) – additional path that denotes a service/product endpoint.

Returns:

Result of the request, typically a JSON serializable object like a
dictionary.

execute_post(product_slug: str, payload: Dict[str, Any] | None = None, json: dict | None = None, data: any | None = None, endpoint: str | None = None)¶

Execute a job request.

Parameters:

product_slug (str) – string used to identify a product entry on the platform.
payload – same as json
json – A JSON serializable Python object to send in the body of the Request.
data – Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request. Typically a string.
endpoint (str | None = None) – additional path that denotes a service/product endpoint.

Return type:

Result of the request, typically a dictionary.

experiment(cfg: ExperimentConfiguration = ExperimentConfiguration(experiment_name=None, trial_name=None, requirements_path=None, local_run=False))¶

Generate Callable for running an experiment.

Parameters:: cfg (ExperimentConfiguration) – The configuration for the experiment.
Returns:: The decorated function.
Return type:: Callable[…, Any]

Examples

>>> @sw.experiment()
... def my_experiment():
...     return 42
... my_experiment()

experiment_download(experiment_name: str, trials: int | list[str], files: str | list[str], jobs: bool | list[str]) → Experiment¶

Download an Experiment.

This gives you the flexiblity to download any number of trials. Particular files or jobs can be downloaded for each trial.

Parameters:

experiment_name (str) – The name of the experiment.
trials (Union[int, list[str]]) – The trials to download. If an int is provided, then the last n trials will be downloaded. If a list of str is provided, then the named trials will be downloaded. The list of str are expected to be trial_name values.
files (Union[str, list[str]]) – The files to download. The str or list of str are expected to be file_name values. If a str is provided, then the file will be downloaded. If a list of str is provided, then the files will be downloaded.
jobs (Union[bool, list[str]]) –
The jobs to download. If a bool is provided,

then the all jobs related with the trial will be downloaded.

If a list of str is provided, then the jobs will be downloaded.

Returns:

The experiment.

Return type:

Experiment

Examples

>>> # Download the last 3 trials of the 'heavy_computation' experiment.
>>> # Download the 'user_program_stdout.txt' file for each trial.
>>> # Do not include any related jobs.
>>> import strangeworks as sw
>>> sw.authenticate(...) # update with your api key.
>>> sw.experiment_download(
...     "heavy_computation", 3, "user_program_stdout.txt", False
... )
Experiment(
    name='heavy_computation',
    trials=[
        Trial(
            name='siete_ocho_207',
            files=[
                File(
                    id=None,
                    slug='evtstr5wp',
                    label=None,
                    file_name='user_program_stdout.txt',
                    url='https://api.strangeworks.com/files/experiments/lucky-badger-8981-krjdisf9d/trial/snarling-roe-0728-t0k8btudx/evtstr5wp',
                    content='The answer is 42.',
                )
            ],
            jobs=None,
        ),
        Trial(
            name='siete_ocho_206',
            files=[
                File(
                    id=None,
                    slug='9kemsahmh',
                    label=None,
                    file_name='user_program_stdout.txt',
                    url='https://api.strangeworks.com/files/experiments/lucky-badger-8981-krjdisf9d/trial/glistening-river-1629-5pjcb0r9j/9kemsahmh',
                    content='sent request to strangeworks optimization.',
                    )
            ],
            jobs=None,
        ),
        Trial(
            name='siete_ocho_205',
            files=[
                File(
                    id=None,
                    slug='rbm85i4wy',
                    label=None,
                    file_name='user_program_stdout.txt',
                    url='https://api.strangeworks.com/files/experiments/lucky-badger-8981-krjdisf9d/trial/winding-water-8578-giugxm4gd/rbm85i4wy',
                    content='',
                )
            ],
            jobs=None,
        )])

>>> # Download a list of named trials of the 'heavy_computation' experiment.
>>> # Download the 'result.pickle' and 'user_program_stdout.txt'
>>> #   files for each trial.
>>> # If the trial has the files you requested
>>> #   then they will be included in the Trial object.
>>> # Include any related jobs.
>>> # If no jobs are related to any of the trials,
>>> #   then the jobs attribute will be None.
>>> import strangeworks as sw
>>> sw.authenticate(...) # update with your api key.
>>> sw.experiment_download(
...     "heavy_computation",
...     ["siete_ocho", "siete_ocho_9"],
...     ["result.pickle", "user_program_stdout.txt"],
...     True,
... )
Experiment(
    name='heavy_computation',
    trials=[
        Trial(
            name='siete_ocho_9',
            files=[
                File(
                    id=None,
                    slug='hseuqyjd7',
                    label=None,
                    file_name='result.pickle',
                    url='https://api.strangeworks.com/files/experiments/lucky-badger-8981-krjdisf9d/trial/bold-whale-5839-5yhcpjuhz/hseuqyjd7',
                    content='gASVBAAAAAAAAABNagQu'
                ),
                File(
                    id=None,
                    slug='ey5szvabe',
                    label=None,
                    file_name='user_program_stdout.txt',
                    url='https://api.strangeworks.com/files/experiments/lucky-badger-8981-krjdisf9d/trial/bold-whale-5839-5yhcpjuhz/ey5szvabe',
                    content=''),
            ],
            jobs=[
                Job(
                    slug='straight-mountain-3370',
                    child_jobs=[],
                    external_identifier='',
                    resource=None,
                    status='COMPLETED',
                    is_terminal_state=None,
                    remote_status=None,
                    job_data_schema=None,
                    job_data=None,
                    files=[
                        File(
                            id=None,
                            slug='7ab5s545s',
                            label=None,
                            file_name='result.json',
                            url='https://api.strangeworks.com/files/jobs/straight-mountain-3370/7ab5s545s/result.json',
                            content=None,
                        )
                    ],
                )
            ]),
        Trial(name='siete_ocho', files=[], jobs=None)
    ],
)

experiment_get_result(name: str, trial: str | None = None) → Any¶

Get Experiment Result.

Allows you to download the result of an experiment.

Assumes that your current environment has the same modules loaded / installed as the environment which you submitted the experiment.

Parameters:

name (str) – The name of the experiment.
trial (Optional[str]) – The name of the trial. Defaults to the last trial in the experiment.

Returns:

The result of the experiment. This is the value that you returned from your experiment function.

Return type:

Any

Examples

>>> import strangeworks as sw
>>> sw.authenticate(...)
>>> sw.experiment_get_result("heavy_computation", "siete_ocho_9")
42
>>> sw.experiment_get_result("heavy_computation")
42

Raises:

StrangeworksError – If we are unable to download the result.
StrangeworksError – If we are unable to get one trial from the experiment.
StrangeworksError – If the trial is not in a COMPLETED state.
StrangeworksError – If we are unable to get the one result file from the trial.

experiment_upload(experiment_name: str, trial_name: str, file_path: str) → File¶

experiment_upload allows you to upload a file to a trial.

Parameters:

experiment_name (str) – The name of the experiment.
trial_name (str) – The name of the trial.
file_path (str) – The path to the file to upload.

Returns:

The file that was uploaded.

Return type:

File

Examples

>>> import strangeworks as sw
>>> sw.authenticate(...)
>>> sw.experiment_upload(
...     "heavy_computation",
...     "siete_ocho_9",
...     "./post_processed_result.json",
... )

get_backend(backend_slug: str) → Backend¶

Return a single backend by the slug.

Replaces the deprecated BackendsService.

get_backends(product_slugs: List[str] | None = None, backend_type_slugs: List[str] | None = None, backend_statuses: List[str] | None = None, backend_tags: List[str] | None = None) → List[Backend]¶

Return a list of backends available based on the filters provided.

Replaces the deprecated BackendsService.

get_error_messages(job_slug: str) → Dict[str, List[File]]¶

get_resource_for_product(product_slug: str) → Resource¶

Get resource to use when using product.

If the user has a resource allready configured and that resource still exists, that resource will be returned. If the user-configured resource no longer exists, an error will be raised.

If user does not have a resource identified for the product and there is only a single resouce for the product available in the users workspace, that resource will be returned.

If there are multiple resources for the given product slug and the user hasn’t already selected one, they will be asked to do so.

If there are no resources configured for the product slug, an error will be raised asking the user to create one.

Parameters:: product_slug (str) – product identifier.
Returns:: a resource object which maps to the product.
Return type:: Resource
Raises:: :StrangeworksError – if no resource is found or there are multiple resource and none selected.

get_sdk_api() → SDKAPI¶: Return SDK API instance.

Retrieve list of jobs associated with the current workspace account.

Parameters:

slug (Optional[str] = None) – Identifier for a specific job. Defaults to None.
resource_slugs (Optional[List[str]]) – List of resource identifiers. Only jobs whose resources match will be returned. Defaults to None.
product_slugs (Optional[List[str]]) – List of product identifiers. Only jobs whose product slugs match will be returned. Defaults to None.
statuses (Optional[List[str]]) – List of job statuses. Only obs whose statuses match will be returned. Defaults to None.
tags (Optional[List[str]]) – List of tags to filter the jobs by. Defaults to None.
tag_operator (Optional[TagOperator]) – The logical operator to use for the tags. Can be either “AND” or “OR”. Defaults to None, treating the tags list as an OR operation if multiple tags are provided.

Returns:

List of jobs or None if there are no jobs that match selection criteria.

Return type:

Optional[List[Job]]

resources(slug: str | None = None) → List[Resource] | None¶

Retrieve list of resources that are available for this workspace account.

Parameters:: slug (Optional[str]) – Identifier for a specific resource. Defaults to None.
Returns:: List of resources for the current workspace account or None if no resources have been created.
Return type:: Optional[List[Resource]]

run(func: Callable[[...], Any], input: ExperimentInput | list[ExperimentInput], cfg: ExperimentConfiguration = ExperimentConfiguration(experiment_name=None, trial_name=None, requirements_path=None, local_run=False), **kwargs) → dict[str, TrialSubmission]¶

Run an experiment.

Parameters:

func (Callable[..., Any]) – The function to run.
input (Union[ExperimentInput, list[ExperimentInput]]) – The input to the function.
cfg (ExperimentConfiguration) – The configuration for the experiment.

Returns:

The results of the experiment.

Return type:

dict[str, TrialSubmission]

set_resource_for_product(resource_slug: str, product_slug: str) → None¶

Set which resource to use for a given product.

Users can have multiple resources set up for the same product. When this is the case, they can set which resource to use with this call.

Parameters:

resource (str) – Resource identifier (currently the slug).
product_slug –

str
product identifier.

upload_file(file_path: str) → File¶

Upload a file to strangeworks.

File.url is how you can download the file.

raises StrangeworksError if any issues arise while attempting to upload the file.

workspace_info() → Workspace¶: Retrieve information about the current workspace.

class strangeworks.sw_client.TagOperator(value)¶

Bases: Enum

Logical operators for tags.

AND = 'AND'¶

OR = 'OR'¶

strangeworks.utils module¶

utils.py.

strangeworks.utils.is_empty_str(s: str) → bool¶

Check if string is empty.

A string is considered to be empty if any one of the following conditions are true:

it is set to None or

consists exclusively of spaces

is equal to “”

Module contents¶

Strangeworks SDK.