|Static Checks Action| |Fossology Tests Action|

.. |Static Checks Action| 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 Action| image:: https://github.com/deveaud-m/fossology-python/workflows/Fossology%20Tests/badge.svg
   :target: https://github.com/deveaud-m/fossology-python/actions?query=workflow%3A%22Fossology+Tests%22

A simple wrapper for the Fossology REST API.

See `the OpenAPI specification <https://raw.githubusercontent.com/fossology/fossology/master/src/www/ui/api/documentation/openapi.yaml>`_ used to implement this library.

   Compatible with API version 1.0.7

Usage
=====

Installation
------------

   This project is available as `Python package on PyPi.org <https://pypi.org/project/fossology/>`_

-  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.obj import TokenScope

      FOSSOLOGY_SERVER = "https://fossology.example.com/"
      FOSSOLOGY_USER = "fossy"
      FOSSOLOGY_PASSWORD = "fossy"
      TOKEN_NAME = "fossy_token"

      token = fossology_token(
            FOSSOLOGY_SERVER,
            FOSSOLOGY_USER,
            FOSSOLOGY_PASSWORD,
            TOKEN_NAME,
            TokenScope.WRITE
      )

-  Start using the API:

   .. code:: python

      from fossology import Fossology

      foss = Fossology(
            FOSSOLOGY_SERVER,
            token,
            FOSSOLOGY_USER
      )


Contribute
==========

Develop
-------

-  All contributions in form of bug reports, feature requests or merge requests!

-  Use proper
   `docstrings <https://realpython.com/documenting-python-code/>`__ to
   document functions and classes

-  Don't forget to extend the minimal `testsuite <test.py>`_ with the
   new functions/classes

-  The **documentation website** can automatically be generated by the `Sphinx autodoc
   extension <http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_


Build
-----

- You can build the PyPi package using `poetry <https://poetry.eustace.io/>`_:

  .. code:: shell

    poetry build

- Build documentation:

  .. code:: shell

     poetry run sphinx-build docs-source docs/

- Cleanup builds:

  .. code:: shell

     rm -r dist/ build/ docs/


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 <https://hub.docker.com/r/fossology/fossology>`_:

  .. code:: shell

    docker pull fossology/fossology
    docker run --name fossology -p 80:80 fossology/fossology

- Start the complete test suite or a specific test case:

  .. code:: shell

     poetry run python tests/tests.py
     poetry run python tests/test_uploads.py