Skip to content

Commit aaf34b1

Browse files
arcangelo7arcangelo7
committed
feat!: Initial implementation of Aldrovandi Provenance toolkit for generating RDF provenance snapshots using CHAD-AP model, with CLI, format detection, and full test suite
0 parents  commit aaf34b1

19 files changed

Lines changed: 1010 additions & 0 deletions

‎.github/workflows/release.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches: [master]
6+
7+
jobs:
8+
release:
9+
name: Release
10+
runs-on: ubuntu-latest
11+
# Only run if commit message contains the keyword [release]
12+
if: contains(github.event.head_commit.message, '[release]')
13+
permissions:
14+
contents: write
15+
issues: write
16+
pull-requests: write
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
24+
- name: Setup Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.10"
28+
29+
- name: Setup Poetry
30+
uses: snok/install-poetry@v1
31+
with:
32+
virtualenvs-create: true
33+
virtualenvs-in-project: true
34+
35+
- name: Install dependencies
36+
run: poetry install
37+
38+
- name: Setup Node.js
39+
uses: actions/setup-node@v4
40+
with:
41+
node-version: "lts/*"
42+
43+
- name: Install semantic-release
44+
run: |
45+
npm install -g semantic-release
46+
npm install -g @semantic-release/git
47+
npm install -g @semantic-release/changelog
48+
npm install -g @semantic-release/exec
49+
50+
- name: Create Release
51+
env:
52+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
53+
run: npx semantic-release

‎.github/workflows/run-tests.yml‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
name: Run tests
2+
3+
on:
4+
push:
5+
branches:
6+
- "**" # All branches, including those with /
7+
pull_request:
8+
branches: [master]
9+
10+
# Add permissions needed for GitHub Pages
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
# Environment for GitHub Pages
17+
env:
18+
COVERAGE_REPORT_PATH: htmlcov
19+
20+
jobs:
21+
CheckCoverage:
22+
runs-on: ubuntu-latest
23+
strategy:
24+
fail-fast: false
25+
matrix:
26+
python-version: ["3.10", "3.11", "3.12"]
27+
28+
steps:
29+
- uses: actions/checkout@v4
30+
with:
31+
submodules: recursive
32+
33+
- name: Set up Python ${{ matrix.python-version }}
34+
uses: actions/setup-python@v5
35+
with:
36+
python-version: ${{ matrix.python-version }}
37+
38+
- name: Setup Poetry
39+
uses: snok/install-poetry@v1
40+
with:
41+
virtualenvs-create: true
42+
virtualenvs-in-project: true
43+
44+
- name: Install dependencies
45+
run: |
46+
poetry install --with dev
47+
48+
- name: Run tests with coverage
49+
run: |
50+
poetry run pip install pytest-cov
51+
poetry run pytest --cov=aldrovandi_provenance --cov-report=xml --cov-report=term
52+
echo "=== Coverage Report ==="
53+
poetry run coverage report
54+
echo "COVERAGE=$(poetry run coverage report | grep TOTAL | awk '{print $4}')" >> $GITHUB_ENV
55+
56+
- name: Generate HTML coverage report
57+
run: |
58+
poetry run coverage html -d htmlcov
59+
60+
# Configure GitHub Pages
61+
- name: Setup Pages
62+
if: matrix.python-version == '3.10'
63+
uses: actions/configure-pages@v5
64+
65+
# Upload coverage report as Pages artifact
66+
- name: Upload Pages artifact
67+
if: matrix.python-version == '3.10' && github.ref == 'refs/heads/main'
68+
uses: actions/upload-pages-artifact@v3
69+
with:
70+
path: ${{ env.COVERAGE_REPORT_PATH }}
71+
72+
- name: Generate coverage badge
73+
if: matrix.python-version == '3.10'
74+
run: |
75+
# Extract coverage percentage as a number
76+
COVERAGE_NUM=$(echo ${{ env.COVERAGE }} | sed 's/%//')
77+
78+
# Determine color based on coverage
79+
if (( $(echo "$COVERAGE_NUM >= 90" | bc -l) )); then
80+
COLOR="green"
81+
elif (( $(echo "$COVERAGE_NUM >= 75" | bc -l) )); then
82+
COLOR="yellow"
83+
elif (( $(echo "$COVERAGE_NUM >= 60" | bc -l) )); then
84+
COLOR="orange"
85+
else
86+
COLOR="red"
87+
fi
88+
89+
echo "BADGE_COLOR=$COLOR" >> $GITHUB_ENV
90+
91+
- name: Create badge
92+
if: matrix.python-version == '3.10'
93+
uses: RubbaBoy/BYOB@v1.3.0
94+
with:
95+
name: aldrovandi-provenance-coverage-${{ github.ref_name }}
96+
label: "Coverage"
97+
status: "${{ env.COVERAGE }}"
98+
color: ${{ env.BADGE_COLOR }}
99+
github_token: ${{ secrets.GIST_PAT }}
100+
repository: arcangelo7/badges
101+
actor: arcangelo7
102+
103+
# Add a new job to deploy to GitHub Pages
104+
# deploy-coverage:
105+
# needs: CheckCoverage
106+
# runs-on: ubuntu-latest
107+
# environment:
108+
# name: ${{ github.repository }}/pages
109+
# url: ${{ steps.deployment.outputs.page_url }}
110+
# steps:
111+
# - name: Deploy to GitHub Pages
112+
# id: deployment
113+
# uses: actions/deploy-pages@v4

‎.releaserc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"branches": ["main"],
3+
"plugins": [
4+
"@semantic-release/commit-analyzer",
5+
"@semantic-release/release-notes-generator",
6+
"@semantic-release/changelog",
7+
[
8+
"@semantic-release/exec",
9+
{
10+
"prepareCmd": "poetry version ${nextRelease.version}"
11+
}
12+
],
13+
[
14+
"@semantic-release/git",
15+
{
16+
"assets": ["pyproject.toml", "CHANGELOG.md"],
17+
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
18+
}
19+
],
20+
"@semantic-release/github"
21+
]
22+
}

‎LICENSE‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
ISC License
2+
3+
Copyright 2025 Arcangelo Massari <info@arcangelomassari.com>
4+
5+
Permission to use, copy, modify, and/or distribute this software for any purpose
6+
with or without fee is hereby granted, provided that the above copyright notice
7+
and this permission notice appear in all copies.
8+
9+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
11+
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
12+
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
13+
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
14+
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
15+
SOFTWARE.

‎README.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Aldrovandi Provenance
2+
3+
[![Tests](https://github.com/arcangelo7/aldrovandi-provenance/actions/workflows/run-tests.yml/badge.svg)](https://github.com/arcangelo7/aldrovandi-provenance/actions/workflows/run-tests.yml)
4+
[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
5+
[![Repo Size](https://img.shields.io/github/repo-size/arcangelo7/aldrovandi-provenance)](https://github.com/arcangelo7/aldrovandi-provenance)
6+
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7+
[![License](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
8+
9+
This repository contains tools for managing provenance information for cultural heritage data using the CHAD-AP (Cultural Heritage Acquisition and Digitisation Application Profile) model.
10+
11+
## Overview
12+
13+
The project provides tools for generating provenance snapshots from RDF data, conforming to the [CHAD-AP specification](https://dharc-org.github.io/chad-ap/current/chad-ap.html).
14+
15+
The primary feature is generating provenance snapshots from RDF data in various formats, where:
16+
- Each subject in the input data gets a provenance named graph (subject URI + "/prov/")
17+
- Each subject gets a snapshot entity in its provenance graph (subject URI + "/prov/se/1")
18+
- Each snapshot is typed as a prov:Entity
19+
- Provenance metadata is added, including generation time and responsible agent
20+
21+
## Installation
22+
23+
Requirements:
24+
- Python 3.10+
25+
- Poetry (recommended for development)
26+
27+
### Using Poetry
28+
29+
If Poetry is not already installed, please follow the installation instructions at [https://python-poetry.org/docs/#installation](https://python-poetry.org/docs/#installation)
30+
31+
```bash
32+
# Clone the repository
33+
git clone https://github.com/your-username/aldrovandi-provenance.git
34+
cd aldrovandi-provenance
35+
36+
# Install dependencies with Poetry
37+
poetry install
38+
```
39+
40+
## Usage
41+
42+
### Generating Provenance Snapshots
43+
44+
The script processes all RDF files in a directory and generates provenance snapshots:
45+
46+
```bash
47+
python -m aldrovandi_provenance.generate_provenance INPUT_DIRECTORY OUTPUT_FILE [--format FORMAT] [--agent AGENT_ORCID]
48+
```
49+
50+
Arguments:
51+
- `INPUT_DIRECTORY`: Directory containing RDF files to process
52+
- `OUTPUT_FILE`: Output file for provenance snapshots (N-Quads format)
53+
- `--format`: (Optional) Force specific input format instead of auto-detection
54+
- `--agent`: (Optional) ORCID of the responsible agent (default: "https://orcid.org/0000-0002-8420-0696")
55+
56+
The script automatically detects RDF file formats based on extensions:
57+
- `.ttl` - Turtle
58+
- `.nt` - N-Triples
59+
- `.n3` - Notation3
60+
- `.xml`, `.rdf` - RDF/XML
61+
- `.jsonld` - JSON-LD
62+
- `.nq` - N-Quads
63+
- `.trig` - TriG
64+
65+
## Example
66+
67+
Input directory contains cultural heritage data in Turtle format:
68+
69+
```turtle
70+
@prefix ex: <http://example.org/> .
71+
@prefix crm: <http://www.cidoc-crm.org/cidoc-crm/> .
72+
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
73+
74+
ex:item1 a crm:E22_Human-Made_Object ;
75+
rdfs:label "Manuscript" .
76+
```
77+
78+
Command:
79+
```bash
80+
python -m aldrovandi_provenance.generate_provenance data/ output.nq
81+
```
82+
83+
The output will include:
84+
- Named graph `<http://example.org/item1/prov/>` containing snapshot metadata
85+
- Information about when the snapshot was created and by whom
86+
- The snapshot will have type prov:Entity
87+
88+
## Development
89+
90+
### Running Tests
91+
92+
```bash
93+
pytest -xvs tests/
94+
```
95+
96+
## License
97+
98+
See the LICENSE file for details.

‎aldrovandi_provenance/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""
2+
Aldrovandi Provenance package for generating provenance snapshots.
3+
"""

‎aldrovandi_provenance/__pycache__/__init__.cpython-313.pyc‎

256 Bytes
Binary file not shown.

‎aldrovandi_provenance/__pycache__/generate_provenance.cpython-313.pyc‎

6.31 KB
Binary file not shown.

0 commit comments

Comments
 (0)