1'''
 2# File management
 3
 4Various examples displaying how to interact with files.
 5
 6##Upload a file
 7
 8Upload a file with some tags to the ENPICOM Platform.
 9```python
10from enpi_api.l2.client.enpi_api_client import EnpiApiClient
11from enpi_api.l2.tags import FileTags  # The `FileTags` import contains all system level file tags available in the ENPICOM Platform
12from enpi_api.l2.types.file import OnCollisionAction
13from enpi_api.l2.types.tag import Tag
14
15with EnpiApiClient() as enpi_client:
16    # Following script will upload the file located under provided path into ENPICOM Platform
17    file = (
18        enpi_client.file_api.upload_file(
19            file_path="path/to/file",
20            # Specify the tags that the file will have
21            tags=[Tag(id=FileTags.CampaignId, value="My campaign ID")],
22            # Specify what to do if a file with the same name already exists, in this case, we overwrite the file
23            on_collision=OnCollisionAction.OVERWRITE,
24        ).wait()
25    )  # If you want to use the file further on in the script, you must await the execution at some point to be sure that the file was uploaded and processed
26
27```
28##Upload multiple files in parallel
29
30This example shows how to upload multiple files at once in
31parallel using the `enpi_api.l2.util.execution.wait_all_parallel` function. This function could also be used for any other type of executions returned.
32
33```python
34import glob
35
36from enpi_api.l2.client.enpi_api_client import EnpiApiClient
37from enpi_api.l2.tags import FileTags  # The `FileTags` import contains all system level file tags available in the ENPICOM Platform
38from enpi_api.l2.types.file import OnCollisionAction
39from enpi_api.l2.types.tag import Tag
40from enpi_api.l2.util.execution import wait_all_parallel
41
42with EnpiApiClient() as enpi_client:
43    # Let us assume that we want to upload all FASTA files that are present in the folder `path/to/folder`
44    files_to_upload = glob.glob("path/to/folder/*.fasta")
45
46    # We start the upload for all files, which will return a list of executions
47    executions = list(
48        map(
49            lambda file: enpi_client.file_api.upload_file(
50                file_path=file,
51                # For this example we add the same tag to all files
52                tags=[Tag(id=FileTags.ProjectId, value="My FASTA project")],
53                # If any files with the same name already exist, we overwrite them
54                on_collision=OnCollisionAction.OVERWRITE,
55            ),
56            files_to_upload,
57        )
58    )
59    # Which can then, using the utility function `wait_all_parallel`, be waited for in parallel
60    uploaded_files = wait_all_parallel(executions)
61
62    # At this point, all files have been uploaded and processed, and we could now use them in further parts of a script
63
64```
65##Download a file
66
67Download a file from the ENPICOM Platform.
68```python
69from enpi_api.l2.client.enpi_api_client import EnpiApiClient
70
71with EnpiApiClient() as enpi_client:
72    """We are assuming that a file matching the filename below exists"""
73
74    filename = "Example file"
75
76    # First we need to find the file that we want to download, as we need the ID of the file
77    filtered_by_name = enpi_client.file_api.get_files(filename=filename)
78
79    # We assume there is only a single file with that name
80    file = next(filtered_by_name)
81
82    # Download the file
83    path_to_downloaded_file = enpi_client.file_api.download_file_by_id(
84        file_id=file.id,
85        # This output directory is optional, if not specified, it will be downloaded to a temporary directory
86        output_directory="path/to/output/directory",
87    )
88
89    # You can now use the file at the path specified in `path_to_downloaded_file`
90
91```
92'''