Skip to content

Commit 6f0776e

Browse files
clayandgenclayandgen
authored
[Documentation] Add docs on download_file (#2555)
* [Documentation] Add docs on download_file * Add whitelisting
1 parent 9316dce commit 6f0776e

File tree

2 files changed

+89
-39
lines changed

2 files changed

+89
-39
lines changed

‎docs.openc3.com/docs/guides/scripting-api.md‎

Lines changed: 86 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -312,6 +312,83 @@ match value:
312312
</TabItem>
313313
</Tabs>
314314

315+
### open_file_dialog
316+
317+
### open_files_dialog
318+
319+
The open_file_dialog and open_files_dialog methods create a file dialog box so the user can select a single or multiple files. The selected file(s) is returned.
320+
321+
Note: COSMOS 5 has deprecated the save_file_dialog and open_directory_dialog methods. save_file_dialog can be replaced by put_target_file if you want to write a file back to the target. open_directory_dialog doesn't make sense in new architecture so you must request individual files.
322+
323+
<Tabs groupId="script-language">
324+
<TabItem value="ruby" label="Ruby Syntax">
325+
326+
```ruby
327+
open_file_dialog("<Title>", "<Message>", filter: "<filter>")
328+
open_files_dialog("<Title>", "<Message>", filter: "<filter>")
329+
```
330+
331+
</TabItem>
332+
333+
<TabItem value="python" label="Python Syntax">
334+
335+
```python
336+
open_file_dialog("<Title>", "<Message>", filter="<filter>")
337+
open_files_dialog("<Title>", "<Message>", filter="<filter>")
338+
```
339+
340+
</TabItem>
341+
</Tabs>
342+
343+
| Parameter | Description |
344+
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
345+
| Title | The title to put on the dialog. Required. |
346+
| Message | The message to display in the dialog box. Optional parameter. |
347+
| filter | Named parameter to filter allowed file types. Optional parameter, specified as comma delimited file types, e.g. ".txt,.doc". See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept for more information. |
348+
349+
<Tabs groupId="script-language">
350+
<TabItem value="ruby" label="Ruby Example">
351+
352+
```ruby
353+
file = open_file_dialog("Open a single file", "Choose something interesting", filter: ".txt")
354+
puts file # Ruby File object
355+
puts file.read
356+
file.delete
357+
358+
files = open_files_dialog("Open multiple files") # message is optional
359+
puts files # Array of File objects (even if you select only one)
360+
files.each do |file|
361+
puts file
362+
puts file.read
363+
file.delete
364+
end
365+
```
366+
367+
</TabItem>
368+
369+
<TabItem value="python" label="Python Example">
370+
371+
```python
372+
file = open_file_dialog("Open a single file", "Choose something interesting", filter=".txt")
373+
print(file)
374+
print(file.read())
375+
file.close()
376+
377+
files = open_files_dialog("Open multiple files") # message is optional
378+
print(files) # Array of File objects (even if you select only one)
379+
for file in files:
380+
print(file)
381+
print(file.read())
382+
file.close()
383+
```
384+
385+
</TabItem>
386+
</Tabs>
387+
388+
## File Manipulation
389+
390+
These methods provide capability to interact with files in the target directory.
391+
315392
### get_target_file
316393

317394
Return a file handle to a file in the target directory
@@ -470,74 +547,45 @@ delete_target_file("INST/delete_me.txt")
470547
</TabItem>
471548
</Tabs>
472549

473-
### open_file_dialog
474-
475-
### open_files_dialog
476-
477-
The open_file_dialog and open_files_dialog methods create a file dialog box so the user can select a single or multiple files. The selected file(s) is returned.
550+
### download_file
478551

479-
Note: COSMOS 5 has deprecated the save_file_dialog and open_directory_dialog methods. save_file_dialog can be replaced by put_target_file if you want to write a file back to the target. open_directory_dialog doesn't make sense in new architecture so you must request individual files.
552+
Prompts the user to download a file from the OpenC3 system to their local machine.
480553

481554
<Tabs groupId="script-language">
482555
<TabItem value="ruby" label="Ruby Syntax">
483556

484557
```ruby
485-
open_file_dialog("<Title>", "<Message>", filter: "<filter>")
486-
open_files_dialog("<Title>", "<Message>", filter: "<filter>")
558+
download_file("<File Path>")
487559
```
488560

489561
</TabItem>
490562

491563
<TabItem value="python" label="Python Syntax">
492564

493565
```python
494-
open_file_dialog("<Title>", "<Message>", filter="<filter>")
495-
open_files_dialog("<Title>", "<Message>", filter="<filter>")
566+
download_file("<File Path>")
496567
```
497568

498569
</TabItem>
499570
</Tabs>
500571

501-
| Parameter | Description |
502-
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503-
| Title | The title to put on the dialog. Required. |
504-
| Message | The message to display in the dialog box. Optional parameter. |
505-
| filter | Named parameter to filter allowed file types. Optional parameter, specified as comma delimited file types, e.g. ".txt,.doc". See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept for more information. |
572+
| Parameter | Description |
573+
| --------- | --------------------------------------------------------------------------- |
574+
| File Path | File Path to the file to download within the OpenC3 system. |
506575

507576
<Tabs groupId="script-language">
508577
<TabItem value="ruby" label="Ruby Example">
509578

510579
```ruby
511-
file = open_file_dialog("Open a single file", "Choose something interesting", filter: ".txt")
512-
puts file # Ruby File object
513-
puts file.read
514-
file.delete
515-
516-
files = open_files_dialog("Open multiple files") # message is optional
517-
puts files # Array of File objects (even if you select only one)
518-
files.each do |file|
519-
puts file
520-
puts file.read
521-
file.delete
522-
end
580+
download_file("targets/INST/procedures/my_data.csv")
523581
```
524582

525583
</TabItem>
526584

527585
<TabItem value="python" label="Python Example">
528586

529587
```python
530-
file = open_file_dialog("Open a single file", "Choose something interesting", filter=".txt")
531-
print(file)
532-
print(file.read())
533-
file.close()
534-
535-
files = open_files_dialog("Open multiple files") # message is optional
536-
print(files) # Array of File objects (even if you select only one)
537-
for file in files:
538-
print(file)
539-
print(file.read())
540-
file.close()
588+
download_file("targets/INST/procedures/my_data.csv")
541589
```
542590

543591
</TabItem>

‎openc3/spec/install/api_docs_spec.rb‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ module OpenC3
2828
IGNORED_APIS.concat(%w(running_script_backtrace running_script_debug running_script_prompt update_news update_plugin_store))
2929
IGNORED_APIS.concat(%w(package_install package_uninstall package_status package_download))
3030
IGNORED_APIS.concat(%w(plugin_install_phase1 plugin_install_phase2 plugin_update_phase1 plugin_uninstall plugin_status))
31+
# APIs that are documented but intentionally not in standard source locations
32+
EXTRA_DOCS_ALLOWED = %w(download_file)
3133

3234
def parse_file(filename, methods)
3335
File.open(filename) do |file|
@@ -134,7 +136,7 @@ def documented
134136
end
135137

136138
it "should not have extra documentation" do
137-
extra = @documented - @ruby_api.keys - @python_api.keys
139+
extra = @documented - @ruby_api.keys - @python_api.keys - EXTRA_DOCS_ALLOWED
138140
expect(extra).to be_empty, "Documented in scripting-api.md but not in source: #{extra}"
139141
end
140142

0 commit comments

Comments
 (0)