`facile_rs.utils.cli`¶

FACILE-RS command-line tool, used to call the different scripts of the FACILE-RS project.

Description¶

This script is the entry point of the FACILE-RS command-line tool. It is used to call the different scripts of the FACILE-RS project. Use subcommands to select a platform (Zenodo, RADAR, …) or metadata type (CFF, DataCite,…). Use subsubcommands to select a FACILE-RS functionality.

Usage¶

FACILE-RS command-line tool, to perform metadata conversion and software publication based on CodeMeta metadata.

usage: facile-rs [-h]
                 {release,gitlab,radar,zenodo,cff,datacite,bag,bagpack,grav}
                 ...

Positional Arguments¶

subcommand

Possible choices: release, gitlab, radar, zenodo, cff, datacite, bag, bagpack, grav

Select the target platform or metadata type.

Sub-commands¶

release¶

Perform operations on CodeMeta metadata

facile-rs release [-h] {prepare} ...

Sub-commands¶

prepare¶

Update CodeMeta file with the given version and date

facile-rs release prepare [-h] --codemeta-location CODEMETA_LOCATION --version
                          VERSION [--date DATE] [--log-level LOG_LEVEL]
                          [--log-file LOG_FILE]

Named Arguments¶

--codemeta-location

Location of the main codemeta.json JSON file

--version

Version of the resource

--date

Date for dateModified (format: ‘%Y-%m-%d’)

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

gitlab¶

Perform operations for GitLab releases

facile-rs gitlab [-h] {publish} ...

Sub-commands¶

publish¶

Create a release on GitLab

facile-rs gitlab publish [-h] --release-tag RELEASE_TAG
                         [--release-description RELEASE_DESCRIPTION]
                         --release-api-url RELEASE_API_URL --private-token
                         PRIVATE_TOKEN [--dry] [--log-level LOG_LEVEL]
                         [--log-file LOG_FILE]
                         [ASSETS ...]

Positional Arguments¶

ASSETS

Assets to be included in the release.

Default: []

Named Arguments¶

--release-tag

Tag for the release.

--release-description

Description for the release.

--release-api-url

API URL to create the release. Example: https://gitlab.com/api/v4/projects/123/releases

--private-token

The PRIVATE_TOKEN to be used with the GitLab API.

--dry

Perform a dry run, do not perform the final request.

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

radar¶

Perform operations for RADAR releases

facile-rs radar [-h] {prepare,upload} ...

Sub-commands¶

prepare¶

Prepare a release on RADAR

facile-rs radar prepare [-h] [--codemeta-location CODEMETA_LOCATION]
                        --radar-url RADAR_URL --radar-username RADAR_USERNAME
                        --radar-password RADAR_PASSWORD --radar-client-id
                        RADAR_CLIENT_ID --radar-client-secret
                        RADAR_CLIENT_SECRET --radar-workspace-id
                        RADAR_WORKSPACE_ID --radar-redirect-url
                        RADAR_REDIRECT_URL --radar-email RADAR_EMAIL
                        --radar-backlink RADAR_BACKLINK [--keep-previous-doi]
                        [--dry] [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments¶

--codemeta-location

Location of the main codemeta.json JSON file

--radar-url

URL of the RADAR service.

--radar-username

Username for the RADAR service.

--radar-password

Password for the RADAR service.

--radar-client-id

Client ID for the RADAR service.

--radar-client-secret

Client secret for the RADAR service.

--radar-workspace-id

Workspace ID for the RADAR service.

--radar-redirect-url

Redirect URL for the OAuth workflow of the RADAR service.

--radar-email

Email for the RADAR metadata.

--radar-backlink

Backlink for the RADAR metadata.

--keep-previous-doi

When creating a new version, keep the previous DOI in the Codemeta file, in the field “isBasedOn”. By default, the previous DOI is removed.

Default: False

--dry

Perform a dry run, do not upload anything.

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

upload¶

Create a release on RADAR

facile-rs radar upload [-h] --codemeta-location CODEMETA_LOCATION
                       [--creators-locations CREATORS_LOCATIONS]
                       [--contributors-locations CONTRIBUTORS_LOCATIONS]
                       [--no-sort-authors] [--radar-path RADAR_PATH]
                       --radar-url RADAR_URL --radar-username RADAR_USERNAME
                       --radar-password RADAR_PASSWORD --radar-client-id
                       RADAR_CLIENT_ID --radar-client-secret
                       RADAR_CLIENT_SECRET --radar-workspace-id
                       RADAR_WORKSPACE_ID --radar-redirect-url
                       RADAR_REDIRECT_URL --radar-email RADAR_EMAIL
                       --radar-backlink RADAR_BACKLINK
                       [--smtp-server SMTP_SERVER]
                       [--notification-email NOTIFICATION_EMAIL]
                       [--assets-token ASSETS_TOKEN]
                       [--assets-token-name ASSETS_TOKEN_NAME] [--dry]
                       [--overwrite] [--log-level LOG_LEVEL]
                       [--log-file LOG_FILE]
                       [ASSETS ...]

Positional Arguments¶

ASSETS

Assets to be added to the repository.

Default: []

Named Arguments¶

--codemeta-location

Location of the main codemeta.json JSON file

--creators-locations, --creators-location

Locations of codemeta JSON files for additional creators

Default: []

--contributors-locations, --contributors-location

Locations of codemeta JSON files for additional contributors

Default: []

--no-sort-authors

Do not sort authors alphabetically, keep order in codemeta.json file

Default: True

--radar-path

Path to the local directory, where the assets are collected before upload. Optional: if not provided, a temporary directory is used.

--radar-url

URL of the RADAR service.

--radar-username

Username for the RADAR service.

--radar-password

Password for the RADAR service.

--radar-client-id

Client ID for the RADAR service.

--radar-client-secret

Client secret for the RADAR service.

--radar-workspace-id

Workspace ID for the RADAR service.

--radar-redirect-url

Redirect URL for the OAuth workflow of the RADAR service.

--radar-email

Email for the RADAR metadata.

--radar-backlink

Backlink for the RADAR metadata.

--smtp-server

SMTP server used to inform about new release. No mail sent if empty.

--notification-email

Recipient address to inform about new release. No mail sent if empty.

--assets-token

Private token, to be used when fetching assets

--assets-token-name

Name of the header field for the token [default: “PRIVATE-TOKEN”]

Default: 'PRIVATE-TOKEN'

--dry

Perform a dry run, do not upload anything.

Default: False

--overwrite

Overwrite existing local assets.

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

zenodo¶

Perform operations for Zenodo releases

facile-rs zenodo [-h] {prepare,upload} ...

Sub-commands¶

prepare¶

Prepare a release on Zenodo

facile-rs zenodo prepare [-h] [--codemeta-location CODEMETA_LOCATION]
                         --zenodo-url ZENODO_URL --zenodo-token ZENODO_TOKEN
                         [--zenodo-version-update ZENODO_VERSION_UPDATE]
                         [--keep-previous-doi] [--dry] [--log-level LOG_LEVEL]
                         [--log-file LOG_FILE]

Named Arguments¶

--codemeta-location

Location of the main codemeta.json JSON file

--zenodo-url

URL of the Zenodo service. Test environment available at https://sandbox.zenodo.org

--zenodo-token

Zenodo personal token.

--zenodo-version-update

Enable Zenodo version update. Can be “codemeta” or a Zenodo identifier. If omitted, a new Zenodo dataset is created without versioning. If set to “codemeta”, a Zenodo identifier is searched in the CodeMeta file, and a new version is created from it (if found). Any other value is considered as a Zenodo identifier: a new version will be created from it.

--keep-previous-doi

When creating a new version, keep the previous DOI in the Codemeta file, in the field “isBasedOn”. By default, the previous DOI is removed.

Default: False

--dry

Perform a dry run, do not upload anything.

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

upload¶

Create a release on Zenodo

facile-rs zenodo upload [-h] --codemeta-location CODEMETA_LOCATION
                        [--creators-locations CREATORS_LOCATIONS]
                        [--contributors-locations CONTRIBUTORS_LOCATIONS]
                        [--no-sort-authors] [--zenodo-path ZENODO_PATH]
                        --zenodo-url ZENODO_URL --zenodo-token ZENODO_TOKEN
                        [--smtp-server SMTP_SERVER]
                        [--notification-email NOTIFICATION_EMAIL]
                        [--assets-token ASSETS_TOKEN]
                        [--assets-token-name ASSETS_TOKEN_NAME] [--dry]
                        [--overwrite] [--log-level LOG_LEVEL]
                        [--log-file LOG_FILE]
                        [ASSETS ...]

Positional Arguments¶

ASSETS

Assets to be added to the repository.

Default: []

Named Arguments¶

--codemeta-location

Location of the main codemeta.json JSON file

--creators-locations, --creators-location

Locations of codemeta JSON files for additional creators

Default: []

--contributors-locations, --contributors-location

Locations of codemeta JSON files for additional contributors

Default: []

--no-sort-authors

Do not sort authors alphabetically, keep order in codemeta.json file

Default: True

--zenodo-path

Path to the local directory, where the assets are collected before upload. Optional: if not provided, a temporary directory is used.

--zenodo-url

URL of the Zenodo service. Test environment available at https://sandbox.zenodo.org

--zenodo-token

Zenodo personal token.

--smtp-server

SMTP server used to inform about new release. No mail sent if empty.

--notification-email

Recipient address to inform about new release. No mail sent if empty.

--assets-token

Private token, to be used when fetching assets

--assets-token-name

Name of the header field for the token [default: “PRIVATE-TOKEN”]

Default: 'PRIVATE-TOKEN'

--dry

Perform a dry run, do not upload anything.

Default: False

--overwrite

Overwrite existing local assets.

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

cff¶

Generate and manage CFF metadata

facile-rs cff [-h] {create} ...

Sub-commands¶

create¶

Create a CFF metadata file

facile-rs cff create [-h] --codemeta-location CODEMETA_LOCATION
                     [--creators-locations CREATORS_LOCATIONS]
                     [--contributors-locations CONTRIBUTORS_LOCATIONS]
                     [--cff-path CFF_PATH] [--no-sort-authors]
                     [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments¶

--codemeta-location

Locations of the main codemeta.json JSON file

--creators-locations, --creators-location

Locations of codemeta JSON files for additional creators

Default: []

--contributors-locations, --contributors-location

Locations of codemeta JSON files for additional contributors

Default: []

--cff-path

Path to the cff output file

--no-sort-authors

Do not sort authors alphabetically, keep order in codemeta.json file

Default: True

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

datacite¶

Generate and manage DataCite metadata

facile-rs datacite [-h] {create} ...

Sub-commands¶

create¶

Create a DataCite metadata file

facile-rs datacite create [-h] --codemeta-location CODEMETA_LOCATION
                          [--creators-locations CREATORS_LOCATIONS]
                          [--contributors-locations CONTRIBUTORS_LOCATIONS]
                          [--datacite-path DATACITE_PATH] [--no-sort-authors]
                          [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments¶

--codemeta-location

Location of the main codemeta.json JSON file

--creators-locations, --creators-location

Locations of codemeta JSON files for additional creators

Default: []

--contributors-locations, --contributors-location

Locations of codemeta JSON files for additional contributors

Default: []

--datacite-path

Path to the DataCite XML output file

--no-sort-authors

Do not sort authors alphabetically, keep order in codemeta.json file

Default: True

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

bag¶

Generate and manage BagIt bags.

facile-rs bag [-h] {create} ...

Sub-commands¶

create¶

Create a BagIt bag.

facile-rs bag create [-h] --bag-path BAG_PATH
                     [--bag-info-locations BAG_INFO_LOCATIONS]
                     [--assets-token ASSETS_TOKEN]
                     [--assets-token-name ASSETS_TOKEN_NAME] [--overwrite]
                     [--log-level LOG_LEVEL] [--log-file LOG_FILE]
                     [ASSETS ...]

Positional Arguments¶

ASSETS

Assets to be added to the bag.

Default: []

Named Arguments¶

--bag-path

Path to the Bag directory

--bag-info-locations, --bag-info-location

Locations of the bag-info YAML/JSON files

Default: []

--assets-token

Private token, to be used when fetching assets

--assets-token-name

Name of the header field for the token [default: “PRIVATE-TOKEN”]

Default: 'PRIVATE-TOKEN'

--overwrite

Overwrite existing Bag directory

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

bagpack¶

Generate and manage BagPack bags (BagIt with DataCite metadata)

facile-rs bagpack [-h] {create} ...

Sub-commands¶

create¶

Create a BagIt bag with DataCite metadata

facile-rs bagpack create [-h] [--bag-path BAG_PATH]
                         [--bag-info-locations BAG_INFO_LOCATIONS]
                         [--datacite-location DATACITE_LOCATION]
                         [--assets-token ASSETS_TOKEN]
                         [--assets-token-name ASSETS_TOKEN_NAME] [--overwrite]
                         [--log-level LOG_LEVEL] [--log-file LOG_FILE]
                         [ASSETS ...]

Positional Arguments¶

ASSETS

Assets to be added to the bag.

Default: []

Named Arguments¶

--bag-path

Path to the Bag directory

--bag-info-locations, --bag-info-location

Locations of the bag-info YAML/JSON files

Default: []

--datacite-location

Path to the DataCite XML file

--assets-token

Private token, to be used when fetching assets

--assets-token-name

Name of the header field for the token [default: “PRIVATE-TOKEN”]

Default: 'PRIVATE-TOKEN'

--overwrite

Overwrite existing Bag directory

Default: False

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

grav¶

Perform operations for Grav CMS

facile-rs grav [-h] {bibtex,docstring,experiments,markdown} ...

Sub-commands¶

bibtex¶

Run the BibTex conversion pipeline

facile-rs grav bibtex [-h] --grav-path GRAV_PATH --pipeline PIPELINE
                      --pipeline-source PIPELINE_SOURCE
                      [--pipeline-csl PIPELINE_CSL] [--log-level LOG_LEVEL]
                      [--log-file LOG_FILE]

Named Arguments¶

--grav-path

Path to the grav repository directory.

--pipeline

Name of the pipeline as specified in the GRAV metadata.

--pipeline-source

Path to the source directory for the pipeline.

--pipeline-csl

Path to the source directory for the pipeline.

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

docstring¶

Run the docstring conversion pipeline

facile-rs grav docstring [-h] --grav-path GRAV_PATH --pipeline PIPELINE
                         --pipeline-source PIPELINE_SOURCE
                         [--pipeline-images PIPELINE_IMAGES]
                         [--pipeline-header PIPELINE_HEADER]
                         [--pipeline-footer PIPELINE_FOOTER]
                         [--pipeline-refs PIPELINE_REFS] [--output-html]
                         [--mathjax-location MATHJAX_LOCATION]
                         [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments¶

--grav-path

Path to the grav repository directory.

--pipeline

Name of the pipeline as specified in the GRAV metadata.

--pipeline-source

Path to the source directory for the pipeline.

--pipeline-images

Path to the images directory for the pipeline.

--pipeline-header

Path to the header template.

--pipeline-footer

Path to the footer template.

--pipeline-refs

Path to the refs yaml file.

--output-html

Output HTML files instead of markdown

Default: False

--mathjax-location

Location of the MathJax script for math rendering in HTML output. This option is only used if –output-html is set. Set to empty string to disable MathJax.

Default: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

experiments¶

Run the experiments conversion pipeline

facile-rs grav experiments [-h] --grav-path GRAV_PATH --pipeline PIPELINE
                           [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments¶

--grav-path

Path to the grav repository directory.

--pipeline

Name of the pipeline as specified in the GRAV metadata.

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

markdown¶

Run the Markdown conversion pipeline

facile-rs grav markdown [-h] --grav-path GRAV_PATH --pipeline PIPELINE
                        --pipeline-source PIPELINE_SOURCE
                        [--log-level LOG_LEVEL] [--log-file LOG_FILE]

Named Arguments¶

--grav-path

Path to the grav repository directory.

--pipeline

Name of the pipeline as specified in the GRAV metadata.

--pipeline-source

Path to the source directory for the pipeline.

--log-level

Log level (ERROR, WARN, INFO, or DEBUG)

Default: 'WARN'

--log-file

Path to the log file

Get help on a subcommand by running ‘facile-rs <subcommand> -h’.

Examples¶

To generate CFF metadata from a CodeMeta metadata file:

$ facile-rs cff create –codemeta-location codemeta.json

Module Contents¶

Classes¶

Parser

Custom ArgumentParser class, which adds the functionality to add default values from the environment.

Functions¶

`create_parser`	Create parsers for the facile-rs command line interface. The main parser has one subparser per platform (Zenodo, RADAR, …) or metadata type (CFF, DataCite,…). Each of this subparser has a subparser per FACILE-RS script.
`setup_env`
`setup_logs`
`main`
`main_deprecated`	Display a deprecation warning when a script is called from the command line directly, without using the ‘facile-rs’ entry point.

API¶

class Parser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)¶

Bases: argparse.ArgumentParser

Custom ArgumentParser class, which adds the functionality to add default values from the environment.

Initialization

add_argument(*args, **kwargs)¶

get_subparser(subcommand)¶

create_parser()¶

Create parsers for the facile-rs command line interface. The main parser has one subparser per platform (Zenodo, RADAR, …) or metadata type (CFF, DataCite,…). Each of this subparser has a subparser per FACILE-RS script.

Returns:: The parser object.

setup_env()¶

setup_logs(log_level, log_file)¶

main()¶

main_deprecated(module_name)¶

Display a deprecation warning when a script is called from the command line directly, without using the ‘facile-rs’ entry point.

Parameters:: func – The main function to call in the script.

facile_rs.utils.cli¶

Description¶

Usage¶

Positional Arguments¶

Sub-commands¶

release¶

Sub-commands¶

prepare¶

Named Arguments¶

gitlab¶

Sub-commands¶

publish¶

Positional Arguments¶

Named Arguments¶

radar¶

Sub-commands¶

prepare¶

Named Arguments¶

upload¶

Positional Arguments¶

Named Arguments¶

zenodo¶

Sub-commands¶

prepare¶

Named Arguments¶

upload¶

Positional Arguments¶

Named Arguments¶

cff¶

Sub-commands¶

create¶

Named Arguments¶

datacite¶

Sub-commands¶

create¶

Named Arguments¶

bag¶

Sub-commands¶

create¶

Positional Arguments¶

Named Arguments¶

bagpack¶

Sub-commands¶

create¶

Positional Arguments¶

Named Arguments¶

grav¶

Sub-commands¶

bibtex¶

Named Arguments¶

docstring¶

Named Arguments¶

experiments¶

Named Arguments¶

markdown¶

Named Arguments¶

Examples¶

Module Contents¶

Classes¶

Functions¶

API¶

`facile_rs.utils.cli`¶