Skip to content

fossology/fossology-python

Repository files navigation

License PyPI Version Python Version Downloads Static Checks Fossology Tests Coverage

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.

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