feat: Release 4.0.0 #341)

Highlights of this release include:
* Support for De-serialization from JSON and XML to this Pythonic Model
* Deprecation of Python 3.6 support
* Support for Python 3.11
* Support for `BomLink`
* Support VEX without needing `Component` in the same `Bom`
* Support for `services` having `dependencies`

BREAKING CHANGE: Large portions of this library have been re-written for this release and many methods and contracts have changed.

Signed-off-by: Paul Horton <[email protected]>

* feat: support VEX without Components in the same BOM

BREAKING CHANGE: Model classes changed to relocated Vulnerability at Bom, not at Component

Signed-off-by: Paul Horton <[email protected]>

* feat: support VEX without Components in the same BOM

BREAKING CHANGE: Model classes changed to relocated Vulnerability at Bom, not at Component

Signed-off-by: Paul Horton <[email protected]>

feat: allow `version` of BOM to be defined

feat: allow `serial_number` of BOM to be prescribed

feat: add helper method to get URN for a BOM according to https://www.iana.org/assignments/urn-formal/cdx
Signed-off-by: Paul Horton <[email protected]>

* chore: fix release workflow

* chore: editorconfig

Signed-off-by: Jan Kowalleck <[email protected]>

* feat: support for deserialization from JSON and XML (#290)

BREAKING CHANGE:

* feat: drop Python 3.6 support

Signed-off-by: Hakan Dilek <[email protected]>
Signed-off-by: Paul Horton <[email protected]>
Co-authored-by: Hakan Dilek <[email protected]>
Co-authored-by: Hakan Dilek <[email protected]>

* fix: update `serializable` to include XML safety changes

Signed-off-by: Paul Horton <[email protected]>

* feat: Support for Python 3.11 (#349)

* feat: officially test and support Python 3.11

Signed-off-by: Paul Horton <[email protected]>

* removed unused imports

Signed-off-by: Paul Horton <[email protected]>

* bump `poetry` to `1.1.12` in CI

Signed-off-by: Paul Horton <[email protected]>

* fix: remove `toml` as dependency as not used and seems to be breaking Python 3.11 CI

Signed-off-by: Paul Horton <[email protected]>

* fix: removed `types-toml` from dependencies - not used

Signed-off-by: Paul Horton <[email protected]>

---------

Signed-off-by: Paul Horton <[email protected]>

* fix: removed `autopep8` in favour of `flake8` as both have conflicting dependencies now

Signed-off-by: Paul Horton <[email protected]>

* chore: bump dev dependencies

fix: removed `setuptools` as dependency
Signed-off-by: Paul Horton <[email protected]>

* tests: compoennt versions optional (#350)

* chore: exclude `venv*` from QA; add typing to QA

Signed-off-by: Jan Kowalleck <[email protected]>

* tests: component versions are optional

Signed-off-by: Jan Kowalleck <[email protected]>

---------

Signed-off-by: Jan Kowalleck <[email protected]>

* doc: doc updates for new deserialization feature

Signed-off-by: Paul Horton <[email protected]>

* doc: doc updates for contribution

Signed-off-by: Paul Horton <[email protected]>

---------

Signed-off-by: Paul Horton <[email protected]>
Signed-off-by: Jan Kowalleck <[email protected]>
Signed-off-by: Hakan Dilek <[email protected]>
Co-authored-by: Jan Kowalleck <[email protected]>
Co-authored-by: Hakan Dilek <[email protected]>
Co-authored-by: Hakan Dilek <[email protected]>

Author: 3 people

.github/workflows/deploy.yml

@@ -4,9 +4,9 @@ on:
   push:
     branches: [ 'main' ]
   workflow_dispatch:
-  
+
 env:
-  PYTHON_VERSION_DEFAULT: "3.10"
+  PYTHON_VERSION_DEFAULT: "3.11"
   POETRY_VERSION: "1.1.12"
 
 jobs:
@@ -22,14 +22,14 @@ jobs:
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
-          
+
       - name: Setup python
         # see https://github.com/actions/setup-python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION_DEFAULT }}
           architecture: 'x64'
-          
+
       - name: Install and configure Poetry
         # See https://github.com/marketplace/actions/install-poetry-action
         uses: snok/install-poetry@v1
@@ -38,17 +38,17 @@ jobs:
           virtualenvs-create: true
           virtualenvs-in-project: true
           installer-parallel: true
-          
+
       - name: Install dependencies
         run: poetry install --no-root
 
       - name: View poetry version
         run: poetry --version
-        
+
       - name: Python Semantic Release
         # see https://python-semantic-release.readthedocs.io/en/latest/automatic-releases/github-actions.html
         # see https://github.com/relekang/python-semantic-release
-        uses: relekang/[email protected].1
+        uses: relekang/[email protected].2
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           repository_username: __token__

.github/workflows/manual-release-candidate.yml

@@ -25,7 +25,7 @@ jobs:
           python -m pip install poetry --upgrade pip
           poetry config virtualenvs.create false
           poetry install
-          python -m pip install python-semantic-release
+          python -m pip install python-semantic-release==7.28.1
       - name: Apply Pre Release Version
         run: |
           RC_VERSION="$(semantic-release --noop --major print-version)-${{ github.event.inputs.release_candidate_suffix }}"

.github/workflows/poetry.yml

@@ -4,7 +4,7 @@ name: Python CI
 
 on:
   push:
-    branches: ["master", "main"]
+    branches: ["main"]
   pull_request:
     branches-ignore: ['dependabot/**']
   workflow_dispatch:
@@ -15,8 +15,8 @@ on:
 
 env:
   REPORTS_DIR: CI_reports
-  PYTHON_VERISON_DEFAULT: "3.10"
-  POETRY_VERSION: "1.1.11"
+  PYTHON_VERSION_DEFAULT: "3.11"
+  POETRY_VERSION: "1.1.12"
 
 jobs:
   coding-standards:
@@ -27,19 +27,23 @@ jobs:
       - name: Checkout
         # see https://github.com/actions/checkout
         uses: actions/checkout@v3
+
       - name: Setup Python Environment
         # see https://github.com/actions/setup-python
         uses: actions/setup-python@v4
         with:
-          python-version: ${{ env.PYTHON_VERISON_DEFAULT }}
+          python-version: ${{ env.PYTHON_VERSION_DEFAULT }}
           architecture: 'x64'
+
       - name: Install poetry
         # see https://github.com/marketplace/actions/setup-poetry
         uses: Gr1N/setup-poetry@v8
         with:
           poetry-version: ${{ env.POETRY_VERSION }}
+
       - name: Install dependencies
         run: poetry install --no-root
+
       - name: Run tox
         run: poetry run tox -e flake8 -s false
 
@@ -53,96 +57,102 @@ jobs:
         include:
           - # test with the locked dependencies
             os: ubuntu-latest
-            python-version: '3.10'
+            python-version: '3.11'
             toxenv-factor: 'locked'
           - # test with the lowest dependencies
-            os: ubuntu-20.04
-            python-version: '3.6'
+            os: ubuntu-latest
+            python-version: '3.7'
             toxenv-factor: 'lowest'
     steps:
       - name: Checkout
         # see https://github.com/actions/checkout
         uses: actions/checkout@v3
+
       - name: Setup Python Environment
         # see https://github.com/actions/setup-python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           architecture: 'x64'
+
       - name: Install poetry
         # see https://github.com/marketplace/actions/setup-poetry
         uses: Gr1N/setup-poetry@v8
         with:
           poetry-version: ${{ env.POETRY_VERSION }}
+
       - name: Install dependencies
         run: poetry install --no-root
+
       - name: Run tox
         run: poetry run tox -e mypy-${{ matrix.toxenv-factor }} -s false
 
   build-and-test:
     name: Test (${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.toxenv-factor }})
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 10
+    timeout-minutes: 15
     env:
       REPORTS_ARTIFACT: tests-reports
     strategy:
       fail-fast: false
       matrix:
         os: ['ubuntu-latest', 'windows-latest', 'macos-latest']
         python-version:
-          - "3.10" # highest supported
+          - "3.11" # highest supported
+          - "3.10"
           - "3.9"
           - "3.8"
-          - "3.7"
-          - "3.6" # lowest supported
+          - "3.7" # lowest supported
         toxenv-factor: ['locked']
         include:
-          - # test with py36 ubuntu20
-            os: ubuntu-20.04
-            python-version: '3.6'
-            toxenv-factor: 'locked'
           - # test with the lowest dependencies
-            os: ubuntu-20.04
-            python-version: '3.6'
-            toxenv-factor: 'lowest'
-        exclude:
-          - # no py36 with latest ubuntu - see https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json
             os: ubuntu-latest
-            python-version: '3.6'
+            python-version: '3.7'
+            toxenv-factor: 'lowest'
     steps:
       - name: Disabled Git auto EOL CRLF transforms
         run: |
           git config --global core.autocrlf false
           git config --global core.eol lf
+
       - name: Checkout
         # see https://github.com/actions/checkout
         uses: actions/checkout@v3
+
       - name: Create reports directory
         run: mkdir ${{ env.REPORTS_DIR }}
+
       - name: Setup Python Environment
         # see https://github.com/actions/setup-python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           architecture: 'x64'
+
       - name: Validate Python Environment
         run: echo "import sys; print('Python %s on %s in %s' % (sys.version, sys.platform, sys.getdefaultencoding()))" | python
+
       - name: Install poetry
         # see https://github.com/marketplace/actions/setup-poetry
         uses: Gr1N/setup-poetry@v8
         with:
           poetry-version: ${{ env.POETRY_VERSION }}
+
       - name: Install dependencies
         run: poetry install --no-root
+
       - name: Ensure build successful
         run: poetry build
+
       - name: Run tox
         run: poetry run tox -e py-${{ matrix.toxenv-factor }} -s false
+
       - name: Generate coverage reports
         run: >
           poetry run coverage report &&
           poetry run coverage xml -o ${{ env.REPORTS_DIR }}/coverage-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.toxenv-factor }}.xml &&
           poetry run coverage html -d ${{ env.REPORTS_DIR }}
+
       - name: Artifact reports
         if: ${{ ! cancelled() }}
         # see https://github.com/actions/upload-artifact

.isort.cfg

@@ -6,7 +6,7 @@ skip_gitignore = false
 skip_glob =
     build/*,dist/*,__pycache__,.eggs,*.egg-info*,
     *_cache,*.cache,
-    .git/*,.tox/*,.venv/*,venv/*
+    .git/*,.tox/*,.venv/*,venv/*,.venv*/*,venv*/*,
     _OLD/*,_TEST/*,
     docs/*
 combine_as_imports = true
@@ -18,3 +18,4 @@ multi_line_output = 3
 src_paths =
     cyclonedx
     tests
+    typings

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: system
         name: mypy
-        entry: poetry run tox -e mypy
+        entry: poetry run tox -e mypy-locked
         pass_filenames: false
         language: system
   - repo: local
@@ -17,7 +17,7 @@ repos:
   - repo: local
     hooks:
       - id: system
-        name: autopep8
-        entry: poetry run autopep8 --in-place -r cyclonedx tests
+        name: flake8
+        entry: poetry run flake8 cyclonedx/ tests/
         pass_filenames: false
         language: system

CONTRIBUTING.md

@@ -23,7 +23,7 @@ Get it all applied via:
 
 ```shell
 poetry run isort .
-poetry run autopep8 --in-place -r cyclonedx tests
+poetry run flake8 cyclonedx/ tests/ typings/
 ```
 
 ## Documentation

README.md

@@ -13,19 +13,21 @@
 ----
 
 This CycloneDX module for Python can generate valid CycloneDX bill-of-material document containing an aggregate of all
-project dependencies.
+project dependencies. CycloneDX is a lightweight BOM specification that is easily created, human-readable, and simple 
+to parse.
 
-This module is not designed for standalone use.
+**This module is not designed for standalone use.**
 
-If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, why not checkout: [CycloneDX Python][cyclonedx-python]
+As of version `3.0.0`, the internal data model was adjusted to allow CycloneDX VEX documents to be produced as per
+[official examples](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) linking a VEX 
+documents to a separate BOM document.
 
-Additionally, the following tool can be used as well (and this library was written to help improve it) [Jake][jake].
+If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, why not checkout 
+[CycloneDX Python][cyclonedx-python] or [Jake][jake].
 
-Additionally, you can use this module yourself in your application to programmatically generate SBOMs.
+Alternatively, you can use this module yourself in your application to programmatically generate CycloneDX BOMs.
 
-CycloneDX is a lightweight BOM specification that is easily created, human-readable, and simple to parse.
-
-View our documentation [here](https://cyclonedx-python-library.readthedocs.io/).
+View the documentation [here](https://cyclonedx-python-library.readthedocs.io/).
 
 ## Python Support
 

cyclonedx/exception/__init__.py

@@ -21,4 +21,7 @@
 
 
 class CycloneDxException(Exception):
+    """
+    Root exception thrown by this library.
+    """
     pass

cyclonedx/exception/factory.py

@@ -30,16 +30,28 @@ class CycloneDxFactoryException(CycloneDxException):
 
 
 class LicenseChoiceFactoryException(CycloneDxFactoryException):
+    """
+    Base exception that covers all LicenseChoiceFactory exceptions.
+    """
     pass
 
 
 class InvalidSpdxLicenseException(LicenseChoiceFactoryException):
+    """
+    Thrown when an invalid SPDX License is provided.
+    """
     pass
 
 
 class LicenseFactoryException(CycloneDxFactoryException):
+    """
+    Base exception that covers all LicenseFactory exceptions.
+    """
     pass
 
 
 class InvalidLicenseExpressionException(LicenseFactoryException):
+    """
+    Thrown when an invalid License expressions is provided.
+    """
     pass

cyclonedx/exception/output.py

@@ -22,6 +22,13 @@
 from . import CycloneDxException
 
 
+class BomGenerationErrorException(CycloneDxException):
+    """
+    Raised if there is an unknown error.
+    """
+    pass
+
+
 class FormatNotSupportedException(CycloneDxException):
     """
     Exception raised when attempting to output a BOM to a format not supported in the requested version.