PYTHON LIBRARY

ghprofile

A lightweight Python library for fetching and summarizing GitHub profile and repository data through a simple Python interface.

Python
GitHub API
PyPI

View on GitHub View on PyPI

install it, import it, query it

THE IDEA

THE IDEA.

ghprofile was created as a lightweight abstraction around GitHub profile information. Instead of repeatedly implementing API requests and profile parsing logic, the library provides a compact Python interface for retrieving common GitHub information.

It is not a web application - it is a Python package anyone can install and import. Where the CS50W projects put Django on a server, ghprofile puts a small library on your machine.

GITHUB PROFILEREPOSITORIESSTARSPINNED REPOSSIMPLE PYTHON API

WHY A LIBRARY?

Turn the API into a tool.

The goal is to make GitHub profile and repository information easier to retrieve from Python through a simple, reusable library. Instead of exposing users directly to every API call, ghprofile provides methods such as:

get_bio()get_followers()get_repo()get_stars()get_pinned_repos()

WHAT IT FETCHES

One profile. More signal.

Six facts about any GitHub user, through one small interface.

BIO

Bio

Retrieve a user's GitHub bio.

FOLLOWERS

Followers

Retrieve follower count.

FOLLOWING

Following

Retrieve following count.

REPOSITORIES

Repositories

List public repositories.

STARS

Stars

Calculate total stars across repositories.

PINNED

Pinned

Fetch pinned repositories.

FROM USERNAME TO DATA

From username to profile.

A username in, a Python object out - the whole point of the library.

USERNAME
GHPROFILE
GITHUB DATA
PYTHON OBJECT
RESULT

example callspython

gh = Ghprofile("octocat")

get_bio()
get_followers()
get_repo()
get_stars()
get_pinned_repos()

SIMPLE API

Simple by design.

The documented interface is intentionally small, named, and straightforward.

ghprofile - documented usagepython

from ghprofile.core import Ghprofile

gh = Ghprofile("octocat", "your_github_token")

print(gh.get_bio())
print(gh.get_followers())
print(gh.get_repo())
print(gh.get_stars())
print(gh.get_pinned_repos())

AUTHENTICATION

Token optional.

WITHOUT TOKEN

Public data
Lower API rate limit
Simple setup

gh = Ghprofile("octocat")

~60 API calls / hour - according to the project's documentation

WITH TOKEN

Higher API rate limit
Private data access
Token passed into Ghprofile

~5000 API calls / hour - according to the project's documentation

Rate limits are documented by the project and originate from GitHub's API access model.

PINNED REPOSITORIES

The pinned part.

The library can fetch a GitHub user's pinned repositories. The project's documentation notes that pinned repositories are retrieved via scraping - not through an official GitHub API endpoint.

GITHUB API + SCRAPING

USER PAGESCRAPEPINNED REPOS

ERROR HANDLING

Fail loud. Fail cleanly.

Errors are wrapped under the custom GhprofileError class, so a failed API call raises a single, catchable exception instead of leaking raw API failures.

API / USER ERRORCUSTOM EXCEPTIONAPPLICATION CAN HANDLE IT

catching the exceptionpython

from ghprofile.core import GhprofileError

try:
    gh = Ghprofile("unknownuser", "badtoken")
except GhprofileError as e:
    print("Something went wrong:", e)

UNDER THE HOOD

A small conceptual architecture.

The library sits between your Python application and GitHub.

PYTHON APPLICATION

GHPROFILE

GITHUB APIPROFILE DATA · REPOSITORIES · STAR COUNTS

PINNED REPO SCRAPINGPINNED REPOSITORIES

PYTHON RESULTS

PACKAGE STRUCTURE

A library you import.

The documented public surface - verified against the project's documentation.

ghprofile.coreThe documented public module - where Ghprofile and GhprofileError live.the import path

GhprofileThe main class. Pass a username (and optionally a token) to start querying.

GhprofileErrorThe custom exception class wrapping failed API calls.

CODE-FIRST

A tool you can import.

Install once, import anywhere - this is a Python package, not a web page.

package useterminal / python

pip install ghprofile

from ghprofile.core import Ghprofile

gh = Ghprofile("octocat")

gh.get_repo()

CONTRIBUTING

Built to extend.

The project's documentation welcomes contributions - new features, improved error handling, test coverage, refactoring, and optimization. Ideas such as commit history and language breakdown appear there as possible future work, not as features that exist today.

New featuresImproved error handlingTest coverageRefactoringOptimization

LICENSE

OPEN SOURCE.

ghprofile is licensed under the MIT License according to the project documentation.

LICENSEMIT

Read the license on GitHub

WHAT THIS PROJECT TAUGHT ME

From script to package.

This project demonstrates packaging Python functionality into a reusable library, designing a small public API, interacting with the GitHub API, handling API errors, working with rate limits, retrieving repository-level statistics, combining API access with scraping, and publishing a package to PyPI.

Packaging a Python libraryTaking small, useful functionality and turning it into an installable, reusable package.
Designing a small public APIA handful of clearly named methods - get_bio, get_followers, get_repo, get_stars, get_pinned_repos.
Interacting with the GitHub APIFetching public profile and repository data through GitHub's REST API.
Handling API errorsFailed calls are wrapped under a custom GhprofileError exception the caller can catch.
Working with rate limitsToken-based access changes the documented API call allowance.
Repository-level statisticsComputing totals like the star count across a user's repositories.
Combining API and scrapingBringing the GitHub API together with scraping for pinned repositories.
Publishing to PyPIThe package is published and installable through pip - with a real PyPI project page.

THE PYPI MOMENT

Published. Installable. Reusable.

A pip install away from any Python project.

install from PyPI

$ pip install ghprofile

View package on PyPI

PROJECT DETAILS

The essentials.

Projectghprofile

CategoryPython library

Built withPython / GitHub API

DistributionPyPI

Repositorygithub.com/ujjwaluzu/ghprofile

Packagepypi.org/project/ghprofile/

LicenseMIT

Want to see the code?

The whole library lives on GitHub - and you can install it from PyPI.

View the project on GitHub Install it from PyPI

pip install ghprofile

Back to all projects