Add code

.github/workflows/docs-ci.yml

@@ -13,10 +13,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
 

.github/workflows/main.yml

@@ -0,0 +1,32 @@
+name: run tests
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+
+    strategy:
+      max-parallel: 4
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: make dev
+
+      - name: Validate code format
+        run: make check
+
+      - name: Run tests
+        run: make test

.github/workflows/pypi-release.yml

@@ -24,9 +24,11 @@ jobs:
     runs-on: ubuntu-24.04
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: 3.12
 

CHANGELOG.rst

@@ -1,8 +1,9 @@
 Changelog
-=========
+=============
 
 
-v0.0.0
-------
+v0.1.0 (October 20, 2025)
+---------------------------
 
-*xxxx-xx-xx* -- Initial release.
+- Initial release of the ``aboutcode.federated`` library based on
+  original work in the ``aboutcode.hashid`` library.

README.rst

@@ -1,107 +1,69 @@
-A Simple Python Project Skeleton
-================================
+aboutcode.federated
+===================
 
-This repo attempts to standardize the structure of the Python-based project's
-repositories using modern Python packaging and configuration techniques.
-Using this `blog post`_ as inspiration, this repository serves as the base for
-all new Python projects and is mergeable in existing repositories as well.
+This is a library of utilities to compute ids and file paths for AboutCode
+federated data based on Package URL
 
-.. _blog post: https://blog.jaraco.com/a-project-skeleton-for-python-projects/
 
+Federated data utilities goal is to handle content-defined and hash-addressable
+Package data keyed by PURL stored in many Git repositories. This approach to
+federate decentralized data is called FederatedCode.
 
-Usage
-=====
 
-A brand new project
--------------------
+Overview
+========
 
-.. code-block:: bash
+The main design elements for these utilities are:
 
-    git init my-new-repo
-    cd my-new-repo
-    git pull git@github.com:nexB/skeleton
+1. **Data Federation**: A Data Federation is a database, representing a consistent,
+non-overlapping set of data kind clusters (like scans, vulnerabilities or SBOMs)
+across many package ecosystems, aka. PURL types.
+A Federation is similar to a traditional database.
 
-    # Create the new repo on GitHub, then update your remote
-    git remote set-url origin git@github.com:nexB/your-new-repo.git
+2. **Data Cluster**: A Data Federation contains Data Clusters, where a Data Cluster
+purpose is to store the data of a single kind (like scans) across multiple PURL
+types. The cluster name is the data kind name and is used as the prefix for
+repository names. A Data Cluster is akin to a table in a traditional database.
 
-From here, you can make the appropriate changes to the files for your specific project.
+3. **Data Repository**: A DataCluster contains of one or more Git Data Repository,
+each storing datafiles of the cluster data kind and a one PURL type, spreading
+the datafiles in multiple Data Directories. The name is data-kind +PURL-
+type+hashid. A Repository is similar to a shard or tablespace in a traditionale
+database.
 
-Update an existing project
----------------------------
+4. **Data Directory**: In a Repository, a Data Directory contains the datafiles for
+PURLs. The directory name PURL-type+hashid
 
-.. code-block:: bash
+5. **Data File**: This is a Data File of the DataCluster's Data Kind that is
+stored in subdirectories structured after the PURL components::
 
-    cd my-existing-project
-    git remote add skeleton git@github.com:nexB/skeleton
-    git fetch skeleton
-    git merge skeleton/main --allow-unrelated-histories
+   namespace/name/version/qualifiers/subpath:
 
-This is also the workflow to use when updating the skeleton files in any given repository.
+- Either at the level of a PURL name: namespace/name,
+- Or at the PURL version level namespace/name/version,
+- Or at the PURL qualifiers+PURL subpath level.
 
-More usage instructions can be found in ``docs/skeleton-usage.rst``.
+A Data File can be for instance a JSON scan results file, or a list of PURLs in
+YAML.
 
+For example, a list of PURLs as a Data Kind  would stored at the name
+subdirectory level::
 
-Release Notes
-=============
+    gem-0107/gem/random_password_generator/purls.yml
 
-- 2025-03-31:
+Or a ScanCode scan as a Data Kind at the version subdirectory level::
 
-    - Use ruff as the main code formatting tool, add ruff rules to pyproject.toml
+    gem-0107/npm/file/3.24.3/scancode.yml
 
-- 2025-03-29:
 
-    - Add support for beta macOS-15
-    - Add support for beta windows-2025
 
-- 2025-02-14:
+License
+-------
 
-    - Drop support for Python 3.8, add support in CI for Python 3.13, use Python 3.12 as default
-      version.
+Copyright (c) AboutCode and others. All rights reserved.
 
-- 2025-01-17:
+SPDX-License-Identifier: Apache-2.0
 
-    - Drop support for macOS-12, add support for macOS-14
-    - Add support in CI for ubuntu-24.04
-    - Add support in CI for Python 3.12
+See https://github.com/aboutcode-org/vulnerablecode for support or download.
 
-- 2024-08-20:
-
-    - Update references of ownership from nexB to aboutcode-org
-
-- 2024-07-01:
-
-    - Drop support for Python 3.8
-    - Drop support for macOS-11, add support for macOS-14
-
-- 2024-02-19:
-
-    - Replace support in CI of default ubuntu-20.04 by ubuntu-22.04
-
-- 2023-10-18:
-
-    - Add dark mode support in documentation
-
-- 2023-07-18:
-
-    - Add macOS-13 job in azure-pipelines.yml
-
-- 2022-03-04:
-
-    - Synchronize configure and configure.bat scripts for sanity
-    - Update CI operating system support with latest Azure OS images
-    - Streamline utility scripts in etc/scripts/ to create, fetch and manage third-party
-      dependencies. There are now fewer scripts. See etc/scripts/README.rst for details
-
-- 2021-09-03:
-    - ``configure`` now requires pinned dependencies via the use of ``requirements.txt``
-      and ``requirements-dev.txt``
-    - ``configure`` can now accept multiple options at once
-    - Add utility scripts from scancode-toolkit/etc/release/ for use in generating project files
-    - Rename virtual environment directory from ``tmp`` to ``venv``
-    - Update README.rst with instructions for generating ``requirements.txt``
-      and ``requirements-dev.txt``, as well as collecting dependencies as wheels and generating
-      ABOUT files for them.
-
-- 2021-05-11:
-    - Adopt new configure scripts from ScanCode TK that allows correct configuration of which
-      Python version is used.
+See https://aboutcode.org for more information about AboutCode OSS projects.

setup.cfg

@@ -1,12 +1,12 @@
 [metadata]
-name = skeleton
+name = aboutcode.federated
 license = Apache-2.0
 
 # description must be on ONE line https://github.com/pypa/setuptools/issues/1390
-description = skeleton
+description = "A library for AboutCode PURL-based federated identifiers"
 long_description = file:README.rst
 long_description_content_type = text/x-rst
-url = https://github.com/aboutcode-org/skeleton
+url = https://github.com/aboutcode-org/aboutcode.federated
 
 author = nexB. Inc. and others
 author_email = info@aboutcode.org
@@ -20,7 +20,13 @@ classifiers =
     Topic :: Utilities
 
 keywords =
-    utilities
+    purl
+    Package-URL
+    open source
+    package
+    sca
+    scan
+    hash
 
 license_files =
     apache-2.0.LICENSE
@@ -40,6 +46,10 @@ include_package_data = true
 zip_safe = false
 
 install_requires =
+    packageurl_python == 0.17.6
+    saneyaml == 0.6.1
+    requests == 2.25.1
+    uritemplate == 4.2.0
 
 
 [options.packages.find]