Merge branch 'main' into main

Author: pombredanne

.github/workflows/generate-index-and-docs.yml

@@ -0,0 +1,45 @@
+name: Check and generate PURL Type Docs and Index
+
+on:
+  push:
+    paths:
+      - "types/*.json"
+      - "schemas/*.json"
+      - "etc/"
+    branches:
+      - main
+  workflow_dispatch:
+# All permissions should be specified at the job level
+permissions: { }
+
+jobs:
+  generate-index-and-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      content: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: make conf
+
+      - name: Validate code and data formats
+        run: make check
+
+      - name: Generate index and docs
+        run: make gendocs
+
+      - name: Commit and push changes
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git add types/ types-doc/
+          git commit -s -m "Generate updated PURL type documentation" || echo "No changes to commit"
+          git push

.gitignore

@@ -1 +1,4 @@
 /tmp/
+/venv/
+/.python-version
+.ruff_cache/

Makefile

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) the purl authors
+# Visit https://github.com/package-url/purl-spec and https://packageurl.org for support
+
+PYTHON_EXE?=python3
+VENV_LOCATION=venv
+ACTIVATE?=. ${VENV_LOCATION}/bin/activate;
+
+CODEGEN?=datamodel-codegen \
+    --target-python-version 3.10 \
+    --use-double-quotes \
+    --use-exact-imports \
+    --use-standard-collections \
+    --wrap-string-literal \
+    --enum-field-as-literal all \
+    --formatters ruff-format \
+    --field-constraints \
+    --disable-timestamp \
+    --keep-model-order \
+    --custom-file-header-path LICENSE \
+    --input-file-type jsonschema \
+    --output-model-type pydantic_v2.BaseModel
+
+virtualenv:
+	@echo "-> Bootstrap the virtualenv with PYTHON_EXE=${PYTHON_EXE}"
+	${PYTHON_EXE} -m venv ${VENV_LOCATION}
+
+conf: virtualenv
+	@echo "-> Install dependencies"
+	@${ACTIVATE} pip install -r etc/scripts/requirements.txt
+
+formatcode:
+	@echo "-> Run Ruff format"
+	@${ACTIVATE} ruff check --select I --fix
+	@${ACTIVATE} ruff format
+	@echo "-> Run Ruff linter"
+	@${ACTIVATE} ruff check --fix
+
+formatjson:
+	@echo "-> Format JSON files"
+	@${ACTIVATE} python etc/scripts/format_json.py schemas/
+	@${ACTIVATE} python etc/scripts/format_json.py types/
+	@${ACTIVATE} python etc/scripts/format_json.py tests/
+
+format: formatcode formatjson
+	@echo "-> Format all files"
+
+checkjson:
+	@echo "-> Validate JSON schemas"
+	@${ACTIVATE} check-jsonschema --check-metaschema --verbose schemas/*.json
+	@echo "-> Validate JSON data files against the schemas"
+	@${ACTIVATE} check-jsonschema --schemafile schemas/purl-types-index.schema.json --verbose purl-types-index.json
+	@${ACTIVATE} check-jsonschema --schemafile schemas/purl-type-definition.schema.json --verbose types/*-definition.json
+	@${ACTIVATE} check-jsonschema --schemafile schemas/purl-test.schema.json --verbose tests/*/*-test.json
+
+checkcode:
+	@echo "-> Run Ruff linter validation (pycodestyle, bandit, isort, and more)"
+	@${ACTIVATE} ruff --config etc/scripts/pyproject.toml check
+	@echo "-> Run Ruff format validation"
+	@${ACTIVATE} ruff --config etc/scripts/pyproject.toml format --check
+
+check: checkjson checkcode
+	@echo "-> Run all checks"
+
+clean:
+	@echo "-> Clean the Python env"
+	rm -rf .venv/
+	find . -type f -name '*.py[co]' -delete
+
+gencode:
+	@echo "-> Generate Python code from schemas"
+	@${ACTIVATE} ${CODEGEN} \
+	    --input schemas/purl-types-index.schema.json \
+	    --output etc/scripts/purl_types_index.py
+	@${ACTIVATE} ${CODEGEN} \
+	    --input schemas/purl-type-definition.schema.json \
+	    --output etc/scripts/purl_type_definition.py
+	@${ACTIVATE} ${CODEGEN} \
+	    --input schemas/purl-test.schema.json \
+	    --output etc/scripts/purl_test.py
+	@echo "-> Run Black format for generated code"
+	@${ACTIVATE} black -l 100 --preview --enable-unstable-feature string_processing etc/scripts/*.py
+
+gendocs:
+	@${ACTIVATE} python etc/scripts/generate_index_and_docs.py
+
+
+.PHONY: virtualenv conf formatcode formatjson format checkcode checkjson check clean gencode gendocs

PURL-SPECIFICATION.rst

@@ -116,9 +116,10 @@ A ``purl`` string is an ASCII URL string composed of seven components.
 
 Except as expressly stated otherwise in this section, each component:
 
-- MAY be composed of any of the characters defined in the "Permitted
-  characters" section
-- MUST be encoded as defined in the "Character encoding" section
+- MAY be composed of any of the characters defined in the "`Permitted characters`_" section
+- MUST be encoded as defined in the "`Character encoding`_" section
+
+The "lowercase" rules are defined in the "`Case folding`_" section.
 
 The rules for each component are:
 
@@ -134,7 +135,7 @@ The rules for each component are:
 - **type**:
 
   - The package ``type`` MUST be composed only of ASCII letters and numbers,
-    period '.', plus '+', and dash '-'.
+    period '.', and dash '-'.
   - The ``type`` MUST start with an ASCII letter.
   - The ``type`` MUST NOT be percent-encoded.
   - The ``type`` is case insensitive. The canonical form is lowercase.
@@ -168,7 +169,7 @@ The rules for each component are:
     stripped in the canonical form. They are not part of the ``name``.
   - A ``name`` MUST be a percent-encoded string.
   - When percent-decoded, a ``name`` MAY contain any Unicode character unless
-    prohibited by the package's ``type`` definition in `<PURL-TYPES.rst>`_.
+    the package's ``type`` definition provides otherwise.
 
 
 - **version**:
@@ -205,7 +206,7 @@ The rules for each component are:
     - A ``key`` MUST NOT be percent-encoded.
     - Each ``key`` MUST be unique among all the keys of the ``qualifiers``
       component.
-    - A ``value`` MAY be composed of any character and all characters MUST be
+    - A ``value`` MAY contain any Unicode character and all characters MUST be
       encoded as described in the "Character encoding" section.
 
 
@@ -219,9 +220,11 @@ The rules for each component are:
   - Each ``subpath`` segment MUST be a percent-encoded string
   - When percent-decoded, a segment:
 
-    - MUST NOT contain a '/'
-    - MUST NOT be any of '..' or '.'
+    - MUST NOT contain any slash '/' characters
     - MUST NOT be empty
+    - MUST NOT be any of '..' or '.'
+    - MAY contain any Unicode character other than '/' unless the package's
+      ``type`` definition provides otherwise.
 
   - The ``subpath`` MUST be interpreted as relative to the root of the package
 
@@ -234,7 +237,6 @@ A canonical ``purl`` is composed of these permitted ASCII characters:
 - the Alphanumeric Characters: ``A to Z``, ``a to z``, ``0 to 9``,
 - the Punctuation Characters: ``.-_~`` (period '.',
   dash '-', underscore '_' and tilde '~'),
-- the Plus Character: ``+`` (plus '+'),
 - the Percent Character: ``%`` (percent sign '%'), and
 - the Separator Characters ``:/@?=&#`` (colon ':', slash '/', at sign '@',
   question mark '?', equal sign '=', ampersand '&' and pound sign '#').
@@ -286,6 +288,16 @@ Character encoding
 - With the exception of the percent-encoding mechanism, the rules regarding
   percent-encoding are defined by this specification alone.
 
+Case folding
+~~~~~~~~~~~~
+
+References to "lowercase" in this specification refer to the **culture-invariant**
+full case mapping defined in
+`Section 3.13.2 of the Unicode Standard <https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G34078>`_.
+
+When applied to the ASCII character set, this operation converts uppercase
+Latin letters (``A to Z``) to their corresponding lowercase forms (``a to z``).
+All other ASCII characters remain unchanged.
 
 How to build ``purl`` string from its components
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -340,7 +352,7 @@ To build a ``purl`` string from its components:
 
     - Discard any pair where the ``value`` is empty.
     - UTF-8-encode each ``value`` if needed in your programming language
-    - If the ``key`` is ``checksums`` and this is a list of ``checksums`` join this
+    - If the ``key`` is ``checksum`` and this is a list of checksums join this
       list with a ',' to create this qualifier ``value``
     - Create a string by joining the lowercased ``key``, the equal '=' sign and
       the percent-encoded ``value`` to create a qualifier
@@ -396,8 +408,8 @@ To parse a ``purl`` string in its components:
     - The ``value`` is the percent-decoded right side
     - UTF-8-decode the ``value`` if needed in your programming language
     - Discard any key/value pairs where the value is empty
-    - If the ``key`` is ``checksums``, split the ``value`` on ',' to create
-      a list of ``checksums``
+    - If the ``key`` is ``checksum``, split the ``value`` on ',' to create
+      a list of checksums
 
   - This list of key/value is the ``qualifiers`` object
 
@@ -463,6 +475,13 @@ download URL, VCS URL or checksums in an API, database or web form.
 With this warning, the known ``key`` and ``value`` defined here are valid for use in
 all package types:
 
+- ``vers`` allows the specification of a version range.
+  The value MUST adhere to the `Version Range Specification <VERSION-RANGE-SPEC.rst>`_.
+  This qualifier is mutually exclusive with the ``version`` component.
+  For example::
+
+       pkg:pypi/django?vers=vers:pypi%2F%3E%3D1.11.0%7C%21%3D1.11.1%7C%3C2.0.0
+
 - ``repository_url`` is an extra URL for an alternative, non-default package
   repository or registry. When a package does not come from the default public
   package repository for its ``type`` a ``purl`` may be qualified with this extra