API Endpoints Wrapper Functions

cancel_transfer(client, job_id)

Cancel a transfer job with a job_id

Parameters:

Name	Type	Description	Default
client	EOSCClient	The API client.	required
job_id	str	Transfer job ID.	required

Returns:

Name	Type	Description
TransferStatus	TransferStatus	The canceled transfer with its current status (canceled or any other final status).

Source code in eosc_data_transfer_client/endpoints.py

def cancel_transfer(client: EOSCClient, job_id: str) -> TransferStatus:
    """
    Cancel a transfer job with a job_id

    Args:
        client: The API client.
        job_id: Transfer job ID.

    Returns:
        TransferStatus: The canceled transfer with its current status (canceled or any other final status).
    """
    response = client.request("DELETE", f"/transfer/{job_id}")
    return TransferStatus(**response)

create_transfer(client, transfer)

Initiate a new data transfer.

This function sends a POST request to the EOSC Data Transfer API to create a new transfer job.

Parameters:

Name	Type	Description	Default
client	EOSCClient	An instance of EOSCClient configured with base URL and authentication.	required
transfer	TransferRequest	A TransferRequest object describing the files to transfer and transfer parameters.	required

Returns:

Name	Type	Description
TransferResponse	TransferResponse	An object containing details about the submitted transfer, including job ID and status.

Raises:

Type	Description
EOSCClientError	If the API returns a 4xx error (e.g., invalid input).
EOSCServerError	If the API returns a 5xx error (e.g., internal server error).

Source code in eosc_data_transfer_client/endpoints.py

def create_transfer(client: EOSCClient, transfer: TransferRequest) -> TransferResponse:
    """
    Initiate a new data transfer.

    This function sends a `POST` request to the EOSC Data Transfer API to create a new transfer job.

    Arguments:
        client: An instance of `EOSCClient` configured with base URL and authentication.
        transfer: A `TransferRequest` object describing the files to transfer and transfer parameters.

    Returns:
        TransferResponse: An object containing details about the submitted transfer, including job ID and status.

    Raises:
        EOSCClientError: If the API returns a 4xx error (e.g., invalid input).
        EOSCServerError: If the API returns a 5xx error (e.g., internal server error).
    """
    response = client.request("POST", "/transfers", json=transfer.model_dump())
    return TransferResponse(**response)

get_transfer_field(client, job_id, field_name)

Retrieve a specific field from a transfer job, using TransferStatus model for type resolution.

Parameters:

Name	Type	Description	Default
client	EOSCClient	The API client.	required
job_id	str	Transfer job ID.	required
field_name	str	Field to retrieve.	required

Returns:

Type	Description
Union[str, int, bool, dict, datetime]	The value of the requested field, properly typed.

Raises:

Type	Description
ValueError	If the field name is invalid or type conversion fails.

Source code in eosc_data_transfer_client/endpoints.py

def get_transfer_field(client: EOSCClient, job_id: str, field_name: str) -> Union[str, int, bool, dict, datetime]:
    """
    Retrieve a specific field from a transfer job, using TransferStatus model for type resolution.

    Args:
        client: The API client.
        job_id: Transfer job ID.
        field_name: Field to retrieve.

    Returns:
        The value of the requested field, properly typed.

    Raises:
        ValueError: If the field name is invalid or type conversion fails.
    """
    model_fields = TransferStatus.model_fields
    if field_name not in model_fields:
        raise ValueError(f"Unsupported field name: '{field_name}'. Must be one of: {list(model_fields.keys())}")

    expected_type = model_fields[field_name].annotation
    raw_response = client.request("GET", f"/transfer/{job_id}/{field_name}")

    # Extract from "entity"
    value = raw_response.get("entity", None)
    if value is None:
        raise ValueError(f"No 'entity' found in response for field '{field_name}'")

    # Parse value based on expected type
    try:
        if expected_type is int:
            return int(value)
        elif expected_type is float:
            return float(value)
        elif expected_type is datetime:
            return datetime.fromisoformat(value)
        elif expected_type is bool:
            return str(value).lower() in {"true", "1", "yes"}
        elif expected_type is dict:
            return value if isinstance(value, dict) else {}
        else:
            return str(value)
    except Exception as e:
        raise ValueError(f"Failed to convert value for field '{field_name}' to {expected_type}: {e}")

get_transfer_status(client, transfer_id)

Retrieve the status of a transfer job.

This function sends a GET request to the API to fetch full details about a specific transfer job using its job ID.

Parameters:

Name	Type	Description	Default
client	EOSCClient	An instance of EOSCClient for making authenticated requests.	required
transfer_id	str	The ID of the transfer job to retrieve.	required

Returns:

Name	Type	Description
TransferStatus	TransferStatus	An object with detailed information about the job, including state, timestamps, and metadata.

Raises:

Type	Description
EOSCClientError	If the job ID is invalid or not found.
EOSCServerError	If the API encounters an internal issue.

Source code in eosc_data_transfer_client/endpoints.py

def get_transfer_status(client: EOSCClient, transfer_id: str) -> TransferStatus:
    """
    Retrieve the status of a transfer job.

    This function sends a `GET` request to the API to fetch full details about a specific transfer job
    using its job ID.

    Arguments:
        client: An instance of `EOSCClient` for making authenticated requests.
        transfer_id: The ID of the transfer job to retrieve.

    Returns:
        TransferStatus: An object with detailed information about the job, including state, timestamps, and metadata.

    Raises:
        EOSCClientError: If the job ID is invalid or not found.
        EOSCServerError: If the API encounters an internal issue.
    """
    response = client.request("GET", f"/transfer/{transfer_id}")
    return TransferStatus(**response)

get_user_info(client)

Retrieve user information from the EOSC Data Transfer service.

Returns:

Name	Type	Description
UserInfo	UserInfo	Metadata about the current user, including identity, VO membership, and permissions.

Source code in eosc_data_transfer_client/endpoints.py

def get_user_info(client: EOSCClient) -> UserInfo:
    """
    Retrieve user information from the EOSC Data Transfer service.

    Returns:
        UserInfo: Metadata about the current user, including identity, VO membership, and permissions.
    """
    response = client.request("GET", "/user/info")
    return UserInfo(**response)

list_transfers(client, **filters)

Find transfers matching search criteria.

Parameters:

Name	Type	Description	Default
client	EOSCClient	The API client.	required
**filters	Optional[Any]	Optional query parameters to filter the search.	{}

Returns:

Name	Type	Description
TransferStatusList	TransferStatusList	A list of transfers matching the criteria.

Source code in eosc_data_transfer_client/endpoints.py

def list_transfers(client: EOSCClient, **filters: Optional[Any]) -> TransferStatusList:
    """
    Find transfers matching search criteria.

    Args:
        client: The API client.
        **filters: Optional query parameters to filter the search.

    Returns:
        TransferStatusList: A list of transfers matching the criteria.
    """
    # Filter out None values
    query_params = {k: v for k, v in filters.items() if v is not None}
    response = client.request("GET", "/transfers", params=query_params)
    return TransferStatusList(**response)

parse_doi(client, doi)

Parse a PID (e.g., DOI) and retrieve associated file metadata.

Parameters:

Name	Type	Description	Default
pid	str	The persistent identifier to parse.	required

Returns:

Name	Type	Description
StorageContent	StorageContent	Parsed metadata including a list of files

Raises:

Type	Description
EOSCClientError	For 4xx errors.
EOSCServerError	For 5xx errors.
EOSCRequestError	For network issues.

Source code in eosc_data_transfer_client/endpoints.py

def parse_doi(client: EOSCClient, doi: str) -> StorageContent:
    """
    Parse a PID (e.g., DOI) and retrieve associated file metadata.

    Args:
        pid (str): The persistent identifier to parse.

    Returns:
        StorageContent: Parsed metadata including a list of files

    Raises:
        EOSCClientError: For 4xx errors.
        EOSCServerError: For 5xx errors.
        EOSCRequestError: For network issues.
    """
    response = client.request("GET", "/parser", params={"doi": doi})
    return StorageContent(**response)