Skip to main content

A library to automate Fossology from Python scripts

Project description

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.

Publish

Publish the newest release to PyPi:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fossology-3.3.0.tar.gz (38.0 kB view details)

Uploaded Source

Built Distribution

fossology-3.3.0-py3-none-any.whl (44.4 kB view details)

Uploaded Python 3

File details

Details for the file fossology-3.3.0.tar.gz.

File metadata

  • Download URL: fossology-3.3.0.tar.gz
  • Upload date:
  • Size: 38.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.0.1 CPython/3.12.3 Linux/6.8.0-51-generic

File hashes

Hashes for fossology-3.3.0.tar.gz
Algorithm Hash digest
SHA256 a7bdbda25c26613b877e116117ec06130ac1c64c8605b9a74824050285a5e253
MD5 c275e42fce659460134262acf6e28809
BLAKE2b-256 7894c195de82945e5b52eddde0d560870325412a22025353381279e4a00dc8d8

See more details on using hashes here.

File details

Details for the file fossology-3.3.0-py3-none-any.whl.

File metadata

  • Download URL: fossology-3.3.0-py3-none-any.whl
  • Upload date:
  • Size: 44.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.0.1 CPython/3.12.3 Linux/6.8.0-51-generic

File hashes

Hashes for fossology-3.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5fb13967e081d067e17eba33e3411a21391c552278330b4edc7b36f333146de0
MD5 5cc1ba58a666035f47a49469ef743a34
BLAKE2b-256 c63d48c3f3176ebf3d69603239b5922a315a8adae02c862d5142ae01ceb07467

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page