Reference¶
about¶
Syntax
about [OPTIONS] [COMMANDS]
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
attrib LOCATION: directory, OUTPUT: output file
check LOCATION: directory
gen LOCATION: input file, OUTPUT: directory
inventory LOCATION: directory, OUTPUT: csv file
attrib¶
Syntax
about attrib [OPTIONS] LOCATION OUTPUT
LOCATION: Path to an ABOUT file or a directory containing ABOUT files.
OUTPUT: Path to output file to write the attribution to.
Options:
--inventory PATH Path to an inventory file.
--mapping Use for mapping between the input keys and the ABOUT field.
names - mapping.config
--mapping-file Use a custom mapping file with mapping between input
keys and ABOUT field names.
--template PATH Path to a custom attribution template.
--vartext TEXT Variable texts to the attribution template
--verbose Show all the errors and warning.
-q, --quiet Do not print any error/warning.
-h, --help Show this message and exit.
Purpose¶
Generate an attribution file which contains the all license information from the LOCATION along with the license text.
Assume the following:
'/home/about_files/'** contains all the ABOUT files [LOCATION]
'/home/attribution/attribution.html' is the user's output path [OUTPUT]
'/home/project/component_list.csv' is the inventory that user want to be generated
$ about attrib /home/about_files/ /home/attribution/attribution.html
Options¶
--inventory
This option allows you to define which ABOUT files should be used for attribution generation.
For instance,
'/home/project/component_list.csv' is the inventory that user want to be generated
$ about attrib --inventory /home/project/component_list.csv LOCATION OUTPUT
--mapping
See mapping.config for details
--mapping-file
Same behavior as `--mapping` but with custom mapping file
$ about attrib --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT
--template
This option allows you to use your own template for attribution generation.
For instance, if you have a custom template located at:
/home/custom_template/template.html
$ about attrib --template /home/custom_template/template.html LOCATION OUTPUT
--vartext
This option allow you to pass variable texts to the attribution template
$ about attrib --vartext "title=Attribution Notice" --vartext "header=Product 101" LOCATION OUTPUT
Users can use the following in the template to get the vartext:
{{ vartext_dict['title'] }}
{{ vartext_dict['header'] }}
--verbose
This option tells the tool to show all errors found.
The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'
- The following data are passed to jinja2 and, therefore, can be used for a custom template:
about object: the about objects
common_licenses: a common license keys list in licenses.py
license_key_and_context: a dictionary list with license_key as a key and license text as the value
license_file_name_and_key: a dictionary list with license file name as a key and license key as the value
license_key_to_license_name: a dictionary list with license key as a key and license file name as the value
check¶
Syntax
about check [OPTIONS] LOCATION
LOCATION: Path to an ABOUT file or a directory with ABOUT files.
Options:
--verbose Show all the errors and warning
-h, --help Show this message and exit.
Purpose¶
Validating ABOUT files at LOCATION.
Options¶
--verbose
This option tells the tool to show all errors found.
The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'
$ about check --verbose /home/project/about_files/
gen¶
Syntax
about gen [OPTIONS] LOCATION OUTPUT
LOCATION: Path to a JSON or CSV inventory file.
OUTPUT: Path to a directory where ABOUT files are generated.
Options:
--fetch-license KEY Fetch licenses text from a DejaCode API. and
create <license>.LICENSE side-by-side
with the generated .ABOUT file using data
fetched from a DejaCode License Library. The
following additional options are required:
api_url - URL to the DejaCode License Library
API endpoint
api_key - DejaCode API key
Example syntax:
about gen --fetch-license 'api_url' 'api_key'
--license-notice-text-location PATH Copy the 'license_file' from the directory to
the generated location.
--mapping Use for mapping between the input keys and
the ABOUT field names - mapping.config
--mapping-file Use a custom mapping file with mapping between input
keys and ABOUT field names.
--verbose Show all the errors and warning.
-q, --quiet Do not print any error/warning.
-h, --help Show this message and exit.
Purpose¶
Given an inventory of ABOUT files at location, generate ABOUT files in base directory.
Options¶
--fetch-license
Fetch licenses text from a DejaCode API. and create <license>.LICENSE side-by-side
with the generated .ABOUT file using data fetched from a DejaCode License Library.
This option requires 2 parameters:
api_url - URL to the DJE License Library
api_key - Hash key to authenticate yourself in the API.
In addition, the input needs to have the 'license_expression' field.
(Please contact nexB to get the api_* value to use for this feature)
$ about gen --fetch-license 'api_url' 'api_key' LOCATION OUTPUT
--license-notice-text-location
Copy the license files and notice files to the generated location based on the
'license_file' and 'notice_file' value in the input from the directory
For instance,
the directory, /home/licenses_notices/, contains all the licenses and notices that you want:
/home/license/apache2.LICENSE
/home/license/jquery.js.NOTICE
$ about gen --license-notice-text-location /home/licenses_notices/ LOCATION OUTPUT
--mapping
See mapping.config for details
--mapping-file
Same behavior as `--mapping` but with custom mapping file
$ about attrib --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT
--verbose
This option tells the tool to show all errors found.
The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'
inventory¶
Syntax
about inventory [OPTIONS] LOCATION OUTPUT
LOCATION: Path to an ABOUT file or a directory with ABOUT files.
OUTPUT: Path to the JSON or CSV inventory file to create.
Options:
--filter TEXT Filter for the output inventory.
-f, --format [json|csv] Set OUTPUT file format. [default: csv]
--mapping Use file mapping.config to collect the defined not supported fields in ABOUT files.
--mapping-file Use a custom mapping file with mapping between input
keys and ABOUT field names.
--mapping-output FILE Use a custom mapping file with mapping between
ABOUT field names and output keys
--verbose Show all the errors and warning.
-q, --quiet Do not print any error/warning.
-h, --help Show this message and exit.
Purpose¶
Collect a JSON or CSV inventory of components from ABOUT files.
Options¶
-filter TEXT
Filter for the output inventory.
$ about inventory --filter "license_expression=gpl-2.0" LOCATION OUTPUT
The above command will only inventory the ABOUT files which have the "license_expression: gpl-2.0"
-f, --format [json|csv]
Set OUTPUT file format. [default: csv]
$ about inventory -f json LOCATION OUTPUT
--mapping
See mapping.config for details
--mapping-file
Same behavior as `--mapping` but with custom mapping file
$ about inventory --mapping-file CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT
--mapping-output
Same behavior as `--mapping-file` but with custom mapping file
In the custom mapping file, the left side is the custom key name where
the right side is the ABOUT field name. For instance,
Component: name
The "Component" is a custom field name for the output
The "name" is one of the defaul ABOUT field name that user want to convert
$ about inventory --mapping-output CUSTOM_MAPPING_FILE_PATH LOCATION OUTPUT
--verbose
This option tells the tool to show all errors found.
The default behavior will only show 'CRITICAL', 'ERROR', and 'WARNING'
Special Notes¶
Multiple licenses support format¶
The multiple licenses support format for CSV files are separated by line break
about_resource |
name |
license_key |
license_file |
test.tar.xz |
test |
apache-2.0
mit
|
apache-2.0.LICENSE
mit.LICENSE
|
The multiple licenses support format for ABOUT files are by “grouping” with the keyword “licenses”
about_resource: test.tar.xz
name: test
licenses:
- key: apache 2.0
name: apache-2.0.LICENSE
- key: mit
name: mit.LICENSE