diff --git a/contribute/modules/ROOT/nav.adoc b/contribute/modules/ROOT/nav.adoc index 824ec254..d129db78 100644 --- a/contribute/modules/ROOT/nav.adoc +++ b/contribute/modules/ROOT/nav.adoc @@ -4,4 +4,4 @@ .How to contribute ** xref:index.adoc#contrib-desc[an example or a benchmark description?] ** xref:index.adoc#contrib[an example or a benchmark?] -** xref:vtkjs.adoc[{vtkjs} files?] +** xref:vtkjs.adoc[{vtkjs} files?] \ No newline at end of file diff --git a/contribute/modules/girder/nav.adoc b/contribute/modules/girder/nav.adoc index 9b4e4840..f13f54a2 100644 --- a/contribute/modules/girder/nav.adoc +++ b/contribute/modules/girder/nav.adoc @@ -1,13 +1,13 @@ * xref:README.adoc[How to contribute data with Girder] -** xref:README.adoc#_what_is_girder[What is Girder] -** xref:README.adoc#_file_access_options[File access options] -*** xref:README.adoc#_web_browser_ui[Web brower UI] -*** xref:README.adoc#_python_api[Python API] -** xref:python_scripts.adoc[Python scripts examples] -*** xref:python_scripts.adoc#_with_user_and_password[With user and password] -**** xref:python_scripts.adoc#_what_not_to_do[What not to do] -**** xref:python_scripts.adoc#_interactive_download[Interactive download] -**** xref:python_scripts.adoc#_interactive_upload[Interactive upload] -*** xref:api_keys.adoc#_using_api_keys[Using API keys] -**** xref:api_keys.adoc#_download[Download] -**** xref:api_keys.adoc#_upload[Upload] + ** xref:README.adoc#_what_is_girder[What is Girder] + ** xref:README.adoc#_file_access_options[File access options] + *** xref:README.adoc#_web_browser_ui[Web brower UI] + *** xref:README.adoc#_python_api[Python API] + ** xref:python_scripts.adoc[Python scripts examples] + *** xref:python_scripts.adoc#_with_user_and_password[With user and password] + **** xref:python_scripts.adoc#_what_not_to_do[What not to do] + **** xref:python_scripts.adoc#_interactive_download[Interactive download] + **** xref:python_scripts.adoc#_interactive_upload[Interactive upload] + *** xref:api_keys.adoc#_using_api_keys[Using API keys] + **** xref:api_keys.adoc#_download[Download] + **** xref:api_keys.adoc#_upload[Upload] \ No newline at end of file diff --git a/contribute/modules/girder/pages/README.adoc b/contribute/modules/girder/pages/README.adoc index 8357c6f2..0530e43c 100644 --- a/contribute/modules/girder/pages/README.adoc +++ b/contribute/modules/girder/pages/README.adoc @@ -7,45 +7,4 @@ It can be used to store (large) files such as meshes, simulation results, etc... Read more about it in the {feelpp} xref:data:ROOT:data-storage.adoc[data manual] or link:http://girder.readthedocs.io/[on the official website]. -== File access options - -A big advantage of girder is that files can be accessed either with a nice user -interface (in a web browser) or more programmatically (via CLI or programming -interfaces). -This is true for both upload and download. - -=== Web browser UI - -If you are new to Girder, you should start with the web user interface to -discover the service. -You are encouraged to read the documentation -link:http://girder.readthedocs.io/[documentation] and especially the -link:http://girder.readthedocs.io/en/latest/user-docs.html[user guide]. -For example, using a web browser, you can reach -link:https://girder.math.unistra.fr/#collections[our server]. - -|=== -| image:girder_web_ui.png[Web user interface,100%] -|=== - -NOTE: This is quite straightforward and it should illustrate important concepts -and help better visualize the following section. - -=== Python API - -To download or upload a file using python, we have two options. -We can either use a login system (user + password) or an API key. -- With the user/password, we will need to provide a user and a password to -access files, just like a human would do using the UI. -- With an API key, the script only needs an API key. -This means we do not need to have an account on the Girder server. - -In both cases, similar pieces of information are required: - -- an *address* (URL): to reach the server, -- a *file ID*: to tell which file/directory we want to manipulate, -- either a *user/password* pair or an *API key*: to grant access to the -required file(s). - -Let's check out some -xref:contribute:girder:python_scripts.adoc[scripts]. +include::data:ROOT:partial$girder/README.adoc[] \ No newline at end of file diff --git a/contribute/modules/girder/pages/api_keys.adoc b/contribute/modules/girder/pages/api_keys.adoc index a77522a4..959e2b4a 100644 --- a/contribute/modules/girder/pages/api_keys.adoc +++ b/contribute/modules/girder/pages/api_keys.adoc @@ -1,79 +1 @@ -= Using API keys - -An API key grants access to a certain set of files, with various permissions. -It is very useful and quite convenient to use. -Since it is nothing more than a character string, one could think of it as a -long and pseudorandom special password. - -NOTE: To learn how to set API keys, read -link:http://girder.readthedocs.io/en/latest/user-guide.html#api-keys[this part] -of the documentation. - -== Download - -To use an API key to download a file, see this script: - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using only the API key -gc.authenticate(apiKey='KEY') # <1> - -# We download the file using its file ID. The path indicates where the file -# should be written (the full file name should be included at the end of the path) -gc.downloadFile(fileId='FILEID', path='PATH') # <2> - ----- - -<1> *KEY* is the only needed information to authenticate. - -<2> *FILEID* should be replaced by the actual Girder file ID and *PATH* should -be the path where to store the results, including the desired file name and -extension. - - -== Upload - -To upload using an API key: - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using only the API key -gc.authenticate(apiKey='KEY') # <1> - -# /!\ This is mandatory: we have to open the file in read mode before -# uploading it -f = open('PATH', 'r') # <2> - -# Now we can upload the file <3> -gc.uploadFile(parentId='PID', stream=f, name="NAME", size=SIZE, parentType='TYPE') - ----- - -<1> *KEY* is the only needed information to authenticate. - -<2> *PATH* should be replaced by the full path to the file to read. -*r* stands for "read mode". - -<3> *PID* should be replaced by the parent directory ID (on the Girder server). -*f* is the read stream defined previously . -*NAME* should be replaced by the desired file name (on the Girder server). -*SIZE* should be replaced by the file size (in bytes). -*TYPE* is either *folder*, *user*, or *collection*. +include::data:ROOT:partial$girder/api_keys.adoc[] \ No newline at end of file diff --git a/contribute/modules/girder/pages/python_scripts.adoc b/contribute/modules/girder/pages/python_scripts.adoc index 34d94f40..f8f86185 100644 --- a/contribute/modules/girder/pages/python_scripts.adoc +++ b/contribute/modules/girder/pages/python_scripts.adoc @@ -1,137 +1 @@ -= Python scripts - -Here, we provide some python scripts to access files on Girder. -To be able to use them, please install the girder client python module (read how -link:http://girder.readthedocs.io/en/latest/python-client.html[here]. -) - -== With user and password - -=== What not to do - -WARNING: The following script is only meant as a first approach to understand -how the module works. -You should not use it because it requires your password to be written in clear -in the script. -Use the xref:python_scripts.adoc#_interactive_download[interactive version] -instead. - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using the username and the password. -# /!\ This is for learning purpose. -# For security reasons, you should never put your password in the script. -gc.authenticate(username='USER', password='PASSWORD') # <1> - -# We download the file using its file ID. The path indicates where the file -# should be written (the file name should be included at the end of the path) -gc.downloadFile(fileId='FILEID', path='PATH') # <2> - ----- -<1> *USER* should be replaced by the Girder user name, -*PASSWORD* by the corresponding password -<2> *FILEID* should be replaced by the actual Girder file ID and *PATH* should -be the path where to store the results, including the desired file name and -extension. - -WARNING: If you don't supply the file name, the system will not warn you, it -will *automatically generate one*, which could be confusing ! - -IMPORTANT: Remember not to use this script. Try the -xref:python_scripts.adoc#_interactive_download[interactive one] instead. - - -=== Interactive download - -Here, we use a modified version of the _authenticate_ function to use -interactive login. -This means the password will be prompted for at run time. - -IMPORTANT: This implies the script can not be used in a fully automated way, -because each execution of the script will require the user of the script to be -present to type the password. For a safe and automatic access, use the -xref:api_keys.adoc#_using_api_keys[API keys]. - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using the username, the password will be typed at runtime -gc.authenticate(username='USER', interactive=True) # <1> - -# We download the file using its file ID. The path indicates where the file -# should be written (the full file name should be included at the end of the path) -gc.downloadFile(fileId='FILEID', path='PATH') # <2> - ----- -<1> *USER* should be replaced by the Girder user name, and because of the -_interactive=True_ argument, the password will be prompted for at runtime. -<2> *FILEID* should be replaced by the actual Girder file ID and *PATH* should be the path where to store the results, including the desired file name and extension. - -TIP: We can even prompt the user to type *both the user name and the password* -by providing *only* the _interactive=True_ argument ! -This is a better solution when multiple users are likely to use the script only -once or a handful of times each. - -WARNING: If you don't supply the file name, the system will not warn you, it -will *automatically generate one*, which could be confusing ! - - - -=== Interactive upload - -To upload a file, only a few changes are required. - -[source, python] ----- -#!/usr/bin/env python3 - - -# We need the girder client module. -import girder_client - -# First, we initiate the client with the girder server address. -gc = girder_client.GirderClient(apiUrl='https://girder.math.unistra.fr/api/v1') - -# We authenticate using the username, the password will be typed at runtime -gc.authenticate(username='USER', interactive=True) # <1> - - -# /!\ This is mandatory: we have to open the file in read mode before -# uploading it -f = open('PATH', 'r') # <2> - -# Now we can upload the file <3> -gc.uploadFile(parentId='PID', stream=f, name="NAME", size=SIZE, parentType='TYPE') - ----- - -<1> *USER* should be replaced by the Girder user name, and because of the -_interactive=True_ argument, the password will be prompted for at runtime. - -<2> *PATH* should be replaced by the full path to the file to read. -*r* stands for "read mode". - -<3> *PID* should be replaced by the parent directory ID (on the Girder server). -*f* is the read stream defined previously . -*NAME* should be replaced by the desired file name (on the Girder server). -*SIZE* should be replaced by the file size (in bytes). -*TYPE* is either *folder*, *user*, or *collection*. - -NOTE: We should try and find a way to get the file size automatically. +include::data:ROOT:partial$girder/python_scripts.adoc[] \ No newline at end of file