github-oss-contributions 0.3.1

Fetch organizations where a user created issues or PRs for Open Source

github-oss-contributions Package

github-oss-contributions is a Python package designed to fetch Open Source contributions the user has made in various reputed organizations to showcase on portfolio, resumes, etc.

✨ Why Use This Package?

• 🔗 Track your Open Source footprint across different organizations.

• 💼 Showcase your real OSS contributions easily in personal portfolios, resumes, or developer profiles.

• 🧠 Learn and reflect on your engagement with the open source community.

• 🛠️ Easily integrates into dashboards, static websites, or CLI tools.

📦 Perfect For:

• Developers building personal portfolios with dynamic OSS stats.

• Students applying for programs like GitHub Campus Experts, MLH Fellowships, or Google Summer of Code.

• Anyone who wants to track and display their OSS impact beautifully.

📋 Table of Contents

• Overview
• Features
• Installation
• Usage
• API Reference
• Advanced Usage
• Troubleshooting
• License
• Authors
• Contributing

Overview

github-oss-contributions is a Python package that allows you to discover and track your open source contributions across GitHub organizations. It retrieves information about issues and pull requests you've created in open source projects and organizes them by organization.

✨ Features

• Async & Fast: All network operations are fully asynchronous for best performance.
• Organization Discovery: Find all organizations where you've contributed
• Contribution Tracking: Separate lists of your issues and PRs for each organization
• Rich Metadata: Get organization avatars, profile URLs, and contribution details
• User-Friendly: Interactive CLI output with progress indicators
• GitHub API Integration: Uses GitHub's REST API with authentication support
• Robust Error Handling: Friendly messages and logging for network/API errors.
• Use Directly in CLI: You can directly use in CLI as well with simple cli command given below.

Installation

Option 1: Install from PyPI (Recommended)

pip install github-oss-contributions

Option 2: Install from Source

# Clone the repository
git clone https://github.com/org-name/github-oss-contributions.git
cd github-oss-contributions

# Install in development mode
pip install -e .

# Or install dependencies only
pip install -r requirements.txt

Usage

Basic Usage

from github_oss_contributions import GitHubOssContributions

# Initialize with your GitHub username
client = GitHubOssContributions(username="your_github_username")

# Get your contributions
org_data = client.get_contributions()
print(org_data)

# Pretty Print (rich installed)
client.print_contributions()

Using with GitHub Token (Recommended)

from github_oss_contributions import GitHubOssContributions

# Using a GitHub token increases API rate limits
client = GitHubOssContributions(username="your_github_username", token="YOUR_GITHUB_TOKEN")
org_data = client.get_contributions()
print("Contributions fetched successfully:")
print(org_data)

# pretty print (rich installed)
client.print_contributions()

CLI Usage

After installation, you can use the CLI tool directly from your terminal:

github-oss-contributions --username YOUR_GITHUB_USERNAME

With Github Token (Higher Rate limits):

github-oss-contributions --username YOUR_GITHUB_USERNAME --token YOUR_GITHUB_TOKEN

To print raw HSON data instaed of pretty outputs:

github-oss-contributions --username YOUR_GITHUB_USERNAME --token <your-github-token_OPTIONAL> --raw

📦 About

github-oss-contributions is a Python package to fetch organizations where a GitHub user has created issues or pull requests (PRs) in open source repositories. It helps you discover your open source impact across organizations.

Example Output

Data fetched Successfully! 

Org: xyz-org
Avatar: https://avatars.githubusercontent.com/u/25?v=4
Profile: https://github.com/xyz-org
Issues:
  - 🐛 Bug Report: Validation is not properly handled in the form.    
(https://github.com/xyz-org/website/issues/21)
Pull Requests:
  - docs: added type field in the documentation of package.json
(https://github.com/xyz-org/docs/pull/16)

--------------------------------

Summary:
Organizations: 10
Issues: 11
Pull Requests: 12

🧩 API Reference

GitHubOssContributions Class

Constructor

GitHubOssContributions(username, token=None)

Parameters:

• username (str): GitHub username to fetch contributions for
• token (str, optional): GitHub personal access token for authentication

Methods

get_contributions()

Fetches all issues and pull requests created by the user in organization repositories.

Returns: Dictionary with organization names as keys and contribution data as values:

print_contributions()

Pretty printing the output

Returns: Return the output in most arranged format with spatial color coding and highlighting.

🔍 Advanced Usage

Creating a GitHub Token

For better API rate limits, create a GitHub Personal Access Token:

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
2. Click "Generate new token"
3. Give it a name and set expiration
4. Select "Only select repositories" and choose repositories you want to analyze
5. For permissions, grant "Read-only" access to "Issues" and "Pull requests"
6. Click "Generate token" and copy it

Using in a Project

import os
from github_oss_contributions import GitHubOssContributions

# Use environment variables for sensitive tokens
token = os.environ.get("GITHUB_TOKEN")
client = GitHubOssContributions(username="your_github_username", token=token)
contributions = client.get_contributions()

# Process the contributions
total_orgs = len(contributions)
total_issues = sum(len(data['issues']) for data in contributions.values())
total_prs = sum(len(data['prs']) for data in contributions.values())

print(f"Contributed to {total_orgs} organizations")
print(f"Created {total_issues} issues and {total_prs} pull requests")

⚠️ Troubleshooting

API Rate Limits

If you encounter rate limiting errors:

1. Use a GitHub personal access token
2. Make fewer requests in a short time period
3. Check your rate limit status: https://api.github.com/rate_limit

Common Issues

• Authentication Errors: Verify your token has required permissions
• No Results: Confirm the username is correct and has public activity
• Connection Issues: Check your network connection

📝 License

MIT License

👤 Authors

• Mohit Upadhyay
• Anuj Kumar Upadhyay

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request