A simple wrapper for the Fossology REST API.

See the OpenAPI specification used to implement this library.

Current release is compatible with Fossology version 4.4.0 - API version 1.6.1 (not all endpoints are supported)

See release notes for all details.

If you miss an API Endpoint, please open a new issue or contribute a pull request.

API v2 is partially supported too, however the specification is not stable yet and not all endpoints are supported.

Documentation

See fossology-python on Github Pages.

Usage

Installation

This project is available as Python package on PyPi.org.

• Install fossology and required dependencies:

  pip install fossology requests

Using the API

• Get a REST API token either from the Fossology server under ``User->Edit user account`` or generate a token using the method available in this library:

  from fossology import fossology_token
  from fossology.enum import TokenScope
  
  FOSSOLOGY_SERVER = "https://fossology.example.com/repo" # Note the absence of the trailing slash, otherwise the token generation will fail
  FOSSOLOGY_USER = "fossy"
  FOSSOLOGY_PASSWORD = "fossy"
  TOKEN_NAME = "fossy_token"
  
  # By default version v1 of the token generation API will be used
  token = fossology_token(
        FOSSOLOGY_SERVER,
        FOSSOLOGY_USER,
        FOSSOLOGY_PASSWORD,
        TOKEN_NAME,
        TokenScope.WRITE
        version="v1"
  )

• Start using the API:

  from fossology import Fossology
  
  # By default version v1 of the API will be used
  foss = Fossology(FOSSOLOGY_SERVER, token, FOSSOLOGY_USER, version="v1")
  print(f"Logged in as user {foss.user.name}")

Using the CLI

Fossology Python also offers a command line interface to simplify interactions with your Fossology server.

• To get a list of available commands, run:

  $ foss_cli --help
  Usage: foss_cli [OPTIONS] COMMAND [ARGS]...

• Generate a configuration file:

  $ foss_cli config
  Enter the URL to your Fossology server: e.g. http://fossology/repo
  Fossology URL: http://fossology/repo
  Enter Username and Password: e.g. fossy/fossy (in the default environment)
  Username: fossy
  Password:
  Enter a scope for your Fossology token: either 'read' or 'write'
  Token scope: write

  This will get a token from Fossology server and store it within the local .foss_cli.ini file.

  On subsequent foss_cli calls those values will be reused.

  Re-run the config command to create a new token once it expired.

• Verbosity of all foss_cli commands could be increased using the -v verbosity option:

  $ foss_cli -vv [COMMAND]

  This runs the given command with verbosity level 2 (all debug statements will be logged).

  A log file in directory .foss_cli_results named .foss_cli.log will be created.

• To create a group:

  $ foss_cli -vv create_group FossGroup

• To create a a folder:

  $ foss_cli -vv create_folder FossFolder \
     --folder_group FossGroup \
     --folder_description "Description of FossFolder"

• To upload a file:

  $ foss_cli -vv upload_file tests/files/zlib_1.2.11.dfsg-0ubuntu2.debian.tar.xz \
        --folder_name FossFolder
        --access_level public

• To upload a source package to the server and initialize a scan workflow including report generation:

  $ foss_cli -vv start_workflow --help
  Usage: foss_cli start_workflow [OPTIONS] FILE_NAME
  The foss_cli start_workflow command.
  Options:
        --folder_name TEXT            The name of the folder to upload to.
        --file_description TEXT       The description of the upload.
        --dry_run / --no_dry_run      Do not upload but show what would be done.
                                      Use -vv to see output.
        --reuse_newest_upload / --no_reuse_newest_upload
                                      Reuse newest upload if available.
        --reuse_newest_job / --no_reuse_newest_job
                                      Reuse newest scheduled job for the upload if
                                      available.
        --report_format TEXT          The name of the reportformat. [dep5,
                                      spdx2,spdxtv,readmeoss,unifiedreport]
        --access_level TEXT           The access level of the
                                      upload.[private,protected,public]
        --help                        Show this message and exit.

Contribute

Develop

• All contributions in form of bug reports, feature requests or merge requests!
• Use proper docstrings to document functions and classes
• Extend the testsuite poetry run pytest with the new functions/classes
• The documentation website can automatically be generated by the Sphinx autodoc extension

HINT

To avoid running the whole testsuite during development of a new branch with changing only touching the code related to the CLI, name your branch feat/cli-{something} and only the test_foss_cli_* will run in the pull request context.

Build

• You can build the PyPi package using poetry:

  poetry build

• Build documentation:

  The static site is generated automatically by GitHub Actions on every merge to main branch and pushed to gh-pages branch. The action uses JamesIves/github-pages-deploy-action to deploy the static pages.

  To build it locally

  poetry run sphinx-build -b html docs-source docs/

• Cleanup builds:

  rm -r dist/ docs/

Tag

Each new release gets a new tag with important information about the changes added to the new release:

git tag -a vx.x.x -m "New major/minor/patch release x.x.x"
git push origin vx.x.x

Add required information in the corresponding release in the Github project.

Publish

Publish the newest release to PyPi (visit https://pypi.org/manage/account/#api-tokens to get the token):

poetry publish --build --username __token__ --password $PYPI_TOKEN

Test

The testsuite available in this project expects a running Fossology instance under the hostname fossology with the default admin user "fossy".

• Use the latest Fossology container from Docker hub:

  docker pull fossology/fossology
  tar xJf tests/files/base-files_11.tar.xz -C /tmp
  docker run --mount src="/tmp",dst=/tmp,type=bind --name fossology -p 80:80 fossology/fossology

• Start the complete test suite or a specific test case (and generate coverage report):

  poetry run coverage run --source=fossology -m pytest
  poetry run coverage report -m
  poetry run coverage html