updateCitation 0.0.1__py3-none-any.whl

tests/conftest.py

@@ -0,0 +1,96 @@
+"""SSOT for Pytest."""
+from typing import Generator, Any, Type, Callable
+import pathlib
+from updateCitation import (
+    add_pyprojectDOTtoml,
+    addCitation,
+    addGitHubRelease,
+    addPyPAMetadata,
+    addPyPIrelease,
+    CitationNexus,
+    flowControl,
+    getSettingsPackage,
+    SettingsPackage,
+)
+from updateCitation.github import getGitHubRelease
+from updateCitation.pypa import getPyPAMetadata
+from updateCitation.pypi import getPyPIrelease
+from updateCitation.pyprojectDOTtoml import get_pyprojectDOTtoml
+from updateCitation.variables import cffDASHversionDEFAULT, CitationNexusFieldsRequired, messageDEFAULT
+import pytest
+import shutil
+import uuid
+
+# SSOT for test data paths and filenames
+pathDataSamples = pathlib.Path("tests/dataSamples")
+pathFilenameCitationAlphaDOTcff = pathDataSamples / "citationAlpha.cff"
+pathTmpRoot = pathDataSamples / "tmp"
+
+@pytest.fixture(scope="session", autouse=True)
+def setupTeardownTestSession() -> Generator[None, None, None]:
+    pathDataSamples.mkdir(exist_ok=True)
+    pathTmpRoot.mkdir(exist_ok=True)
+    yield
+    shutil.rmtree(pathTmpRoot, ignore_errors=True)
+
+@pytest.fixture
+def pathTmpTesting(request: pytest.FixtureRequest) -> pathlib.Path:
+    """'path' means directory or folder, not file."""
+    pathTmp = pathTmpRoot / uuid.uuid4().hex
+    pathTmp.mkdir(parents=True, exist_ok=False)
+    return pathTmp
+
+@pytest.fixture
+def pathFilenameTmpTesting(request: pytest.FixtureRequest) -> pathlib.Path:
+    """'filename' means file; 'pathFilename' means the full path and filename."""
+    try:
+        extension = request.param
+    except AttributeError:
+        extension = ".txt"
+
+    uuidString = uuid.uuid4().hex
+    pathFilenameTmp = pathlib.Path(pathTmpRoot, uuidString[0:-8], uuidString[-8:None] + extension)
+    pathFilenameTmp.parent.mkdir(parents=True, exist_ok=False)
+    return pathFilenameTmp
+
+@pytest.fixture
+def nexusCitationTesting(request: pytest.FixtureRequest) -> CitationNexus:
+    """Return a CitationNexus object with the specified attributes."""
+    try:
+        attributes = request.param
+    except AttributeError:
+        attributes = {}
+
+    return CitationNexus(**attributes)
+
+@pytest.fixture
+def citationAlphaDOTcff() -> pathlib.Path:
+    return pathFilenameCitationAlphaDOTcff
+
+"""
+Section: Standardized assert statements and failure messages"""
+
+def uniformTestFailureMessage(expected: Any, actual: Any, functionName: str, *arguments: Any, **keywordArguments: Any) -> str:
+    """Format assertion message for any test comparison."""
+    listArgumentComponents = [str(parameter) for parameter in arguments]
+    listKeywordComponents = [f"{key}={value}" for key, value in keywordArguments.items()]
+    joinedArguments = ', '.join(listArgumentComponents + listKeywordComponents)
+
+    return (f"\nTesting: `{functionName}({joinedArguments})`\n"
+            f"Expected: {expected}\n"
+            f"Got: {actual}")
+
+def standardizedEqualTo(expected: Any, functionTarget: Callable, *arguments: Any, **keywordArguments: Any) -> None:
+    """Template for most tests to compare the actual outcome with the expected outcome, including expected errors."""
+    if type(expected) == Type[Exception]:
+        messageExpected = expected.__name__
+    else:
+        messageExpected = expected
+
+    try:
+        messageActual = actual = functionTarget(*arguments, **keywordArguments)
+    except Exception as actualError:
+        messageActual = type(actualError).__name__
+        actual = type(actualError)
+
+    assert actual == expected, uniformTestFailureMessage(messageExpected, messageActual, functionTarget.__name__, *arguments, **keywordArguments)

tests/test_citationFileFormat.py

@@ -0,0 +1,39 @@
+import pathlib
+import pytest
+from tests.conftest import (
+    addCitation,
+    CitationNexus,
+    standardizedEqualTo,
+)
+
+def test_addCitation(nexusCitationTesting, citationAlphaDOTcff: pathlib.Path):
+    """Test that addCitation() returns a CitationNexus object."""
+    nexusCitation = addCitation(nexusCitationTesting, citationAlphaDOTcff)
+    assert isinstance(nexusCitation, CitationNexus), "addCitation() should return a CitationNexus object."
+
+@pytest.mark.parametrize("fieldName, expectedValue", [
+    ("cffDASHversion", "1.2.0"),
+    ("message", "If you use this software, you can cite it using the metadata from this file."),
+    ("authors", [{'given-names': 'Hunter', 'family-names': 'Hogan', 'email': 'HunterHogan@pm.me'}]),
+    ("commit", "0d70eb67ffbab9563208ec06294887fb7fa6768a"),
+    ("dateDASHreleased", "2025-02-07"),
+    ("identifiers", [{'type': 'url',
+                     'value': 'https://github.com/hunterhogan/mapFolding/releases/tag/0.3.9',
+                     'description': 'The URL for mapFolding 0.3.9.'}]),
+    ("keywords", ['A001415', 'A001416', 'A001417', 'A001418', 'A195646',
+                 'folding', 'map folding', 'OEIS', 'stamp folding']),
+    ("license", "CC-BY-NC-4.0"),
+    ("repository", "https://github.com/hunterhogan/mapFolding.git"),
+    ("repositoryDASHartifact", "https://pypi.org/project/mapfolding/0.3.9/"),
+    ("repositoryDASHcode", "https://github.com/hunterhogan/mapFolding/releases/tag/0.3.9"),
+    ("title", "mapFolding"),
+    ("type", "software"),
+    ("url", "https://github.com/hunterhogan/mapFolding"),
+    ("version", "0.3.9"),
+])
+def test_addCitation_fields(nexusCitationTesting, citationAlphaDOTcff: pathlib.Path,
+                          fieldName: str, expectedValue: str):
+    """Test that addCitation() correctly sets each field in the CitationNexus object."""
+    nexusCitation = addCitation(nexusCitationTesting, citationAlphaDOTcff)
+    # actual = getattr(nexusCitation, fieldName)
+    standardizedEqualTo(expectedValue, getattr, nexusCitation, fieldName)

tests/test_flowControl.py

@@ -0,0 +1,111 @@
+import os
+from updateCitation import flowControl
+import pathlib
+import pytest
+from conftest import standardizedEqualTo, cffDASHversionDEFAULT, messageDEFAULT, CitationNexus, SettingsPackage, get_pyprojectDOTtoml
+
+# Dummy implementations to record call order.
+def dummy_add_pyprojectDOTtoml(nexusCitation: CitationNexus, truth: SettingsPackage) -> tuple[CitationNexus, SettingsPackage]:
+    callOrder.append("add_pyprojectDOTtoml")
+    truth = get_pyprojectDOTtoml(truth)  # Populate truth.tomlPackageData from the pyproject.toml file.
+    # Set required fields to avoid ValueError from setInStone.
+    nexusCitation.title = truth.tomlPackageData.get("name")
+    nexusCitation.authors = truth.tomlPackageData.get("authors", [])
+    # Supply a dummy contact if absent.
+    contactData = truth.tomlPackageData.get("contact")
+    if not contactData:
+        nexusCitation.contact = [{"name": "Dummy", "email": "dummy@example.com"}]
+    else:
+        nexusCitation.contact = contactData
+    return nexusCitation, truth
+
+def dummy_addCitation(nexusCitation: CitationNexus, pathFilenameCitationSSOT) -> CitationNexus:
+    callOrder.append("addCitation")
+    return nexusCitation
+
+def dummy_addPyPAMetadata(nexusCitation: CitationNexus, tomlPackageData: dict) -> CitationNexus:
+    callOrder.append("addPyPAMetadata")
+    return nexusCitation
+
+def dummy_addGitHubRelease(nexusCitation: CitationNexus) -> CitationNexus:
+    callOrder.append("addGitHubRelease")
+    return nexusCitation
+
+def dummy_addPyPIrelease(nexusCitation: CitationNexus) -> CitationNexus:
+    callOrder.append("addPyPIrelease")
+    return nexusCitation
+
+def dummy_writeCitation(nexusCitation: CitationNexus, pathFilenameCitationSSOT, pathFilenameCitationDOTcffRepository) -> None:
+    callOrder.append("writeCitation")
+    return
+
+@pytest.fixture
+def validTomlTmpFile(tmp_path: pathlib.Path) -> pathlib.Path:
+    pathFilename = tmp_path / "pyproject.toml"
+    tomlContent = """
+[project]
+name = "ValidTitle"
+authors = [{name = "John Doe", email = "john@example.com"}]
+contact = [{name = "Contact Name", email = "contact@example.com"}]
+"""
+    pathFilename.write_text(tomlContent)
+    return pathFilename
+
+@pytest.fixture
+def missingTitleTomlTmpFile(tmp_path: pathlib.Path) -> pathlib.Path:
+    pathFilename = tmp_path / "pyproject.toml"
+    # Missing the "name" key.
+    tomlContent = """
+[project]
+authors = [{name = "John Doe", email = "john@example.com"}]
+contact = [{name = "Contact Name", email = "contact@example.com"}]
+"""
+    pathFilename.write_text(tomlContent)
+    return pathFilename
+
+def restore_flowControl(monkeypatch) -> None:
+    # Restore original functions (if needed in further tests) by deleting our attributes.
+    for name in ["add_pyprojectDOTtoml", "addCitation", "addPyPAMetadata", "addGitHubRelease", "addPyPIrelease", "writeCitation"]:
+        if hasattr(flowControl, name):
+            monkeypatch.undo()
+
+def test_here_valid(validTomlTmpFile: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    global callOrder
+    callOrder = []  # type: list[str]
+
+    # Override functions in flowControl, recording call order.
+    monkeypatch.setattr(flowControl, "add_pyprojectDOTtoml", dummy_add_pyprojectDOTtoml)
+    monkeypatch.setattr(flowControl, "addCitation", dummy_addCitation)
+    monkeypatch.setattr(flowControl, "addPyPAMetadata", dummy_addPyPAMetadata)
+    monkeypatch.setattr(flowControl, "addGitHubRelease", dummy_addGitHubRelease)
+    monkeypatch.setattr(flowControl, "addPyPIrelease", dummy_addPyPIrelease)
+    monkeypatch.setattr(flowControl, "writeCitation", dummy_writeCitation)
+
+    # Call here() with our valid temporary pyproject.toml.
+    flowControl.here(validTomlTmpFile)
+
+    # Verify call order.
+    expectedOrder = [
+        "add_pyprojectDOTtoml",
+        "addCitation",
+        "addPyPAMetadata",
+        "addGitHubRelease",
+        "addPyPIrelease",
+        "writeCitation"
+    ]
+    assert callOrder == expectedOrder
+
+def test_here_missingTitle(missingTitleTomlTmpFile: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    # Override add_pyprojectDOTtoml to mimic its normal behavior so that title remains None.
+    def dummy_noTitle(nexusCitation: CitationNexus, truth: SettingsPackage) -> tuple[CitationNexus, SettingsPackage]:
+        # Do not set title.
+        nexusCitation.authors = truth.tomlPackageData.get("authors", [])
+        nexusCitation.contact = truth.tomlPackageData.get("contact", [])
+        # This will cause setInStone to raise ValueError.
+        nexusCitation.setInStone("pyprojectDOTtoml")
+        return nexusCitation, truth
+
+    monkeypatch.setattr(flowControl, "add_pyprojectDOTtoml", dummy_noTitle)
+
+    with pytest.raises(ValueError):
+        flowControl.here(missingTitleTomlTmpFile)

tests/test_pypa.py

@@ -0,0 +1,18 @@
+import pytest
+from conftest import standardizedEqualTo, getPyPAMetadata, addPyPAMetadata, CitationNexus
+
+def test_getPyPAMetadata_missingName() -> None:
+    dictionaryPackageData = {
+        "version": "17.19.23",
+    }
+    with pytest.raises(Exception):
+        getPyPAMetadata(dictionaryPackageData)
+
+def test_addPyPAMetadata_missingName(nexusCitationTesting: CitationNexus) -> None:
+    dictionaryPackageData = {
+        "urls": {
+            "homepage": "https://gemini.stars.cosmos"
+        }
+    }
+    with pytest.raises(Exception):
+        addPyPAMetadata(nexusCitationTesting, dictionaryPackageData)

tests/test_pypi.py

@@ -0,0 +1,15 @@
+import pytest
+from conftest import standardizedEqualTo, getPyPIrelease, addPyPIrelease
+
+@pytest.mark.parametrize("nexusCitationTesting, expected", [
+({"title": "numpy", "version": "1.23.5"}, {"repositoryDASHartifact": "https://pypi.org/project/numpy/1.23.5/"}),
+({"title": "scikit-learn", "version": "1.2.2"}, {"repositoryDASHartifact": "https://pypi.org/project/scikit-learn/1.2.2/"}),
+({"title": "Requests", "version": "2.28.2"}, {"repositoryDASHartifact": "https://pypi.org/project/requests/2.28.2/"}),
+({"title": "Orion", "version": "5.7.11"}, {"repositoryDASHartifact": "https://pypi.org/project/orion/5.7.11/"}),
+({"title": "Taurus", "version": "11.13.17"}, {"repositoryDASHartifact": "https://pypi.org/project/taurus/11.13.17/"}),
+({"version": "1.0.0"}, ValueError),
+({"title": "pandas"}, ValueError),
+({}, ValueError), ], indirect=["nexusCitationTesting"] )
+def test_getPyPIrelease(nexusCitationTesting: dict[str, str], expected: dict[str, str] | type[ValueError]) -> None:
+    """Test PyPI release info retrieval with various package names and versions."""
+    standardizedEqualTo(expected, getPyPIrelease, nexusCitationTesting)

tests/test_variables.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+import pytest
+from conftest import standardizedEqualTo, cffDASHversionDEFAULT, messageDEFAULT, CitationNexus, SettingsPackage
+
+def test_CitationNexus_requiredFields(nexusCitationTesting: CitationNexus) -> None:
+    assert nexusCitationTesting.cffDASHversion == cffDASHversionDEFAULT
+    assert nexusCitationTesting.message == messageDEFAULT
+    assert nexusCitationTesting.authors == []
+    assert nexusCitationTesting.title is None
+
+def test_CitationNexus_setInStone_failsOnMissingRequired(nexusCitationTesting: CitationNexus) -> None:
+    nexusCitation = CitationNexus()
+    with pytest.raises(ValueError, match="Field title is required but not provided"):
+        nexusCitation.setInStone("pyprojectDOTtoml")
+
+def test_CitationNexus_setInStone_freezesFields(nexusCitationTesting: CitationNexus) -> None:
+    nexusCitationTesting.title = "SolarSystem"
+    nexusCitationTesting.authors = [{"given-names": "Mercury", "family-names": "Venus"}]
+    nexusCitationTesting.setInStone("pyprojectDOTtoml")
+
+    nexusCitationTesting.title = "GalacticCore"
+    assert nexusCitationTesting.title == "SolarSystem"
+
+def test_CitationNexus_setInStone_multipleContexts(nexusCitationTesting: CitationNexus) -> None:
+    nexusCitationTesting.title = "Jupiter"
+    nexusCitationTesting.authors = [{"given-names": "Saturn", "family-names": "Uranus"}]
+    nexusCitationTesting.version = "3.5.7"
+    nexusCitationTesting.keywords = ["Neptune", "Pluto"]
+    nexusCitationTesting.setInStone("pyprojectDOTtoml")
+    nexusCitationTesting.setInStone("PyPA")
+
+    # Should not change fields frozen by either context
+    nexusCitationTesting.title = "NewTitle"
+    nexusCitationTesting.version = "3.5.8"
+    assert nexusCitationTesting.title == "Jupiter"
+    assert nexusCitationTesting.version == "3.5.7"
+
+def test_SettingsPackage_initialization(pathFilenameTmpTesting: Path) -> None:
+    settings = SettingsPackage(pathFilenamePackageSSOT=pathFilenameTmpTesting)
+    assert settings.pathFilenamePackageSSOT == pathFilenameTmpTesting
+    assert settings.filenameCitationDOTcff == "CITATION.cff"
+    assert isinstance(settings.tomlPackageData, dict)

updateCitation/__init__.py

@@ -0,0 +1,16 @@
+from .variables import (
+    CitationNexus,
+    CitationNexusFieldsFrozen,
+    filename_pyprojectDOTtomlDEFAULT,
+    mapNexusCitation2pyprojectDOTtoml,
+    projectURLTargets,
+    SettingsPackage,
+)
+
+from .pyprojectDOTtoml import add_pyprojectDOTtoml, getSettingsPackage
+from .citationFileFormat import addCitation, writeCitation
+from .pypa import addPyPAMetadata
+from .github import addGitHubRelease
+from .pypi import addPyPIrelease
+
+from .flowControl import here

updateCitation/citationFileFormat.py

@@ -0,0 +1,88 @@
+from cffconvert.cli.create_citation import create_citation
+from typing import Any, Dict, List
+from updateCitation import CitationNexus, CitationNexusFieldsFrozen
+import attrs
+import cffconvert
+import pathlib
+import ruamel.yaml
+
+def addCitation(nexusCitation: CitationNexus, pathFilenameCitationSSOT: pathlib.Path) -> CitationNexus:
+    """Given a path to a citation file, return a CitationNexus object.
+        The citation file is expected to be in a format that can be parsed by
+        `cffconvert.cli.create_citation.create_citation()`. This function
+        ensures convergence with the CFF ecosystem by using `create_citation`
+        and its internal `_parse()` method.
+        Parameters:
+            pathFilenameCitationSSOT (pathlib.Path): Path to the citation file.
+        Returns:
+            CitationNexus: A CitationNexus object populated with data from the
+                citation file.
+        """
+
+    # `cffconvert.cli.create_citation.create_citation()` is PAINFULLY mundane, but a major problem
+    # in the CFF ecosystem is divergence. Therefore, I will use this function so that my code
+    # converges with the CFF ecosystem.
+    citationObject: cffconvert.Citation = create_citation(infile=pathFilenameCitationSSOT, url=None)
+    # `._parse()` is a yaml loader: use it for convergence
+    cffobj: Dict[Any, Any] = citationObject._parse()
+
+    # This step is designed to prevent deleting fields that are populated in the current CFF file,
+    # but for whatever reason do not get added to the CitationNexus object.
+    Z0Z_list: List[attrs.Attribute] = list(attrs.fields(type(nexusCitation)))
+    for Z0Z_field in Z0Z_list:
+        if Z0Z_field.name in CitationNexusFieldsFrozen:
+            continue
+        cffobjKeyName: str = Z0Z_field.name.replace("DASH", "-")
+        cffobjValue = cffobj.get(cffobjKeyName)
+        if cffobjValue: # An empty list will be False
+            setattr(nexusCitation, Z0Z_field.name, cffobjValue)
+
+    # nexusCitation.setInStone("Citation")
+    return nexusCitation
+
+def writeCitation(nexusCitation: CitationNexus, pathFilenameCitationSSOT: pathlib.Path, pathFilenameCitationDOTcffRepo: pathlib.Path):
+    """Writes citation information to YAML files.
+        This function takes a CitationNexus object and writes its data to two YAML files:
+        one for single source of truth (SSOT) and another for a repository's .cff file.
+        It performs data conversion, validation, and file writing using the ruamel.yaml library.
+        Parameters:
+            nexusCitation (CitationNexus): An object containing citation metadata.
+            pathFilenameCitationSSOT (pathlib.Path): Path to the SSOT YAML file.
+            pathFilenameCitationDOTcffRepo (pathlib.Path): Path to the .cff YAML file in the repository.
+        Raises:
+            ValidationError: If the generated citation object fails validation.
+        Notes:
+            - The function uses a temporary validation file.
+            - It replaces "DASH" with "-" in dictionary keys.
+            - It filters out empty lists from the citation data.
+        """
+
+    # NOTE embarrassingly hacky process to follow
+    parameterIndent= 2
+    parameterLineWidth = 60
+    yamlWorkhorse = ruamel.yaml.YAML()
+
+    def srsly(Z0Z_filed, Z0Z_value):
+        if Z0Z_value: # empty lists
+            return True
+        else:
+            return False
+
+    dictionaryCitation = attrs.asdict(nexusCitation, filter=srsly)
+    for keyName in list(dictionaryCitation.keys()):
+        dictionaryCitation[keyName.replace("DASH", "-")] = dictionaryCitation.pop(keyName)
+
+    pathFilenameForValidation = pathFilenameCitationSSOT.with_stem('validation')
+
+    def writeStream(pathFilename):
+        with open(pathFilename, 'w') as pathlibIsAStealthContextManagerThatRuamelCannotDetectAndRefusesToWorkWith:
+            yamlWorkhorse.dump(dictionaryCitation, pathlibIsAStealthContextManagerThatRuamelCannotDetectAndRefusesToWorkWith)
+
+    writeStream(pathFilenameForValidation)
+
+    citationObject: cffconvert.Citation = create_citation(infile=pathFilenameForValidation, url=None)
+    if citationObject.validate() is None:
+        writeStream(pathFilenameCitationSSOT)
+        writeStream(pathFilenameCitationDOTcffRepo)
+
+    pathFilenameForValidation.unlink()

updateCitation/flowControl.py

@@ -0,0 +1,77 @@
+from typing import Any, Union
+from updateCitation import (
+    add_pyprojectDOTtoml,
+    addCitation,
+    addGitHubRelease,
+    addPyPAMetadata,
+    addPyPIrelease,
+    CitationNexus,
+    filename_pyprojectDOTtomlDEFAULT,
+    getSettingsPackage,
+    SettingsPackage,
+    writeCitation,
+)
+import os
+import pathlib
+
+"""
+How to automate citation updates:
+- The `pyproject.toml` file is the source of truth for settings.
+    - read from it
+    - create a `SettingsPackage` object with the toml values or the default values
+- Create an installable package for updateCitation.
+- Create a GitHub Action that runs updateCitation.
+
+Projected flow during a GitHub action to update a citation:
+- Commit and push all to GitHub
+- GitHub action:
+    - pip install updateCitation # i need to make a PyPI package first, of course
+    - import updateCitation
+    - `updateCitation.here()`
+    ? Can/should the following logic (or some parts of it) be a function in `updateCitation`?
+    - updateCitation will compare the toml version to the github and the pypi versions
+        - if the toml version is newer
+            - if python tests pass,
+                - updateCitation will update everything, including not yet existing versions on GitHub and/or PyPI
+                - updateCitation will make a special git commit with the updated citation so that the updated versions are in the releases
+                - after that special commit, the workflows for GitHub and PyPI are allowed to run
+            - if python tests do NOT pass, updateCitation will update everything but NOT anticipate new versions numbers on GitHub and PyPI
+        - I don't have logic for updating the `commit` field yet, but when I figure out how to implement the logic, I guess I will use the hash from the commit just before the special commit.
+"""
+
+def here(pathFilename_pyprojectDOTtoml: Union[str, os.PathLike[Any], None] = None) -> None:
+    """Updates citation files based on package metadata and release information.
+
+        This function orchestrates the update of citation files within a repository.
+        It gathers metadata from the pyproject.toml file, adds information from
+        GitHub and PyPI releases, and writes the updated citation data to both
+        the single-source-of-truth (SSOT) citation file and the repository-level
+        citation file.
+        Parameters:
+            pathRoot (Union[str, os.PathLike[Any]]): The root path of the repository.
+        Raises:
+            ValueError: If the package name cannot be found in the pyproject.toml file.
+        """
+    pathFilenameSettingsSSOT = pathlib.Path(pathFilename_pyprojectDOTtoml) if pathFilename_pyprojectDOTtoml else pathlib.Path.cwd() / filename_pyprojectDOTtomlDEFAULT
+    truth: SettingsPackage = getSettingsPackage(pathFilenameSettingsSSOT)
+
+    nexusCitation = CitationNexus()
+
+    nexusCitation, truth = add_pyprojectDOTtoml(nexusCitation, truth)
+
+    if not nexusCitation.title:
+        # TODO learn how to change the field from `str | None` to `str` after the field is populated
+        # especially for a required field
+        raise ValueError("Package name is required.")
+
+    # pathCitations = truth.pathRepository / "citations"
+    pathCitations = truth.pathRepository / nexusCitation.title / "citations"
+    pathFilenameCitationSSOT = pathCitations / truth.filenameCitationDOTcff
+    pathFilenameCitationDOTcffRepository = truth.pathRepository / truth.filenameCitationDOTcff
+
+    nexusCitation = addCitation(nexusCitation, pathFilenameCitationSSOT)
+    nexusCitation = addPyPAMetadata(nexusCitation, truth.tomlPackageData)
+    nexusCitation = addGitHubRelease(nexusCitation)
+    nexusCitation = addPyPIrelease(nexusCitation)
+
+    writeCitation(nexusCitation, pathFilenameCitationSSOT, pathFilenameCitationDOTcffRepository)

updateCitation/github.py

@@ -0,0 +1,76 @@
+from github import Auth, Github
+from typing import Any, Dict
+from updateCitation import CitationNexus
+import os
+import warnings
+
+def getGitHubRelease(nexusCitation: CitationNexus) -> Dict[str, Any]:
+    """Retrieves the latest release information from a GitHub repository.
+        Parameters:
+            nexusCitation (CitationNexus): A CitationNexus object containing
+                citation metadata, including the repository URL.
+        Returns:
+            Dict[str, Any]: A dictionary containing the release date,
+                identifiers (release URL), and repository code URL.
+                Returns an empty dictionary if the repository URL is missing
+                or if an error occurs while fetching the release information.
+        """
+    if not nexusCitation.repository:
+        return {}
+
+    githubClient = None
+    try:
+        # Initialize GitHub client with optional authentication
+        token = os.environ.get("GITHUB_TOKEN")
+        githubClient = Github(auth=Auth.Token(token)) if token else Github()
+
+        repoFullName = nexusCitation.repository.replace("https://github.com/", "").replace(".git", "")
+        repo = githubClient.get_repo(repoFullName)
+
+        latestRelease = repo.get_latest_release()
+
+        return {
+            "dateDASHreleased": latestRelease.published_at.strftime("%Y-%m-%d"),
+            "identifiers": [{
+                "type": "url",
+                "value": latestRelease.html_url,
+                "description": f"The URL for {nexusCitation.title} {nexusCitation.version}."
+            }] if latestRelease.html_url else [],
+            "repositoryDASHcode": latestRelease.html_url,
+        }
+
+    except Exception as ERRORmessage:
+        warnings.warn(f"Failed to get GitHub release info: {ERRORmessage}")
+        return {}
+    finally:
+        if githubClient:
+            githubClient.close()
+
+def addGitHubRelease(nexusCitation: CitationNexus) -> CitationNexus:
+    """Adds GitHub release information to a CitationNexus object.
+        Parameters:
+            nexusCitation (CitationNexus): The CitationNexus object to update.
+        Returns:
+            CitationNexus: The updated CitationNexus object with GitHub release information.
+    """
+
+    gitHubReleaseData = getGitHubRelease(nexusCitation)
+
+    commitValue = gitHubReleaseData.get("commit")
+    if commitValue:
+        nexusCitation.commit = commitValue
+
+    dateDASHreleasedValue = gitHubReleaseData.get("dateDASHreleased")
+    if dateDASHreleasedValue:
+        nexusCitation.dateDASHreleased = dateDASHreleasedValue
+
+    identifiersValue = gitHubReleaseData.get("identifiers")
+    if identifiersValue:
+        nexusCitation.identifiers = identifiersValue
+
+    repositoryDASHcodeValue = gitHubReleaseData.get("repositoryDASHcode")
+    if repositoryDASHcodeValue:
+        nexusCitation.repositoryDASHcode = repositoryDASHcodeValue
+
+    # nexusCitation.setInStone("GitHub")
+    return nexusCitation

updateCitation/pypa.py

@@ -0,0 +1,82 @@
+from updateCitation import CitationNexus, projectURLTargets
+from packaging.metadata import Metadata as PyPAMetadata
+from typing import Any, Dict
+import packaging
+import packaging.metadata
+import packaging.utils
+import packaging.version
+
+def getPyPAMetadata(packageData: Dict[str, Any]) -> PyPAMetadata:
+    """
+    Retrieves and formats package metadata from a dictionary into a PyPAMetadata object.
+    Parameters:
+        packageData (Dict[str, Any]): A dictionary containing package information,
+            typically obtained from an external source like a package index.
+            It should include keys such as "name", "version", "keywords", "license",
+            and "urls". The "urls" key should map to a dictionary where keys are
+            URL names (e.g., "Homepage", "Documentation") and values are the
+            corresponding URLs. The "license" key is expected to be a dictionary
+            with a "text" key holding the license text.
+    Returns:
+        PyPAMetadata: A PyPAMetadata object containing the extracted and formatted
+            metadata. The project URLs are filtered to include only those with keys
+            present in the `projectURLTargets` set (converted to lowercase for
+            comparison). The package name is canonicalized using
+            `packaging.utils.canonicalize_name` and validated.
+    Raises:
+        packaging.metadata.InvalidMetadata: If the package name is missing from
+            the input `packageData`. This exception is raised by
+            `packaging.utils.canonicalize_name` if `validate=True` and the name
+            is None. Other potential exceptions from `packaging.utils.canonicalize_name`
+            are not explicitly handled.
+    """
+    dictionaryProjectURLs: Dict[str, str] = {}
+    for urlName, url in packageData.get("urls", {}).items():
+        urlName = urlName.lower()
+        if urlName in projectURLTargets:
+            dictionaryProjectURLs[urlName] = url
+
+    metadataRaw = packaging.metadata.RawMetadata(
+        keywords=packageData.get("keywords", []),
+        license_expression=packageData.get("license", {}).get("text", ""),
+        metadata_version="2.4",
+        name=packaging.utils.canonicalize_name(packageData.get("name", None), validate=True), # packaging.metadata.InvalidMetadata: 'name' is a required field
+        project_urls=dictionaryProjectURLs,
+        version=packageData.get("version", None),
+    )
+
+    metadata = PyPAMetadata().from_raw(metadataRaw)
+    return metadata
+
+def addPyPAMetadata(nexusCitation: CitationNexus, tomlPackageData: Dict[str, Any]) -> CitationNexus:
+    """Adds PyPA (Python Packaging Authority) metadata to a CitationNexus object.
+        Parameters:
+            nexusCitation (CitationNexus): The CitationNexus object to update.
+            tomlPackageData (Dict[str, Any]): A dictionary containing the parsed TOML data
+                from the package's pyproject.toml file.  This should contain the
+                `project` table as specified in PEP 621.
+        Returns:
+            CitationNexus: The updated CitationNexus object with PyPA metadata.
+        Raises:
+            ValueError: If the metadata name is missing from the TOML data.
+        """
+
+    metadata: PyPAMetadata = getPyPAMetadata(tomlPackageData)
+
+    if metadata.version: nexusCitation.version = str(metadata.version)
+    if metadata.keywords: nexusCitation.keywords = metadata.keywords
+    if metadata.license_expression: nexusCitation.license = metadata.license_expression
+
+    Z0Z_lookup: Dict[str, str] = {
+        "homepage": "url",
+        "license": "licenseDASHurl",
+        "repository": "repository",
+    }
+    if metadata.project_urls:
+        for urlTarget in projectURLTargets:
+            url = metadata.project_urls.get(urlTarget, None)
+            if url:
+                setattr(nexusCitation, Z0Z_lookup[urlTarget], url)
+
+    # nexusCitation.setInStone("PyPA")
+    return nexusCitation