New and imroved export behavior - [merged]

[alexander-haller]

In GitLab by @mhxion on Nov 6, 2023, 24:56

Merges new-export-behavior -> dev

Export

Fixes #2. Export function now is as powerful as shell redirection. It acts almost exactly the same way as before.

--export as a flag: When --export is passed without any following value/path, it acts as a flag, and export_dir value from elapi.yaml configuration file is used. It should be clear that export_dir in a configuration file only accepts a directory path.*

--export to a directory: If a directory path is provided as a value, i.e., --export <path/to/directory>, then that path is used instead. When the path is a directory, the file name is auto-generated using the following scheme: DATE_HHMMSS_<FUNCTION>.EXT

DATE_HHMMSS_<FUNCTION>.EXT. New in this patch, date comes first as you preferred. This one's for you ; )

(NEW) --export to a file: Exporting always to a directory with a fixed file name scheme poses some issues.

• The default file name scheme can be undesired. I.e., If a user preferred to have only the date in the name, and not the time.
• The default name creates a new file for every time data is exported. This guarantees data retention. However, if export is used heavily (e.g. for debugging something), it will create a new file for every single export. This can quickly lead to a spam of files, and also make it difficult for the user to search for a specific file.

To address those issues, --export now supports a path to a direct file as well. When a file path is passed, i.e., --export <path/to/file.json>, then data is simply exported to that file. A few examples:

elapi get users --id 1 --export ~/Download/user_with_id_1.yaml

# Will be exported to ~/Download/user_with_id_1.yaml in YAML format every time.

elapi get users --id 1 --export ~/Download/user_1_$(date '+%Y-%m-%d').json

# Export with a custom naming scheme. Here, Bash `date` provides the date.
# Will be exported to /Download/user_1_2023-11-06.json in JSON format.

elapi get users --id 1 --export /usr/bin/user_with_id_1.yaml

# Export comes with a export file validator. A path without write permission will be invalidated, 
# so export will fallback to `export_dir` defined in configuration file.
# If `export_dir` isn't defined or it gets invalidated as well, export will fallback to 
# `XDG_DOWNLOAD_DIR`, and if that is invalidated too, 
# the fallback will be `$HOME/Downloads`. This fallback order is the same as before.

When export is successful, a success message including the full file path will always be printed. show-config command can always be run to see which export path will be used when no path is explicitly passed to --export. As always, show-config is there to alleviate any confusion with the fallback order.

*: --export to a file completes the exporting feature. However, for our use cases, for bill-teams, we will likely never export directly to a file. We will define our desired export location export_dir in the configuration file instead. From the name it's clear export_dir only expects a directory path, and not a file path! If a file path is assigned as a value for export_dir, elAPI can detect that, and will show warning against such mistakes.

Format

Previously, we could pass desired format for returned data with the argument --output or -o. You mentioned in the past, how the term --output could get confusing. And now it does the most since we currently have both --export and --output! This PR renames --output/-o to --format/-F. Example:

elapi get users --id 1 -F json --export

# Exports to `export_dir` from configuration file in JSON format.

[alexander-haller]

In GitLab by @mhxion on Nov 6, 2023, 24:56

requested review from @alexander-haller

[alexander-haller]

Very good

[alexander-haller]

approved this merge request

[alexander-haller]

In GitLab by @mhxion on Nov 9, 2023, 15:02

I am glad you liked it! : ) Thanks for approving.

[alexander-haller]

In GitLab by @mhxion on Nov 9, 2023, 15:02

resolved all threads