Python API

Examples

Upload

from filesender import UserAuth, FileSenderClient
from asyncio import run

async def main():
    user_client = FileSenderClient(
        base_url="https://filesender.aarnet.edu.au",
        auth=UserAuth(
            api_key="kzh1mk1bik1bavgjrggwd6w8u71vyrg5cagevfkt5zv21njodl6hzaiscrok36dtz",
            username="me@institute.edu.au"
        )
    )
    await user_client.prepare()
    transfer = await user_client.upload_workflow(
        files=["my_data.r1.fastq", "my_data.r2.fastq"],
        transfer_args={
            "recipients": ["them@organisation.edu.au"],
            "from": "me@institute.edu.au"
        }
    )

if __name__ == "__main__":
    run(main())

Download

from filesender import UserAuth, FileSenderClient
from asyncio import run
from pathlib import Path

async def main():
    download_client = FileSenderClient(
        base_url="https://filesender.aarnet.edu.au
    )

    await download_client.download_files(
        token="hxvmxx9n-2e5u-br7d-4sf5-ypa3-tq55qw43",
        out_dir=Path("~/Downloads")
    )

if __name__ == "__main__":
    run(main())

filesender.FileSenderClient

FileSenderClient(
    base_url: str,
    chunk_size: Optional[int] = None,
    auth: Auth = Auth(),
    concurrent_files: Optional[int] = 1,
    concurrent_chunks: Optional[int] = 2,
)

A client that can be used to programmatically interact with FileSender.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	The base URL for the FileSender instance you want to interact with. This should just be a host name such as `https://filesender.aarnet.edu.au`, and should not include `/rest.php` or any other path element.	required
`chunk_size`	`Optional[int]`	The chunk size (in bytes) used for uploading, which is the amount of data that is sent to the server per request. By default this is the maximum chunk size allowed by the server, but you might want to adjust this to reduce memory usage or because you are getting timeout errors.	`None`
`auth`	`Auth`	The authentication method. This is optional, but you almost always want to provide it. Generally you will want to use `UserAuth` or `GuestAuth`.	`Auth()`
`concurrent_files`	`Optional[int]`	The number of files that will be uploaded concurrently. This works multiplicatively with `concurrent_chunks`, so `concurrent_files=2, concurrent_chunks=2` means 4 total chunks of data will be stored in memory and sent concurrently.	`1`
`concurrent_chunks`	`Optional[int]`	The number of chunks that will be read from each file concurrently. Increase this number to speed up transfers, or reduce this number to reduce memory usage and network errors. This can be set to `None` to enable unlimited concurrency, but use at your own risk.	`2`

prepare `async`

prepare() -> None

Checks that the chunk size is appropriate and/or sets the chunk size based on the server info. This should always be run before using the client.

create_guest `async`

create_guest(body: Guest) -> Guest

Sends a voucher to a guest to invite them to send files

Parameters:

Name	Type	Description	Default
`body`	`Guest`	see `Guest`	required

Returns:

Type	Description
`Guest`	See `Guest`

upload_workflow `async`

upload_workflow(
    files: List[Path], transfer_args: PartialTransfer = {}
) -> Transfer

High level function for uploading one or more files

Parameters:

Name	Type	Description	Default
`files`	`List[Path]`	A list of files and/or directories to upload.	required
`transfer_args`	`PartialTransfer`	Additional options to include when creating the transfer, for example a subject or message. See `PartialTransfer`.	`{}`

download_files `async`

download_files(token: str, out_dir: Path) -> None

Downloads all files for a transfer.

Parameters:

Name	Type	Description	Default
`token`	`str`	Obtained from the transfer email. The same as `GuestAuth`'s `guest_token`.	required
`out_dir`	`Path`	The path to write the downloaded files.	required

get_server_info `async`

get_server_info() -> ServerInfo

Returns all information known about the current FileSender server.

Returns:

Type	Description
`ServerInfo`	See `ServerInfo`.

create_transfer `async`

create_transfer(body: Transfer) -> Transfer

Tells FileSender that you intend to start building a new transfer. Generally you should use upload_workflow instead of this, which is much more user friendly.

Parameters:

Name	Type	Description	Default
`body`	`Transfer`	See `Transfer`.	required

Returns:

Type	Description
`Transfer`	See `Transfer` (this is a different type from the input parameter).

update_transfer `async`

update_transfer(
    transfer_id: int, body: TransferUpdate
) -> Transfer

Updates an existing transfer, e.g. to indicate that it has finished. Generally you should use upload_workflow instead of this, which is much more user friendly.

Parameters:

Name	Type	Description	Default
`transfer_id`	`int`	Identifier obtained from the result of `create_transfer`	required
`body`	`TransferUpdate`	See `TransferUpdate`	required

Returns:

Type	Description
`Transfer`	See `Transfer`

update_file `async`

update_file(file_info: File, body: FileUpdate) -> None

Updates metadata for an existing file, e.g. to indicate that it has finished. Generally you should use upload_workflow instead of this, which is much more user friendly.

Parameters:

Name	Type	Description	Default
`file_info`	`File`	Identifier obtained from the result of `create_transfer`	required
`body`	`FileUpdate`	See `FileUpdate`	required

upload_file `async`

upload_file(file_info: File, path: Path) -> None

Uploads a file, with multiple chunks being uploaded in parallel Generally you should use upload_workflow instead of this, which is much more user friendly.

Parameters:

Name	Type	Description	Default
`file_info`	`File`	Identifier obtained from the result of `create_transfer`	required
`path`	`Path`	File path to the file to be uploaded	required

download_file `async`

download_file(
    token: str,
    file_id: int,
    out_dir: Path,
    file_size: Union[int, float, None] = None,
    file_name: Optional[str] = None,
) -> None

Downloads a single file.

Parameters:

Name	Type	Description	Default
`token`	`str`	Obtained from the transfer email. The same as `GuestAuth`'s `guest_token`.	required
`file_id`	`int`	A single file ID indicating the file to be downloaded.	required
`out_dir`	`Path`	The path to write the downloaded file.	required
`file_size`	`Union[int, float, None]`	The file size in bytes, optionally.	`None`
`file_name`	`Optional[str]`	The file name of the file being downloaded. This will impact the name by which it's saved.	`None`

upload_complete `async`

upload_complete(file_info: File, path: Path) -> None

Uploads a file and marks the upload as complete. Generally you should use upload_workflow instead of this, which is much more user friendly.

filesender.UserAuth `dataclass`

UserAuth(username: str, api_key: str, delay: int = 0)

Bases: Auth

Used to authenticate the FileSenderClient with all permissions of a full user.

Attributes:

Name	Type	Description
`username`	`str`	The username (generally the email address) of the user performing FileSender operations
`api_key`	`str`	The API key that corresponds to the username. You can generally obtain this at the https://some.filesender.domain/?s=user URL.
`delay`	`int`	The number of seconds to delay the timestamp. See https://docs.filesender.org/filesender/v2.0/rest/#signed-request

filesender.GuestAuth `dataclass`

GuestAuth(
    guest_token: str,
    security_token: Optional[str] = None,
    csrf_token: Optional[str] = None,
)

Bases: Auth

Used to authenticate the FileSenderClient with a guest token

Attributes:

Name	Type	Description
`guest_token`	`str`	The string after `vid=` in the voucher link

Python API

Examples

Upload

Download

filesender.FileSenderClient

prepare async

create_guest async

upload_workflow async

download_files async

get_server_info async

create_transfer async

update_transfer async

update_file async

upload_file async

download_file async

upload_complete async

filesender.UserAuth dataclass

filesender.GuestAuth dataclass

prepare `async`

create_guest `async`

upload_workflow `async`

download_files `async`

get_server_info `async`

create_transfer `async`

update_transfer `async`

update_file `async`

upload_file `async`

download_file `async`

upload_complete `async`

filesender.UserAuth `dataclass`

filesender.GuestAuth `dataclass`