github-growth-plotter 0.1.0__py3-none-any.whl

github_growth_plotter/__init__.py

@@ -0,0 +1,2 @@
+# GitHub Growth Plotter
+__version__ = "0.1.0"

github_growth_plotter/cli.py

@@ -0,0 +1,189 @@
+import argparse
+import subprocess
+import requests
+import csv
+import os
+import sys
+from datetime import datetime
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+
+def get_github_token():
+    try:
+        result = subprocess.run(['gh', 'auth', 'token'], capture_output=True, text=True, check=True)
+        return result.stdout.strip()
+    except subprocess.CalledProcessError:
+        print("Error: Could not retrieve GitHub token. Ensure you are logged in using 'gh auth login'.")
+        sys.exit(1)
+    except FileNotFoundError:
+         # Fallback to env var if gh not found
+         token = os.environ.get("GITHUB_TOKEN")
+         if not token:
+             print("Error: 'gh' CLI not found and GITHUB_TOKEN environment variable not set.")
+             sys.exit(1)
+         return token
+
+def get_current_repo():
+    try:
+        # First try using gh CLI
+        result = subprocess.run(['gh', 'repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner'], capture_output=True, text=True, check=True)
+        return result.stdout.strip()
+    except subprocess.CalledProcessError:
+        try:
+             # Fallback to git remote parsing
+             result = subprocess.run(['git', 'config', '--get', 'remote.origin.url'], capture_output=True, text=True, check=True)
+             url = result.stdout.strip()
+             # Extract owner/repo from url
+             if url.startswith("git@github.com:"):
+                 return url[15:].replace('.git', '')
+             elif url.startswith("https://github.com/"):
+                 return url[19:].replace('.git', '')
+             else:
+                 print("Error: Could not determine current repository from git remote.")
+                 sys.exit(1)
+        except Exception as e:
+             print("Error: Could not determine current repository. Are you in a git repository?")
+             sys.exit(1)
+    except FileNotFoundError:
+        print("Error: Required command line tool 'gh' or 'git' not found.")
+        sys.exit(1)
+
+def fetch_stargazers(repo, token):
+    url = f"https://api.github.com/repos/{repo}/stargazers"
+    headers = {
+        "Accept": "application/vnd.github.v3.star+json",
+        "Authorization": f"Bearer {token}",
+        "X-GitHub-Api-Version": "2022-11-28"
+    }
+    
+    stargazers = []
+    page = 1
+    per_page = 100
+    
+    print(f"Fetching stargazers for {repo}...")
+    while True:
+        params = {"page": page, "per_page": per_page}
+        response = requests.get(url, headers=headers, params=params)
+        
+        if response.status_code != 200:
+            print(f"Error fetching stargazers: {response.status_code} {response.text}")
+            sys.exit(1)
+            
+        data = response.json()
+        if not data:
+            break
+            
+        for item in data:
+            stargazers.append({
+                "user": item["user"]["login"],
+                "starred_at": item["starred_at"]
+            })
+            
+        if "next" not in response.links:
+            break
+        page += 1
+        
+    return stargazers
+
+def save_to_csv(stargazers, filename):
+    with open(filename, mode='w', newline='', encoding='utf-8') as file:
+        writer = csv.DictWriter(file, fieldnames=["user", "starred_at"])
+        writer.writeheader()
+        for stargazer in stargazers:
+            writer.writerow(stargazer)
+    print(f"Saved {len(stargazers)} stargazers to {filename}")
+
+def plot_growth(stargazers, filename, repo):
+    dates = [datetime.strptime(s["starred_at"], "%Y-%m-%dT%H:%M:%SZ") for s in stargazers]
+    dates.sort()
+    
+    counts = list(range(1, len(dates) + 1))
+    
+    plt.figure(figsize=(10, 6))
+    plt.plot(dates, counts, marker='', linestyle='-', color='b')
+    
+    plt.title(f"Stargazers Growth for {repo}")
+    plt.xlabel("Date")
+    plt.ylabel("Number of Stargazers")
+    
+    # Format the x-axis to show dates nicely
+    plt.gca().xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))
+    plt.gca().xaxis.set_major_locator(mdates.AutoDateLocator())
+    plt.gcf().autofmt_xdate()
+    
+    plt.grid(True)
+    plt.tight_layout()
+    plt.savefig(filename)
+    print(f"Saved growth plot to {filename}")
+
+def update_gitignore(filename):
+    if os.path.exists('.gitignore'):
+        with open('.gitignore', 'r', encoding='utf-8') as f:
+            content = f.read()
+            if filename in content.splitlines():
+                return
+        with open('.gitignore', 'a', encoding='utf-8') as f:
+            if content and not content.endswith('\n'):
+                f.write('\n')
+            f.write(f"{filename}\n")
+    else:
+        with open('.gitignore', 'w', encoding='utf-8') as f:
+            f.write(f"{filename}\n")
+    print(f"Added {filename} to .gitignore")
+
+def publish_to_readme(plot_filename, repo):
+    readme_path = "README.md"
+    basename = os.path.basename(plot_filename)
+    img_path = f"./assets/{basename}"
+    
+    html_snippet = f'\n<p align="center">\n  <img src="{img_path}" alt="{repo}" width="100%" />\n</p>\n'
+    
+    if os.path.exists(readme_path):
+        with open(readme_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        if basename not in content:
+            with open(readme_path, 'a', encoding='utf-8') as f:
+                if content and not content.endswith('\n'):
+                    f.write('\n')
+                f.write(html_snippet)
+            print(f"Published plot to {readme_path}")
+        else:
+            print(f"Plot already seems to be published in {readme_path}")
+    else:
+        with open(readme_path, 'w', encoding='utf-8') as f:
+            f.write(html_snippet.lstrip())
+        print(f"Created {readme_path} and published plot")
+
+def main():
+    parser = argparse.ArgumentParser(description="Fetch stargazers and plot growth.")
+    parser.add_argument("repo", nargs="?", help="GitHub repository in owner/repo format. If not provided, uses the current repository.")
+    parser.add_argument("--publish", action="store_true", help="Auto publish the plot to the current README.md")
+    args = parser.parse_args()
+    
+    repo = args.repo
+    if not repo:
+        repo = get_current_repo()
+        
+    token = get_github_token()
+    
+    stargazers = fetch_stargazers(repo, token)
+    
+    if not stargazers:
+        print("No stargazers found or repository does not exist.")
+        sys.exit(0)
+        
+    safe_repo_name = repo.replace('/', '_')
+    csv_filename = f"{safe_repo_name}_stargazers.csv"
+    
+    os.makedirs("assets", exist_ok=True)
+    plot_filename = os.path.join("assets", f"{safe_repo_name}_growth.svg")
+    
+    save_to_csv(stargazers, csv_filename)
+    update_gitignore(csv_filename)
+    plot_growth(stargazers, plot_filename, repo)
+    
+    if args.publish:
+        publish_to_readme(plot_filename, repo)
+
+if __name__ == "__main__":
+    main()

github_growth_plotter-0.1.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: github-growth-plotter
+Version: 0.1.0
+Summary: A tool to fetch GitHub stargazers and plot growth over time.
+Author: Open Source Maintainers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: matplotlib
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<div align="center">
+  <img src="./assets/banner.svg" alt="GitHub Stargazers Growth Plotter Banner" width="100%">
+</div>
+
+# 📈 GitHub Stargazers Growth Plotter
+
+<div align="center">
+
+[![Python](https://img.shields.io/badge/Python-3.x-blue?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![GitHub CLI](https://img.shields.io/badge/GitHub%20CLI-Required-black?style=for-the-badge&logo=github&logoColor=white)](https://cli.github.com/)
+[![Matplotlib](https://img.shields.io/badge/Matplotlib-Supported-orange?style=for-the-badge)](https://matplotlib.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+</div>
+
+> **Note:** As the stargazers API for 3rd party repos gets deprecated or restricted, repository owners can use this tool to easily fetch and publish their own repository's growth charts!
+
+🚀 **GitHub Stargazers Growth Plotter** is an automated tool that fetches the stargazers history of any GitHub repository, caches it locally, and generates a stunning SVG growth plot. Designed for repository owners, this script can auto-publish charts directly to your `README.md` for maximum visibility and better SEO indexing of project metrics.
+
+## ✨ Features
+
+- 🔐 **Automated Authentication**: Seamlessly integrates with your active GitHub CLI (`gh`) token. Zero manual token configuration required!
+- 🎯 **Zero-Config Context**: Automatically detects your current repository from your git config if run without arguments.
+- 🗄️ **Local Caching**: Caches historical stargazer data in a CSV file and dynamically appends it to your `.gitignore` to prevent accidental commits.
+- 📊 **High-Quality Plotting**: Renders beautiful, scalable vector `.svg` plots optimized for web display, saving them cleanly in an `assets/` directory.
+- 📝 **Auto-Publishing**: With a simple flag, automatically inject your latest growth chart into your `README.md` within a perfectly centered HTML block.
+
+## 🛠️ Prerequisites
+
+1. **Python 3.x**: Ensure Python is installed on your system.
+2. **GitHub CLI (`gh`)**: You must have the GitHub CLI installed and authenticated.
+   ```bash
+   gh auth login
+   ```
+3. **Installation**:
+   Install the tool via PyPI:
+   ```bash
+   pip install github-growth-plotter
+   ```
+   *(To install from source locally, clone the repo and run `pip install .`)*
+
+## 🚀 Usage Guide
+
+### 1️⃣ Run for the current repository
+If you are already inside a Git repository folder, you can simply run:
+```bash
+github-growth-plot
+```
+This detects the repository, downloads the stargazers to a CSV, and outputs the SVG plot in the `assets/` directory.
+
+### 2️⃣ Run for a specific repository
+You can specify any repository using the standard `owner/repo` format:
+```bash
+github-growth-plot "google/jax"
+```
+
+### 3️⃣ Auto-publish to README
+Want to display the chart on your project's main page? Pass the `--publish` flag:
+```bash
+github-growth-plot --publish
+```
+This automatically appends the following HTML snippet to the bottom of your `README.md`:
+```html
+<p align="center">
+  <img src="./assets/<username>_<reponame>_growth.svg" alt="<owner>/<repo>" width="100%" />
+</p>
+```
+
+## 📂 Generated Files
+
+When executed, the script generates and manages the following files:
+- 🖼️ **`assets/<username>_<reponame>_growth.svg`**: The generated vector graph showing star growth over time.
+- 📄 **`<username>_<reponame>_stargazers.csv`**: Raw historical star data (automatically ignored via `.gitignore`).
+- 🙈 **`.gitignore`**: Updated automatically to ignore the generated CSV file.
+
+---
+*Made with ❤️ for Open Source Maintainers.*
+

github_growth_plotter-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+github_growth_plotter/__init__.py,sha256=AoM7mnMJBf91xMUQD3E6hxoTD3EEteiE0gulyzIbIGw,46
+github_growth_plotter/cli.py,sha256=0euDYtWC01oJt6cUcD_Yg77NQonw3Qup3rH1RnWTKbg,6832
+github_growth_plotter-0.1.0.dist-info/licenses/LICENSE,sha256=aMKES33CpfnVgmxv1FVtwDajlgzhPZ695UF8-E8rsy8,1068
+github_growth_plotter-0.1.0.dist-info/METADATA,sha256=EewdJYAxUm_lqa94j8jTEoFFbKAF3hHBjmpOsxYyYsw,4304
+github_growth_plotter-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+github_growth_plotter-0.1.0.dist-info/entry_points.txt,sha256=Z3m0SN3KLjTnF3m7EonTWKau_fc4oZWSmyLvb9ZMMuY,70
+github_growth_plotter-0.1.0.dist-info/top_level.txt,sha256=TEWCDu-4GmSdG4BfBpAum7uW9qARSqTUwxap9ztTfS0,22
+github_growth_plotter-0.1.0.dist-info/RECORD,,

github_growth_plotter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

github_growth_plotter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+github-growth-plot = github_growth_plotter.cli:main

github_growth_plotter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ishan Dutta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

github_growth_plotter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+github_growth_plotter