feat(package_config): Add classes for config package_configurations

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "python-ort"
-version = "0.3.1"
+version = "0.4.0"
 description = "A Python Ort model serialization library"
 readme = "README.md"
 license = "MIT"

schemas/repository-configuration-schema.json

@@ -796,7 +796,7 @@
         "vcs": {
           "anyOf": [
             {
-              "$ref": "#/$defs/VcsInfo"
+              "$ref": "#/$defs/VcsInfoCurationData"
             },
             {
               "type": "null"
@@ -1263,49 +1263,72 @@
       "title": "Sw360Configuration",
       "type": "object"
     },
-    "VcsInfo": {
+    "VcsInfoCurationData": {
       "description": "Bundles general Version Control System information.\n\nAttributes:\n    type(VcsType): The type of the VCS, for example Git, GitRepo, Mercurial, etc.\n    url(AnyUrl): The URL to the VCS repository.\n    revision(str): The VCS-specific revision (tag, branch, SHA1) that the version of the package maps to.\n    path(str): The path inside the VCS to take into account.\n        If the VCS supports checking out only a subdirectory, only this path is checked out.",
       "properties": {
         "type": {
-          "$ref": "#/$defs/VcsType",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/VcsType"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
           "description": "The type of the VCS, for example Git, GitRepo, Mercurial, etc."
         },
         "url": {
+          "anyOf": [
+            {
+              "format": "uri",
+              "minLength": 1,
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
           "description": "The URL to the VCS repository.",
-          "format": "uri",
-          "minLength": 1,
-          "title": "Url",
-          "type": "string"
+          "title": "Url"
         },
         "revision": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
           "description": "The VCS-specific revision (tag, branch, SHA1) that the version of the package maps to.",
-          "title": "Revision",
-          "type": "string"
+          "title": "Revision"
         },
         "path": {
-          "default": "",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
           "description": "The path inside the VCS to take into account.If the VCS supports checking out only a subdirectory, only this path is checked out.",
-          "title": "Path",
-          "type": "string"
+          "title": "Path"
         }
       },
-      "required": [
-        "url",
-        "revision"
-      ],
-      "title": "VcsInfo",
+      "title": "VcsInfoCurationData",
       "type": "object"
     },
     "VcsType": {
-      "description": "A class for Version Control System types. Each type has one or more [aliases] associated to it,\nwhere the first alias is the definite name. This class is not implemented as an enum as\nconstructing from an unknown type should be supported while maintaining that type as the primary\nalias for the string representation.\n\nAttributes:\n    aliases(list[str]): Primary name and aliases",
+      "description": "A class for Version Control System types. Each type has one or more [aliases] associated to it,\nwhere the first alias is the definite name. This class is not implemented as an enum as\nconstructing from an unknown type should be supported while maintaining that type as the primary\nalias for the string representation.\n\nAttributes:\n    name(str): Primary name and aliases",
       "properties": {
-        "aliases": {
-          "description": "Primary name and aliases",
-          "items": {
-            "type": "string"
-          },
-          "title": "Aliases",
-          "type": "array"
+        "name": {
+          "title": "Name",
+          "type": "string"
         }
       },
       "title": "VcsType",

src/ort/__init__.py

@@ -2,18 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 
-from ort.models.analyzer_configurations import OrtAnalyzerConfigurations
-from ort.models.ort_configuration import OrtConfiguration, Scanner, Severity, Storages
-from ort.models.package_managers import OrtPackageManagerConfigurations, OrtPackageManagers
 from ort.models.repository_configuration import OrtRepositoryConfiguration
 
 __all__ = [
-    "OrtAnalyzerConfigurations",
-    "OrtConfiguration",
-    "OrtPackageManagerConfigurations",
-    "OrtPackageManagers",
     "OrtRepositoryConfiguration",
-    "Scanner",
-    "Severity",
-    "Storages",
 ]

src/ort/models/config/analyzer_configuration.py

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.config.package_manager_configuration import PackageManagerConfiguration
+
+_package_managers: list[str] = [
+    "Bazel",
+    "Bower",
+    "Bundler",
+    "Cargo",
+    "Carthage",
+    "CocoaPods",
+    "Composer",
+    "Conan",
+    "GoMod",
+    "GradleInspector",
+    "Maven",
+    "NPM",
+    "NuGet",
+    "PIP",
+    "Pipenv",
+    "PNPM",
+    "Poetry",
+    "Pub",
+    "SBT",
+    "SpdxDocumentFile",
+    "Stack",
+    "SwiftPM",
+    "Tycho",
+    "Unmanaged",
+    "Yarn",
+    "Yarn2",
+]
+
+
+class AnalyzerConfiguration(BaseModel):
+    """
+    Enable the analysis of projects that use version ranges to declare their dependencies. If set to true,
+    dependencies of exactly the same project might change with another scan done at a later time if any of the
+    (transitive) dependencies are declared using version ranges and a new version of such a dependency was
+    published in the meantime. If set to false, analysis of projects that use version ranges will fail. Defaults to
+    false.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    allow_dynamic_versions: bool = Field(
+        default=False,
+        description="Enable the analysis of projects that use version ranges to declare their dependencies."
+        "If set to true, dependencies of exactly the same project might change with another scan done at a later time"
+        "if any of the (transitive) dependencies are declared using version ranges and a new version of such a"
+        "dependency was published in the meantime. If set to false, analysis of projects that use version ranges will"
+        "fail. Defaults to false.",
+    )
+    enabled_package_managers: list[str] = Field(
+        default=_package_managers,
+        description="A list of the case-insensitive names of package managers that are enabled."
+        "Disabling a package manager in [disabledPackageManagers] overrides enabling it here.",
+    )
+    disabled_package_managers: list[str] | None = Field(
+        default=None,
+        description="A list of the case-insensitive names of package managers that are disabled."
+        "Disabling a package manager in this list overrides [enabledPackageManagers].",
+    )
+    package_managers: dict[str, PackageManagerConfiguration] | None = Field(
+        default=None,
+        description="Get a [PackageManagerConfiguration] from [packageManagers]. The difference to accessing the map"
+        "directly is that [packageManager] can be case-insensitive.",
+    )
+    skip_excluded: bool = Field(
+        default=False,
+        description="A flag to control whether excluded scopes and paths should be skipped during the analysis.",
+    )

src/ort/models/config/license_finding_curation.py

@@ -2,7 +2,9 @@
 # SPDX-License-Identifier: MIT
 
 
-from pydantic import BaseModel, ConfigDict, Field
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from ort.models.config.license_finding_curation_reason import LicenseFindingCurationReason
 
@@ -59,3 +61,17 @@ class LicenseFindingCuration(BaseModel):
         default=None,
         description="A comment explaining this [LicenseFindingCuration].",
     )
+
+    @field_validator("start_lines", mode="before")
+    @classmethod
+    def parse_start_lines(cls, value: Any) -> list[int] | None:
+        if value is None or value == "":
+            return None
+        if isinstance(value, str):
+            # CSV style split
+            return [int(x.strip()) for x in value.split(",") if x.strip()]
+        if isinstance(value, list):
+            return [int(x) for x in value]
+        if isinstance(value, int):
+            return [value]
+        raise ValueError("start_lines must be a comma-separated string or a list of integers")

src/ort/models/config/package_configuration.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.config.license_finding_curation import LicenseFindingCuration
+from ort.models.config.path_exclude import PathExclude
+from ort.models.config.vcsmatcher import VcsMatcher
+from ort.models.identifier import Identifier
+from ort.models.source_code_origin import SourceCodeOrigin
+
+
+class PackageConfiguration(BaseModel):
+    """
+    A class used in the [OrtConfiguration] to configure [PathExclude]s and [LicenseFindingCuration]s for a specific
+    [Package]'s [Identifier] (and [Provenance]).
+    Note that [PathExclude]s and [LicenseFindingCuration]s for [Project]s are configured by a
+    [RepositoryConfiguration]'s excludes and curations properties instead.
+
+    Attributes:
+        id (Identifier): The [Identifier] which must match with the identifier of the package in
+            order for this package curation to apply. The [version][Identifier.version] can be
+            either a plain version string matched for equality, or an Ivy-style version matchers.
+            * The other components of the [identifier][id] are matched by equality.
+        source_artifact_url (str | None): The source artifact this configuration applies to.
+        vcs (VcsMatcher | None): The vcs and revision this configuration applies to.
+        source_code_origin (SourceCodeOrigin | None): The source code origin this configuration
+            applies to.
+        path_excludes (list[PathExclude]): Path excludes.
+        license_finding_curations (list[LicenseFindingCuration]): License finding curations.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    id: Identifier = Field(
+        description="The [Identifier] which must match with the identifier of the package in order for this package"
+        "curation to apply. The [version][Identifier.version] can be either a plain version string matched for"
+        "equality, or an Ivy-style version matchers."
+        "* The other components of the [identifier][id] are matched by equality.",
+    )
+
+    source_artifact_url: str | None = Field(
+        default=None,
+        description="The source artifact this configuration applies to.",
+    )
+
+    vcs: VcsMatcher | None = Field(
+        default=None,
+        description="The vcs and revision this configuration applies to.",
+    )
+
+    source_code_origin: SourceCodeOrigin | None = Field(
+        default=None,
+        description="The source code origin this configuration applies to.",
+    )
+
+    path_excludes: list[PathExclude] = Field(
+        default_factory=list,
+        description="Path excludes.",
+    )
+
+    license_finding_curations: list[LicenseFindingCuration] = Field(
+        default_factory=list,
+        description="License finding curations.",
+    )

src/ort/models/config/package_manager_configuration.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PackageManagerConfiguration(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    must_run_after: list[str] | None = Field(
+        default=None,
+        description="The configuration model for a package manager. This class is (de-)serialized in the following"
+        "places:"
+        "- Deserialized from config.yml as part of [OrtConfiguration] (via Hoplite)."
+        "- Deserialized from .ort.yml as part of [RepositoryAnalyzerConfiguration] (via Jackson)"
+        "- (De-)Serialized as part of [org.ossreviewtoolkit.model.OrtResult] (via Jackson).",
+    )
+
+    options: dict[str, str] | None = Field(
+        default=None,
+        description="Custom configuration options for the package manager. See the documentation of the respective"
+        "class for available options.",
+    )