Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fossology/fossology-python

Python wrapper for the Fossology API
https://github.com/fossology/fossology-python

automation fossology oss-clearing

Last synced: 3 months ago
JSON representation

Python wrapper for the Fossology API

Awesome Lists containing this project

README 

          
|License| |PyPI Version| |Python Version| |Downloads| |Static Checks| |Fossology Tests| |Coverage|



.. |License| image:: https://img.shields.io/badge/license-MIT-blue.svg

   :target: https://github.com/fossology/fossology-python/blob/main/LICENSE.md



.. |PyPI Version| image:: https://badge.fury.io/py/fossology.svg

   :target: https://pypi.org/project/fossology



.. |Python Version| image:: https://img.shields.io/badge/python-3.11%2C3.12-blue?logo=python

   :target: https://www.python.org/doc/versions/



.. |Downloads| image:: https://static.pepy.tech/badge/fossology

   :target: https://pepy.tech/project/fossology



.. |Static Checks| image:: https://github.com/deveaud-m/fossology-python/workflows/Static%20Checks/badge.svg

   :target: https://github.com/deveaud-m/fossology-python/actions?query=workflow%3A%22Static+Checks%22



.. |Fossology Tests| image:: https://github.com/deveaud-m/fossology-python/workflows/API%20Tests/badge.svg

   :target: https://github.com/deveaud-m/fossology-python/actions?query=workflow%3A%22API+Tests%22



.. |Coverage| image:: https://codecov.io/gh/fossology/fossology-python/branch/master/graph/badge.svg

   :target: https://codecov.io/gh/fossology/fossology-python

   



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:



   .. code:: shell



      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:



   .. code:: python



      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:



   .. code:: python



      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:



   .. code:: bash



      $ foss_cli --help

      Usage: foss_cli [OPTIONS] COMMAND [ARGS]...



- Generate a configuration file:



   .. code:: bash



      $ 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:



   .. code:: bash



      $ 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:



   .. code:: bash



      $ foss_cli -vv create_group FossGroup



- To create a a folder:



   .. code:: bash



      $ foss_cli -vv create_folder FossFolder \

         --folder_group FossGroup \

         --folder_description "Description of FossFolder"



- To upload a file:



   .. code:: bash



      $ 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:



   .. code:: bash



      $ 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,

                                          clixml,spdx3json,spdx3rdf,spdx3jsonld]

            --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 `_:



  .. code:: shell



    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



  .. code:: shell



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



- Cleanup builds:



  .. code:: shell



     rm -r dist/ docs/



Tag

---



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



.. code:: shell



   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):



.. code:: shell



   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 `_:



  .. code:: shell



    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):



  .. code:: shell



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

     poetry run coverage report -m

     poetry run coverage html