wip: create utils to hold commonly used functionality

Author: schnaitter

quadriga/metadata/__init__.py

@@ -9,11 +9,13 @@
     "create_bibtex",
     "update_citation_cff",
     "extract_from_config_toc",
-    "run_all"
+    "run_all",
+    "utils"
 ]
 
 # Import the modules to make their functions available
 from . import create_bibtex
 from . import update_citation_cff
 from . import extract_from_config_toc
 from . import run_all
+from . import utils

quadriga/metadata/utils.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+Common utility functions for metadata management in the Quadriga Book Template.
+This module provides reused functionality across different metadata scripts.
+"""
+
+import yaml
+import os
+import re
+import json
+from pathlib import Path
+from datetime import datetime
+
+# ---- File Path Handling ----
+
+def get_repo_root():
+    """
+    Get the path to the repository root, assuming this module is in quadriga/metadata/.
+    
+    Returns:
+        str: Absolute path to the repository root
+    """
+    quadriga_metadata_dir = os.path.dirname(os.path.abspath(__file__))
+    quadriga_dir = os.path.dirname(quadriga_metadata_dir)
+    repo_root = os.path.dirname(quadriga_dir)
+    return repo_root
+
+def get_file_path(relative_path, repo_root=None):
+    """
+    Get the absolute path to a file in the repository.
+    
+    Args:
+        relative_path (str): Relative path from the repository root
+        repo_root (str, optional): Repository root path. If None, it will be determined
+    
+    Returns:
+        str: Absolute path to the file
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return os.path.join(repo_root, relative_path)
+
+# ---- YAML Handling ----
+
+def load_yaml_file(file_path):
+    """
+    Load a YAML file and return its contents as a Python object.
+    
+    Args:
+        file_path (str): Path to the YAML file
+        
+    Returns:
+        dict/list: Contents of the YAML file, or None if an error occurs
+    """
+    try:
+        with open(file_path, 'r', encoding='utf-8') as file:
+            return yaml.safe_load(file)
+    except Exception as e:
+        print(f"Error loading {file_path}: {e}")
+        return None
+
+def save_yaml_file(file_path, data, add_schema_comment=None):
+    """
+    Save Python object as YAML to the specified file.
+    
+    Args:
+        file_path (str): Path where the YAML file should be saved
+        data (dict/list): Data to save
+        add_schema_comment (str, optional): Schema comment to add at the start of the file
+                                           e.g. "# yaml-language-server: $schema=quadriga-schema.json"
+    """
+    try:
+        with open(file_path, 'w', encoding='utf-8') as file:
+            yaml.dump(data, file, sort_keys=False, default_flow_style=False, allow_unicode=True)
+        
+        # Add schema comment if requested
+        if add_schema_comment:
+            with open(file_path, 'r+', encoding='utf-8') as file:
+                content = file.read()
+                file.seek(0, 0)
+                file.write(f"{add_schema_comment}\n" + content)
+                
+        print(f"Successfully updated {file_path}")
+    except Exception as e:
+        print(f"Error saving to {file_path}: {e}")
+
+# ---- Markdown and Jupyter Content Handling ----
+
+def extract_first_heading(file_path):
+    """
+    Extract the first heading from a markdown or jupyter notebook file.
+    
+    Args:
+        file_path (str): Path to the file
+        
+    Returns:
+        str: The content of the first heading or filename if no heading found
+    """
+    try:
+        # Handle both .md and .ipynb files
+        if file_path.endswith('.ipynb'):
+            # For Jupyter notebooks, parse the JSON to find the first heading
+            with open(file_path, 'r', encoding='utf-8') as file:
+                notebook = json.load(file)
+                
+            # Look for the first markdown cell with a heading
+            for cell in notebook.get('cells', []):
+                if cell.get('cell_type') == 'markdown':
+                    content = ''.join(cell.get('source', []))
+                    heading_match = re.search(r'^#\s+(.+)$', content, re.MULTILINE)
+                    if heading_match:
+                        return heading_match.group(1).strip()
+        else:
+            # For markdown files
+            with open(file_path, 'r', encoding='utf-8') as file:
+                content = file.read()
+            
+            # Skip YAML frontmatter if it exists
+            content = re.sub(r'^---\n.*?\n---\n', '', content, flags=re.DOTALL)
+            
+            # Extract the first heading
+            heading_match = re.search(r'^#\s+(.+)$', content, re.MULTILINE)
+            if heading_match:
+                return heading_match.group(1).strip()
+    except Exception as e:
+        print(f"Error extracting heading from {file_path}: {e}")
+    
+    # If we couldn't find a heading, return the filename
+    return os.path.splitext(os.path.basename(file_path))[0]
+
+# ---- Citation Handling ----
+
+def format_authors_for_bibtex(authors):
+    """
+    Format a list of authors in the proper BibTeX format.
+    
+    Args:
+        authors (list): List of author dictionaries with 'given-names' and 'family-names'
+        
+    Returns:
+        str: Authors formatted for BibTeX
+    """
+    return " and ".join([f"{a.get('family-names', '')}, {a.get('given-names', '')}" for a in authors])
+
+def generate_citation_key(authors, title, year):
+    """
+    Generate a citation key for BibTeX.
+    
+    Args:
+        authors (list): List of author dictionaries
+        title (str): Title of the work
+        year (str): Year of publication
+        
+    Returns:
+        str: Citation key
+    """
+    first_author = authors[0] if authors else {'family-names': 'Unknown'}
+    title_words = title.split()
+    return f"{first_author.get('family-names', 'Unknown')}_{title_words[0] if title_words else 'Untitled'}_{year}"