osslag 1.0.0__py3-none-any.whl

osslag/metrics/pvac.py

@@ -0,0 +1,166 @@
+"""Semantic Version Activity Categorizer (PVAC)
+
+Author:
+    Shane Panter and Luke Hindman
+
+Description:
+    This module provides a set of functions for categorizeing version strings
+    based on the official and extended semantic versioning policies. The module
+    also provides a function for calculating the version delta between two
+    packages based on the weighted sum of the major, minor, and patch version
+    numbers.
+"""
+
+import re
+
+"""Regular expression patterns for matching version strings"""
+version_mapping = [
+    # Official Semantic
+    {
+        "pattern": re.compile(
+            r"^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+        ),
+        "class_group": "Semantic",
+    },
+    # ExtendedSemantic: Match epoch prepended to version string based upon official versioning policy
+    {
+        "pattern": re.compile(
+            r"^((?P<epoch>0|[1-9]\d*):)?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+        ),
+        "class_group": "Extended-Semantic",
+    },
+    # Semi-Semantic: Allow version numbers to start with 0; Make the patch field optional and separated by either a . or a lower case p
+    {
+        "pattern": re.compile(
+            r"^((?P<epoch>0|[1-9]\d*):)?(?P<major>[0-9]\d*)\.(?P<minor>[0-9]\d*)((\.|p|pl)(?P<patch>[0-9]\d*))?(?:-(?P<prerelease>(?:[0-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:[0-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+        ),
+        "class_group": "Semi-Semantic",
+    },
+]
+
+
+def lookup_category(version_string):
+    """Given a version string, return a dictionary containing the category
+
+    Args:
+        version_string (string): The version string to categorize
+
+    Returns:
+        dict: A dictionary containing the category information
+
+    """
+    # Clean the string for standardized processing
+    version_string = version_string.strip()
+
+    version_dict = {
+        "category": None,
+        "epoch": None,
+        "major": None,
+        "minor": None,
+        "patch": None,
+    }
+    for map in version_mapping:
+        m = map["pattern"].match(version_string.strip())
+        if m is not None:
+            version_dict = {}
+            if "epoch" not in m.groupdict().keys() or m.groupdict()["epoch"] is None:
+                version_dict["epoch"] = 0
+            else:
+                version_dict["epoch"] = int(m.groupdict()["epoch"])
+
+            if "major" not in m.groupdict().keys() or m.groupdict()["major"] is None:
+                version_dict["major"] = 0
+            else:
+                version_dict["major"] = int(m.groupdict()["major"])
+
+            if "minor" not in m.groupdict().keys() or m.groupdict()["minor"] is None:
+                version_dict["minor"] = 0
+            else:
+                version_dict["minor"] = int(m.groupdict()["minor"])
+
+            if "patch" not in m.groupdict().keys() or m.groupdict()["patch"] is None:
+                version_dict["patch"] = 0
+            else:
+                version_dict["patch"] = int(m.groupdict()["patch"])
+
+            version_dict["category"] = map["class_group"]
+            break
+    return version_dict
+
+
+def version_delta(packages, major_weight, minor_weight, patch_weight):
+    """Calculate the version delta between two packages based on the weighted
+        sum of the major, minor, and patch version numbers.
+
+    Args:
+        packages (tuple): A list of tuples containing version information
+        major_weight (float): The weight to apply to the major version number
+        minor_weight (float): The weight to apply to the minor version number
+        patch_weight (float): The weight to apply to the patch version number
+
+    Returns:
+        type: A single value representing the sum of the weighted version deltas
+
+    """
+    version_delta = 0
+
+    for version_tuple_A, version_tuple_B in packages:
+        # Destructure the version tuples
+        semanticA, epochA, majorA, minorA, patchA = version_tuple_A
+        semanticB, epochB, majorB, minorB, patchB = version_tuple_B
+
+        if epochA != epochB:
+            continue
+
+        if semanticA == "Unknown" or semanticB == "Unknown":
+            continue
+
+        weighted_version_A = (
+            (majorA * major_weight) + (minorA * minor_weight) + (patchA * patch_weight)
+        )
+        weighted_version_B = (
+            (majorB * major_weight) + (minorB * minor_weight) + (patchB * patch_weight)
+        )
+        version_delta += abs(weighted_version_B - weighted_version_A)
+
+    return version_delta
+
+
+def categorize_development_activity(version_string_A, version_string_B):
+    """Calculate the development activity level between two version strings
+
+    Args:
+        version_string_A (string): The first version string to compare
+        version_string_B (string): The second version string to compare
+
+    Returns:
+        string: A string representing the development activity level between
+        the two version strings
+
+    """
+    class_A_dict = lookup_category(version_string_A)
+    class_B_dict = lookup_category(version_string_B)
+
+    if (
+        class_A_dict["category"] == "Unknown"
+        or class_A_dict["category"] is None
+        or class_B_dict["category"] == "Unknown"
+        or class_B_dict["category"] is None
+    ):
+        return "Unknown"
+
+    if class_A_dict["epoch"] != class_B_dict["epoch"]:
+        return "Unknown"
+
+    activity_level = "Unknown"
+
+    if class_A_dict["major"] != class_B_dict["major"]:
+        activity_level = "Very Active"
+    elif class_A_dict["minor"] != class_B_dict["minor"]:
+        activity_level = "Moderately Active"
+    elif class_A_dict["patch"] != class_B_dict["patch"]:
+        activity_level = "Lightly Active"
+    else:
+        activity_level = "Sedentary"
+
+    return activity_level

osslag/utils/github_helper.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime, timedelta
+from typing import NamedTuple
+
+import pandas as pd
+import requests
+from dotenv import load_dotenv
+from github import Github
+from github.GithubException import GithubException
+
+from osslag.utils import vcs
+
+load_dotenv()  # Load environment variables from .env file if present
+logger = logging.getLogger(__name__)
+
+# Suppress overly verbose logging from urllib3 and requests
+logging.getLogger("urllib3").setLevel(logging.CRITICAL)
+logging.getLogger("requests").setLevel(logging.CRITICAL)
+
+# Redirect PyGithub's logging to a file for debugging
+github_logger = logging.getLogger("github")
+filer_handler = logging.FileHandler("github_debug.log")
+filer_handler.setLevel(logging.INFO)
+github_logger.addHandler(filer_handler)
+github_logger.setLevel(logging.CRITICAL)
+
+
+class GithubAPIResult(NamedTuple):
+    success: bool
+    data: dict | None
+    error: str | None
+
+
+def gh_get_rate_limit_info(github_token: str | None = None) -> dict | None:
+    """Retrieve GitHub API rate limit information.
+
+    Args:
+        github_token: Optional GitHub Personal Access Token. If not provided,
+                      uses unauthenticated access limits.
+
+    Returns:
+        A dictionary with keys: 'limit', 'remaining', 'reset_datetime', 'authenticated'.
+        Returns None on error.
+
+    """
+    try:
+        gh = Github(github_token) if github_token else Github()
+        rate_limit = gh.get_rate_limit()
+        core = rate_limit.resources.core
+
+        # core.reset is a datetime object
+        reset_dt = (
+            core.reset
+            if isinstance(core.reset, datetime)
+            else datetime.fromtimestamp(core.reset)
+        )
+        # convert to local timezone
+        reset_dt = reset_dt.astimezone()
+        # convert to a naive datetime in local time
+        reset_dt = reset_dt.replace(tzinfo=None)
+
+        return {
+            "limit": core.limit,
+            "remaining": core.remaining,
+            "reset_datetime": reset_dt.strftime("%I:%M:%S %p"),
+            "authenticated": github_token is not None,
+        }
+    except GithubException:
+        return None
+    except Exception:
+        return None
+
+
+def fetch_pull_requests(
+    repo_url: str,
+    github_token: str | None = None,
+    state: str = "all",
+    months: int | None = None,
+) -> pd.DataFrame:
+    """Retrieve pull requests for a GitHub repository via the GitHub API.
+
+    Args:
+        repo_url: HTTPS URL to the repository (e.g., https://github.com/owner/repo[.git]).
+        github_token: Optional GitHub token for authenticated requests (higher rate limits, private repos).
+        state: Filter by PR state: 'open', 'closed', or 'all' (default 'all').
+        months: Optional limit to PRs created within the last N months (approx 30 days per month).
+
+    Returns:
+        A list of dictionaries with PR metadata: 'number', 'title', 'state', 'user', 'created_at',
+        'updated_at', 'closed_at', 'merged_at', 'html_url'. Returns None on error.
+
+    """
+    if months is not None and (not isinstance(months, int) or months < 1):
+        raise ValueError("months parameter must be a positive integer or None")
+
+    owner, repo = vcs.extract_owner_name_repo(repo_url)
+    github_token = github_token or os.getenv("GITHUB_TOKEN")
+    if owner is None or repo is None:
+        raise ValueError(f"Invalid GitHub repository URL: {repo_url}")
+
+    try:
+        gh = Github(github_token) if github_token else Github()
+        repo_obj = gh.get_repo(f"{owner}/{repo}")
+
+        # PyGithub supports state in {'open','closed','all'}
+        prs = repo_obj.get_pulls(state=state, sort="created", direction="desc")
+
+        cutoff = None
+        if months is not None:
+            cutoff = datetime.now() - timedelta(days=months * 30)
+
+        results: list[dict] = []
+        for pr in prs:
+            # Filter by months if requested
+            if cutoff is not None and pr.created_at < cutoff:
+                # Because we sorted desc by created time, we can stop early
+                break
+
+            results.append(
+                {
+                    "number": pr.number,
+                    "title": pr.title,
+                    "state": pr.state,
+                    "user": None if pr.user is None else pr.user.login,
+                    "created_at": pr.created_at.isoformat() if pr.created_at else None,
+                    "updated_at": pr.updated_at.isoformat() if pr.updated_at else None,
+                    "closed_at": pr.closed_at.isoformat() if pr.closed_at else None,
+                    "merged_at": pr.merged_at.isoformat() if pr.merged_at else None,
+                    "html_url": pr.html_url,
+                }
+            )
+
+        return pd.DataFrame(results)
+    except GithubException as e:
+        raise ValueError(f"GitHub API error: {e.data.get('message', str(e))}") from e
+    except Exception as e:
+        raise ValueError(f"Failed to fetch pull requests: {str(e)}") from e
+
+
+def gh_check_repo_exists(owner: str, repo: str) -> GithubAPIResult:
+    """Check if a GitHub repository exists via the API."""
+    github_token = os.getenv("GITHUB_TOKEN")
+
+    if github_token:
+        logger.debug("Using authenticated GitHub access")
+    else:
+        logger.warning("Using unauthenticated GitHub access (60 req/hr limit)")
+
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+    headers = {"Accept": "application/vnd.github.v3+json"}
+    if github_token:
+        headers["Authorization"] = f"Bearer {github_token}"
+
+    try:
+        response = requests.get(url, headers=headers, timeout=30)
+
+        if response.status_code == 200:
+            return GithubAPIResult(data=None, error=None, success=True)
+
+        # Handle rate limiting explicitly
+        if response.status_code == 403:
+            remaining = response.headers.get("X-RateLimit-Remaining", "?")
+            reset_time_str = response.headers.get("X-RateLimit-Reset", "")
+            error_msg = (
+                f"Rate limited (remaining: {remaining}, resets: {reset_time_str})"
+            )
+            return GithubAPIResult(
+                data={"owner": owner, "repo": repo},
+                error=error_msg,
+                success=False,
+            )
+
+        # Handle actual not found
+        if response.status_code == 404:
+            error_msg = f"404 Not Found: {url}"
+            try:
+                error_data = response.json()
+                if "message" in error_data:
+                    error_msg = error_data["message"]
+            except Exception:
+                pass
+            return GithubAPIResult(
+                data={"owner": owner, "repo": repo}, error=error_msg, success=False
+            )
+
+        # Other errors
+        error_msg = f"HTTP {response.status_code}"
+        try:
+            error_data = response.json()
+            if "message" in error_data:
+                error_msg = error_data["message"]
+        except Exception:
+            pass
+        logger.warning(f"GitHub API error for {owner}/{repo}: {error_msg}")
+        return GithubAPIResult(
+            data={"owner": owner, "repo": repo}, error=error_msg, success=False
+        )
+    except requests.RequestException as e:
+        return GithubAPIResult(
+            data={"owner": owner, "repo": repo}, error=str(e), success=False
+        )
+
+
+def fetch_github_repo_metadata(
+    repo_url: str, github_token: str | None = None
+) -> pd.DataFrame:
+    """Fetch GitHub repo metadata given repo URL and token.
+
+    Handles rate limiting by catching RateLimitExceededException and waiting
+    for the reset time before retrying.
+    """
+    owner, repo = vcs.extract_owner_name_repo(repo_url)
+    github_token = github_token or os.getenv("GITHUB_TOKEN")
+    if owner is None or repo is None:
+        raise ValueError(f"Invalid repository URL: {repo_url}")
+
+    # Configure GitHub client with explicit timeout (30 seconds)
+    github_client = (
+        Github(github_token, timeout=30) if github_token else Github(timeout=30)
+    )
+    repo_obj = github_client.get_repo(f"{owner}/{repo}")
+    data = {
+        "repo_url": repo_url,
+        "full_name": repo_obj.full_name,
+        "description": repo_obj.description,
+        "stargazers_count": repo_obj.stargazers_count,
+        "forks_count": repo_obj.forks_count,
+        "open_issues_count": repo_obj.open_issues_count,
+        "watchers_count": repo_obj.watchers_count,
+        "created_at": repo_obj.created_at,
+        "updated_at": repo_obj.updated_at,
+        "pushed_at": repo_obj.pushed_at,
+        "archived": repo_obj.archived,
+        "license": str(repo_obj.license.spdx_id) if repo_obj.license else None,
+        "topics": ",".join(repo_obj.get_topics()),
+    }
+    return pd.DataFrame([data])