greenmining 1.0.4__tar.gz → 1.0.6__tar.gz

{greenmining-1.0.4 → greenmining-1.0.6}/CHANGELOG.md

@@ -84,7 +84,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Pattern matching engine
 - Green awareness detection
 - Data analysis and reporting
-- CLI interface with Click
 - Docker support with multi-stage builds
 - GitHub Actions CI/CD pipeline
 - PyPI publishing workflow

{greenmining-1.0.4/greenmining.egg-info → greenmining-1.0.6}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: greenmining
-Version: 1.0.4
-Summary: Analyze GitHub repositories to identify green software engineering patterns and energy-efficient practices
+Version: 1.0.6
+Summary: An empirical Python library for Mining Software Repositories (MSR) in Green IT research
 Author-email: Adam Bouafia <a.bouafia@student.vu.nl>
 License: MIT
 Project-URL: Homepage, https://github.com/adam-bouafia/greenmining
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://github.com/adam-bouafia/greenmining#readme
 Project-URL: Repository, https://github.com/adam-bouafia/greenmining
 Project-URL: Issues, https://github.com/adam-bouafia/greenmining/issues
 Project-URL: Changelog, https://github.com/adam-bouafia/greenmining/blob/main/CHANGELOG.md
-Keywords: green-software,gsf,sustainability,carbon-footprint,microservices,mining,repository-analysis,energy-efficiency,github-analysis
+Keywords: green-software,gsf,msr,mining-software-repositories,green-it,sustainability,carbon-footprint,energy-efficiency,repository-analysis,github-analysis,pydriller,empirical-software-engineering
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -43,8 +43,13 @@ Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
 Requires-Dist: black>=23.12.0; extra == "dev"
 Requires-Dist: ruff>=0.1.9; extra == "dev"
 Requires-Dist: mypy>=1.8.0; extra == "dev"
-Requires-Dist: build>=1.0.4; extra == "dev"
+Requires-Dist: build>=1.0.5; extra == "dev"
 Requires-Dist: twine>=4.0.2; extra == "dev"
+Provides-Extra: energy
+Requires-Dist: psutil>=5.9.0; extra == "energy"
+Requires-Dist: codecarbon>=2.3.0; extra == "energy"
+Provides-Extra: dashboard
+Requires-Dist: flask>=3.0.0; extra == "dashboard"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.2.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
@@ -53,15 +58,30 @@ Dynamic: license-file
 
 # greenmining
 
-Green mining for microservices repositories.
+An empirical Python library for Mining Software Repositories (MSR) in Green IT research.
 
 [![PyPI](https://img.shields.io/pypi/v/greenmining)](https://pypi.org/project/greenmining/)
 [![Python](https://img.shields.io/pypi/pyversions/greenmining)](https://pypi.org/project/greenmining/)
 [![License](https://img.shields.io/github/license/adam-bouafia/greenmining)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://greenmining.readthedocs.io/)
 
 ## Overview
 
-`greenmining` is a Python library and CLI tool for analyzing GitHub repositories to identify green software engineering practices and energy-efficient patterns. It detects sustainable software patterns across cloud, web, AI, database, networking, and general categories.
+`greenmining` is a research-grade Python library designed for **empirical Mining Software Repositories (MSR)** studies in **Green IT**. It enables researchers and practitioners to:
+
+- **Mine repositories at scale** - Fetch and analyze GitHub repositories via GraphQL API with configurable filters
+- **Batch analysis with parallelism** - Analyze multiple repositories concurrently with configurable worker pools
+- **Classify green commits** - Detect 122 sustainability patterns from the Green Software Foundation (GSF) catalog
+- **Analyze any repository by URL** - Direct PyDriller-based analysis with support for private repositories
+- **Measure energy consumption** - RAPL, CodeCarbon, and CPU Energy Meter backends for power profiling
+- **Carbon footprint reporting** - CO2 emissions calculation with 20+ country profiles and cloud region support
+- **Power regression detection** - Identify commits that increased energy consumption
+- **Method-level analysis** - Per-method complexity and metrics via Lizard integration
+- **Version power comparison** - Compare power consumption across software versions
+- **Generate research datasets** - Statistical analysis, temporal trends, and publication-ready reports
+- **Web dashboard** - Flask-based interactive visualization of analysis results
+
+Whether you're conducting MSR research, analyzing green software adoption, or measuring the energy footprint of codebases, GreenMining provides the empirical toolkit you need.
 
 ## Installation
 
@@ -105,7 +125,7 @@ if is_green_aware(commit_msg):
     # Output: ['Cache Static Data', 'Use Efficient Cache Strategies']
 ```
 
-#### Fetch Repositories with Custom Keywords (NEW)
+#### Fetch Repositories with Custom Keywords
 
 ```python
 from greenmining import fetch_repositories
@@ -144,8 +164,6 @@ for repo in repos[:5]:
 ```python
 from greenmining.services.commit_extractor import CommitExtractor
 from greenmining.services.data_analyzer import DataAnalyzer
-from greenmining.analyzers.nlp_analyzer import NLPAnalyzer
-from greenmining.analyzers.ml_feature_extractor import MLFeatureExtractor
 from greenmining import fetch_repositories
 
 # Fetch repositories with custom keywords
@@ -195,18 +213,6 @@ for commit in commits:
         results.append(result)
         print(f"Green commit found: {commit.message[:50]}...")
         print(f"  Patterns: {result['known_pattern']}")
-        
-        # Access NLP analysis results (NEW)
-        if 'nlp_analysis' in result:
-            nlp = result['nlp_analysis']
-            print(f"  NLP: {nlp['morphological_count']} morphological matches, "
-                  f"{nlp['semantic_count']} semantic matches")
-        
-        # Access ML features (NEW)
-        if 'ml_features' in result:
-            ml = result['ml_features']['text']
-            print(f"  ML Features: {ml['word_count']} words, "
-                  f"keyword density: {ml['keyword_density']:.2f}")
 ```
 
 #### Access Sustainability Patterns Data
@@ -242,7 +248,7 @@ print(f"Available categories: {sorted(categories)}")
 #          'monitoring', 'network', 'networking', 'resource', 'web']
 ```
 
-#### Advanced Analysis: Temporal Trends (NEW)
+#### Advanced Analysis: Temporal Trends
 
 ```python
 from greenmining.services.data_aggregator import DataAggregator
@@ -374,7 +380,7 @@ repositories = fetch_repositories(
     min_stars=10,
     keywords="software engineering",
 )
-print(f"✓ Fetched {len(repositories)} repositories")
+print(f"Fetched {len(repositories)} repositories")
 
 # STAGE 2: Extract Commits
 print("\nExtracting commits...")
@@ -386,7 +392,7 @@ extractor = CommitExtractor(
     timeout=120,
 )
 all_commits = extractor.extract_from_repositories(repositories)
-print(f"✓ Extracted {len(all_commits)} commits")
+print(f"Extracted {len(all_commits)} commits")
 
 # Save commits
 extractor.save_results(
@@ -405,8 +411,8 @@ analyzed_commits = analyzer.analyze_commits(all_commits)
 # Count green-aware commits
 green_count = sum(1 for c in analyzed_commits if c.get("green_aware", False))
 green_percentage = (green_count / len(analyzed_commits) * 100) if analyzed_commits else 0
-print(f"✓ Analyzed {len(analyzed_commits)} commits")
-print(f"✓ Green-aware: {green_count} ({green_percentage:.1f}%)")
+print(f"Analyzed {len(analyzed_commits)} commits")
+print(f"Green-aware: {green_count} ({green_percentage:.1f}%)")
 
 # Save analysis
 analyzer.save_results(analyzed_commits, output_dir / "analyzed.json")
@@ -434,7 +440,7 @@ print("\n" + "="*80)
 print("ANALYSIS COMPLETE")
 print("="*80)
 aggregator.print_summary(results)
-print(f"\n📁 Results saved in: {output_dir.absolute()}")
+print(f"\nResults saved in: {output_dir.absolute()}")
 ```
 
 **What this example does:**
@@ -567,38 +573,44 @@ greenmining includes built-in energy measurement capabilities for tracking the c
 |---------|----------|---------|--------------|
 | **RAPL** | Linux (Intel/AMD) | CPU/RAM energy (Joules) | `/sys/class/powercap/` access |
 | **CodeCarbon** | Cross-platform | Energy + Carbon emissions (gCO2) | `pip install codecarbon` |
+| **CPU Meter** | All platforms | Estimated CPU energy (Joules) | Optional: `pip install psutil` |
+| **Auto** | All platforms | Best available backend | Automatic detection |
 
 #### Python API
 
 ```python
-from greenmining.energy import RAPLEnergyMeter, CodeCarbonMeter
-
-# RAPL (Linux only)
-rapl = RAPLEnergyMeter()
-if rapl.is_available():
-    rapl.start()
-    # ... run analysis ...
-    result = rapl.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-
-# CodeCarbon (cross-platform)
-cc = CodeCarbonMeter()
-if cc.is_available():
-    cc.start()
-    # ... run analysis ...
-    result = cc.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-    print(f"Carbon: {result.carbon_grams:.4f} gCO2")
+from greenmining.energy import RAPLEnergyMeter, CPUEnergyMeter, get_energy_meter
+
+# Auto-detect best backend
+meter = get_energy_meter("auto")
+meter.start()
+# ... run analysis ...
+result = meter.stop()
+print(f"Energy: {result.joules:.2f} J")
+print(f"Power: {result.watts_avg:.2f} W")
+
+# Integrated energy tracking during analysis
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+analyzer = LocalRepoAnalyzer(energy_tracking=True, energy_backend="auto")
+result = analyzer.analyze_repository("https://github.com/pallets/flask")
+print(f"Analysis energy: {result.energy_metrics['joules']:.2f} J")
 ```
 
-#### Experiment Results
+#### Carbon Footprint Reporting
+
+```python
+from greenmining.energy import CarbonReporter
 
-CodeCarbon was verified with a real experiment:
-- **Repository**: flask (pallets/flask)
-- **Commits analyzed**: 10
-- **Energy measured**: 160.6 J
-- **Carbon emissions**: 0.0119 gCO2
-- **Duration**: 11.28 seconds
+reporter = CarbonReporter(
+    country_iso="USA",
+    cloud_provider="aws",
+    region="us-east-1",
+)
+report = reporter.generate_report(total_joules=3600.0)
+print(f"CO2: {report.total_emissions_kg * 1000:.4f} grams")
+print(f"Equivalent: {report.tree_months:.2f} tree-months to offset")
+```
 
 ### Pattern Database
 
@@ -700,8 +712,7 @@ ruff check greenmining/ tests/
 - Python 3.9+
 - PyGithub >= 2.1.1
 - PyDriller >= 2.5
-- pandas >= 2.2.0
-- click >= 8.1.7
+- pandas >= 2.2.0 
 - codecarbon >= 2.0.0 (optional, for cross-platform energy measurement)
 
 ## License

{greenmining-1.0.4 → greenmining-1.0.6}/README.md

@@ -1,14 +1,29 @@
 # greenmining
 
-Green mining for microservices repositories.
+An empirical Python library for Mining Software Repositories (MSR) in Green IT research.
 
 [![PyPI](https://img.shields.io/pypi/v/greenmining)](https://pypi.org/project/greenmining/)
 [![Python](https://img.shields.io/pypi/pyversions/greenmining)](https://pypi.org/project/greenmining/)
 [![License](https://img.shields.io/github/license/adam-bouafia/greenmining)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://greenmining.readthedocs.io/)
 
 ## Overview
 
-`greenmining` is a Python library and CLI tool for analyzing GitHub repositories to identify green software engineering practices and energy-efficient patterns. It detects sustainable software patterns across cloud, web, AI, database, networking, and general categories.
+`greenmining` is a research-grade Python library designed for **empirical Mining Software Repositories (MSR)** studies in **Green IT**. It enables researchers and practitioners to:
+
+- **Mine repositories at scale** - Fetch and analyze GitHub repositories via GraphQL API with configurable filters
+- **Batch analysis with parallelism** - Analyze multiple repositories concurrently with configurable worker pools
+- **Classify green commits** - Detect 122 sustainability patterns from the Green Software Foundation (GSF) catalog
+- **Analyze any repository by URL** - Direct PyDriller-based analysis with support for private repositories
+- **Measure energy consumption** - RAPL, CodeCarbon, and CPU Energy Meter backends for power profiling
+- **Carbon footprint reporting** - CO2 emissions calculation with 20+ country profiles and cloud region support
+- **Power regression detection** - Identify commits that increased energy consumption
+- **Method-level analysis** - Per-method complexity and metrics via Lizard integration
+- **Version power comparison** - Compare power consumption across software versions
+- **Generate research datasets** - Statistical analysis, temporal trends, and publication-ready reports
+- **Web dashboard** - Flask-based interactive visualization of analysis results
+
+Whether you're conducting MSR research, analyzing green software adoption, or measuring the energy footprint of codebases, GreenMining provides the empirical toolkit you need.
 
 ## Installation
 
@@ -52,7 +67,7 @@ if is_green_aware(commit_msg):
     # Output: ['Cache Static Data', 'Use Efficient Cache Strategies']
 ```
 
-#### Fetch Repositories with Custom Keywords (NEW)
+#### Fetch Repositories with Custom Keywords
 
 ```python
 from greenmining import fetch_repositories
@@ -91,8 +106,6 @@ for repo in repos[:5]:
 ```python
 from greenmining.services.commit_extractor import CommitExtractor
 from greenmining.services.data_analyzer import DataAnalyzer
-from greenmining.analyzers.nlp_analyzer import NLPAnalyzer
-from greenmining.analyzers.ml_feature_extractor import MLFeatureExtractor
 from greenmining import fetch_repositories
 
 # Fetch repositories with custom keywords
@@ -142,18 +155,6 @@ for commit in commits:
         results.append(result)
         print(f"Green commit found: {commit.message[:50]}...")
         print(f"  Patterns: {result['known_pattern']}")
-        
-        # Access NLP analysis results (NEW)
-        if 'nlp_analysis' in result:
-            nlp = result['nlp_analysis']
-            print(f"  NLP: {nlp['morphological_count']} morphological matches, "
-                  f"{nlp['semantic_count']} semantic matches")
-        
-        # Access ML features (NEW)
-        if 'ml_features' in result:
-            ml = result['ml_features']['text']
-            print(f"  ML Features: {ml['word_count']} words, "
-                  f"keyword density: {ml['keyword_density']:.2f}")
 ```
 
 #### Access Sustainability Patterns Data
@@ -189,7 +190,7 @@ print(f"Available categories: {sorted(categories)}")
 #          'monitoring', 'network', 'networking', 'resource', 'web']
 ```
 
-#### Advanced Analysis: Temporal Trends (NEW)
+#### Advanced Analysis: Temporal Trends
 
 ```python
 from greenmining.services.data_aggregator import DataAggregator
@@ -321,7 +322,7 @@ repositories = fetch_repositories(
     min_stars=10,
     keywords="software engineering",
 )
-print(f"✓ Fetched {len(repositories)} repositories")
+print(f"Fetched {len(repositories)} repositories")
 
 # STAGE 2: Extract Commits
 print("\nExtracting commits...")
@@ -333,7 +334,7 @@ extractor = CommitExtractor(
     timeout=120,
 )
 all_commits = extractor.extract_from_repositories(repositories)
-print(f"✓ Extracted {len(all_commits)} commits")
+print(f"Extracted {len(all_commits)} commits")
 
 # Save commits
 extractor.save_results(
@@ -352,8 +353,8 @@ analyzed_commits = analyzer.analyze_commits(all_commits)
 # Count green-aware commits
 green_count = sum(1 for c in analyzed_commits if c.get("green_aware", False))
 green_percentage = (green_count / len(analyzed_commits) * 100) if analyzed_commits else 0
-print(f"✓ Analyzed {len(analyzed_commits)} commits")
-print(f"✓ Green-aware: {green_count} ({green_percentage:.1f}%)")
+print(f"Analyzed {len(analyzed_commits)} commits")
+print(f"Green-aware: {green_count} ({green_percentage:.1f}%)")
 
 # Save analysis
 analyzer.save_results(analyzed_commits, output_dir / "analyzed.json")
@@ -381,7 +382,7 @@ print("\n" + "="*80)
 print("ANALYSIS COMPLETE")
 print("="*80)
 aggregator.print_summary(results)
-print(f"\n📁 Results saved in: {output_dir.absolute()}")
+print(f"\nResults saved in: {output_dir.absolute()}")
 ```
 
 **What this example does:**
@@ -514,38 +515,44 @@ greenmining includes built-in energy measurement capabilities for tracking the c
 |---------|----------|---------|--------------|
 | **RAPL** | Linux (Intel/AMD) | CPU/RAM energy (Joules) | `/sys/class/powercap/` access |
 | **CodeCarbon** | Cross-platform | Energy + Carbon emissions (gCO2) | `pip install codecarbon` |
+| **CPU Meter** | All platforms | Estimated CPU energy (Joules) | Optional: `pip install psutil` |
+| **Auto** | All platforms | Best available backend | Automatic detection |
 
 #### Python API
 
 ```python
-from greenmining.energy import RAPLEnergyMeter, CodeCarbonMeter
-
-# RAPL (Linux only)
-rapl = RAPLEnergyMeter()
-if rapl.is_available():
-    rapl.start()
-    # ... run analysis ...
-    result = rapl.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-
-# CodeCarbon (cross-platform)
-cc = CodeCarbonMeter()
-if cc.is_available():
-    cc.start()
-    # ... run analysis ...
-    result = cc.stop()
-    print(f"Energy: {result.energy_joules:.2f} J")
-    print(f"Carbon: {result.carbon_grams:.4f} gCO2")
+from greenmining.energy import RAPLEnergyMeter, CPUEnergyMeter, get_energy_meter
+
+# Auto-detect best backend
+meter = get_energy_meter("auto")
+meter.start()
+# ... run analysis ...
+result = meter.stop()
+print(f"Energy: {result.joules:.2f} J")
+print(f"Power: {result.watts_avg:.2f} W")
+
+# Integrated energy tracking during analysis
+from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+analyzer = LocalRepoAnalyzer(energy_tracking=True, energy_backend="auto")
+result = analyzer.analyze_repository("https://github.com/pallets/flask")
+print(f"Analysis energy: {result.energy_metrics['joules']:.2f} J")
 ```
 
-#### Experiment Results
+#### Carbon Footprint Reporting
+
+```python
+from greenmining.energy import CarbonReporter
 
-CodeCarbon was verified with a real experiment:
-- **Repository**: flask (pallets/flask)
-- **Commits analyzed**: 10
-- **Energy measured**: 160.6 J
-- **Carbon emissions**: 0.0119 gCO2
-- **Duration**: 11.28 seconds
+reporter = CarbonReporter(
+    country_iso="USA",
+    cloud_provider="aws",
+    region="us-east-1",
+)
+report = reporter.generate_report(total_joules=3600.0)
+print(f"CO2: {report.total_emissions_kg * 1000:.4f} grams")
+print(f"Equivalent: {report.tree_months:.2f} tree-months to offset")
+```
 
 ### Pattern Database
 
@@ -647,8 +654,7 @@ ruff check greenmining/ tests/
 - Python 3.9+
 - PyGithub >= 2.1.1
 - PyDriller >= 2.5
-- pandas >= 2.2.0
-- click >= 8.1.7
+- pandas >= 2.2.0 
 - codecarbon >= 2.0.0 (optional, for cross-platform energy measurement)
 
 ## License

greenmining-1.0.6/greenmining/__init__.py

@@ -0,0 +1,87 @@
+# Green Microservices Mining - GSF Pattern Analysis Tool.
+
+from greenmining.config import Config
+from greenmining.controllers.repository_controller import RepositoryController
+from greenmining.gsf_patterns import (
+    GREEN_KEYWORDS,
+    GSF_PATTERNS,
+    get_pattern_by_keywords,
+    is_green_aware,
+)
+
+__version__ = "1.0.6"
+
+
+def fetch_repositories(
+    github_token: str,
+    max_repos: int = None,
+    min_stars: int = None,
+    languages: list = None,
+    keywords: str = None,
+):
+    # Fetch repositories from GitHub with custom search keywords.
+    config = Config()
+    config.GITHUB_TOKEN = github_token
+    controller = RepositoryController(config)
+
+    return controller.fetch_repositories(
+        max_repos=max_repos,
+        min_stars=min_stars,
+        languages=languages,
+        keywords=keywords,
+    )
+
+
+def analyze_repositories(
+    urls: list,
+    max_commits: int = 500,
+    parallel_workers: int = 1,
+    output_format: str = "dict",
+    energy_tracking: bool = False,
+    energy_backend: str = "rapl",
+    method_level_analysis: bool = False,
+    include_source_code: bool = False,
+    ssh_key_path: str = None,
+    github_token: str = None,
+):
+    # Analyze multiple repositories from URLs.
+    # Args:
+    #   urls: List of GitHub repository URLs
+    #   max_commits: Maximum commits to analyze per repository
+    #   parallel_workers: Number of parallel analysis workers (1=sequential)
+    #   output_format: Output format (dict, json, csv)
+    #   energy_tracking: Enable automatic energy measurement during analysis
+    #   energy_backend: Energy backend (rapl, codecarbon, cpu_meter, auto)
+    #   method_level_analysis: Include per-method metrics via Lizard
+    #   include_source_code: Include source code before/after in results
+    #   ssh_key_path: SSH key path for private repositories
+    #   github_token: GitHub token for private HTTPS repositories
+    from greenmining.services.local_repo_analyzer import LocalRepoAnalyzer
+
+    analyzer = LocalRepoAnalyzer(
+        max_commits=max_commits,
+        energy_tracking=energy_tracking,
+        energy_backend=energy_backend,
+        method_level_analysis=method_level_analysis,
+        include_source_code=include_source_code,
+        ssh_key_path=ssh_key_path,
+        github_token=github_token,
+    )
+
+    return analyzer.analyze_repositories(
+        urls=urls,
+        parallel_workers=parallel_workers,
+        output_format=output_format,
+    )
+
+
+__all__ = [
+    "Config",
+    "GSF_PATTERNS",
+    "GREEN_KEYWORDS",
+    "is_green_aware",
+    "get_pattern_by_keywords",
+    "fetch_repositories",
+    "analyze_repositories",
+    "__version__",
+]

{greenmining-1.0.4 → greenmining-1.0.6}/greenmining/__version__.py

@@ -1,3 +1,3 @@
 # Version information for greenmining.
 
-__version__ = "1.0.4"
+__version__ = "1.0.5"

greenmining-1.0.6/greenmining/analyzers/__init__.py

@@ -0,0 +1,22 @@
+# Analyzers for GreenMining framework.
+
+from .code_diff_analyzer import CodeDiffAnalyzer
+from .statistical_analyzer import StatisticalAnalyzer
+from .temporal_analyzer import TemporalAnalyzer
+from .qualitative_analyzer import QualitativeAnalyzer
+from .power_regression import PowerRegressionDetector, PowerRegression
+from .metrics_power_correlator import MetricsPowerCorrelator, CorrelationResult
+from .version_power_analyzer import VersionPowerAnalyzer, VersionPowerReport
+
+__all__ = [
+    "CodeDiffAnalyzer",
+    "StatisticalAnalyzer",
+    "TemporalAnalyzer",
+    "QualitativeAnalyzer",
+    "PowerRegressionDetector",
+    "PowerRegression",
+    "MetricsPowerCorrelator",
+    "CorrelationResult",
+    "VersionPowerAnalyzer",
+    "VersionPowerReport",
+]