opossum-file

This is a library implementing operations around files readable by OpossumUI.

Current state

Supports the conversion from the following file format to .opossum:

• .opossum itself
• ScanCode (json)
• more to come...

License

Apache-2.0

Installation

You find the latest release here. We offer prebuilt binaries for Linux, MacOS and Windows.

Alternatively, or to get the cutting-edge version, you can clone the repository and run the code yourself. See Development below for installation instructions.

How to use

Command-line usage

The CLI uses subcommands. The main command just displays all available subcommands

Usage: opossum-file [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  generate  Generate an Opossum file from various other file formats.

generate

Usage: opossum-file generate [OPTIONS]

  Generate an Opossum file from various other file formats.

  Currently supported input formats:
    - ScanCode
    - Opossum

Options:
  --opossum PATH         Specify a path to a .opossum file that you would like
                         to include in the final output. Option can be
                         repeated.
  --scan-code-json PATH  Specify a path to a .json file generated by ScanCode
                         that you would like to include in the final output.
                         Option can be repeated.
  -o, --outfile TEXT     The file path to write the generated opossum document
                         to. If appropriate, the extension ".opossum" is
                         appended. If the output file already exists, it is
                         overwritten.  [default: output.opossum]
  --help                 Show this message and exit.

Development

Installation

This package uses uv for installation and dependency management. After installing uv and cloning the repository, you can set up the project with

uv sync

Execution

To execute the code directly (i.e. without building it), use

uv run opossum-file generate ...

Code quality tooling

To lint and test your changes, run

uv run ruff check
uv run ruff format --check
uv run python -m mypy src/ tests/
uv run pytest
uv run lint-imports

Each PR is required to pass these checks, so it is a good a idea to run these commands locally before submitting your PR.

Note:
This project uses faker for testing. By default, every test runs with a different seed. To fix the seed, just adapt the line in faker_setup.py (without committing).

Build

To build, run

uv run python build.py opossum-file

This will create a self-contained executable file dist/opossum-file (dist/opossum-file.exe on Windows).

Creating a new release

Note: You will need the "maintain" role in order to create a new release.

1. Go to the GitHub releases page and use the UI to create a new release.
2. The tag should have the format "opossum-file-$YEAR-$MONTH-$DAY" (in case of an Nth release on the same day "opossum-file-$YEAR-$MONTH-$DAY.N").
3. The title of the release equals the tag.
4. Click the button "Generate release notes" to get the description for the release. Then, remove all the contributions from @renovate which are just dependency upgrades.
5. Click "Publish release". This will trigger the CI/CD pipeline which will build the release for all three OSs and upload the artifacts to the release.