Skip to main content

Unified client for GitHub, GitLab and BitBucket

Project description

GitHarbor

PyPI License Package status Daily downloads Weekly downloads Monthly downloads Distribution format Wheel availability Python version Implementation Releases Github Contributors Github Discussions Github Forks Github Issues Github Issues Github Watchers Github Stars Github Repository size Github last commit Github release date Github language count Github commits this week Github commits this month Github commits this year Package status Code style: black PyUp

Read the documentation!

GitHarbor User Guide

GitHarbor is a unified interface for interacting with Git hosting platforms. It provides a consistent API to work with repositories hosted on GitHub, GitLab, Azure DevOps, Gitea, CodeBerg and Bitbucket.

Getting Started

The main entry point is the create_repository() function which accepts a repository URL and platform-specific credentials:

from githarbor import create_repository

# GitHub repository
repo = create_repository("https://github.com/owner/repo", token="github_pat_...")

# GitLab repository
repo = create_repository("https://gitlab.com/owner/repo", token="glpat-...")

# Azure DevOps repository
repo = create_repository(
    "https://dev.azure.com/org/project/_git/repo",
    token="azure_pat"
)

[!TIP] Always use personal access tokens (PATs) for authentication. Never hardcode tokens in your source code.

Working with Repositories

Basic Repository Information

# Get repository name and default branch
print(repo.name)
print(repo.default_branch)

# Get language statistics
languages = repo.get_languages()
# Returns: {"Python": 10000, "JavaScript": 5000}

# Get recent activity statistics
activity = repo.get_recent_activity(
    days=30,
    include_commits=True,
    include_prs=True,
    include_issues=True
)

Branches and Tags

# List all branches
branches = repo.list_branches()

# Get specific branch
main_branch = repo.get_branch("main")

# List all tags
tags = repo.list_tags()

# Get specific tag
tag = repo.get_tag("v1.0.0")

# Compare branches
diff = repo.compare_branches(
    base="main",
    head="feature",
    include_commits=True,
    include_files=True,
    include_stats=True
)

Commits

# Get specific commit
commit = repo.get_commit("abcd1234")

# List commits with filters
commits = repo.list_commits(
    branch="main",
    since=datetime(2024, 1, 1),
    until=datetime(2024, 2, 1),
    author="username",
    path="src/",
    max_results=100
)

# Search commits
results = repo.search_commits(
    query="fix bug",
    branch="main",
    path="src/",
    max_results=10
)

Issues and Pull Requests

# List open issues
open_issues = repo.list_issues(state="open")

# Get specific issue
issue = repo.get_issue(123)

# List pull requests
prs = repo.list_pull_requests(state="open")  # or "closed" or "all"

# Get specific pull request
pr = repo.get_pull_request(456)

Releases

# Get latest release
latest = repo.get_latest_release(
    include_drafts=False,
    include_prereleases=False
)

# List all releases
releases = repo.list_releases(
    include_drafts=False,
    include_prereleases=True,
    limit=10
)

# Get specific release
release = repo.get_release("v1.0.0")

Repository Content

# Download single file
repo.download(
    path="README.md",
    destination="local/README.md"
)

# Download directory recursively
repo.download(
    path="src/",
    destination="local/src",
    recursive=True
)

# Iterate through files
for file_path in repo.iter_files(
    path="src/",
    ref="main",
    pattern="*.py"
):
    print(file_path)

CI/CD Workflows

# List all workflows
workflows = repo.list_workflows()

# Get specific workflow
workflow = repo.get_workflow("workflow_id")

# Get specific workflow run
run = repo.get_workflow_run("run_id")

Contributors

# Get repository contributors
contributors = repo.get_contributors(
    sort_by="commits",  # or "name" or "date"
    limit=10
)

Error Handling

GitHarbor provides specific exceptions for different error cases:

from githarbor.exceptions import (
    RepositoryNotFoundError,
    ResourceNotFoundError,
    FeatureNotSupportedError
)

try:
    repo = create_repository("https://github.com/nonexistent/repo")
except RepositoryNotFoundError:
    print("Repository does not exist")

try:
    issue = repo.get_issue(999999)
except ResourceNotFoundError:
    print("Issue does not exist")

try:
    repo.some_unsupported_method()
except FeatureNotSupportedError:
    print("This feature is not supported by this repository provider")

[!NOTE] Not all features are supported by all platforms. Operations that aren't supported will raise FeatureNotSupportedError.

[!IMPORTANT] Be mindful of API rate limits when making many requests. Consider implementing retries and delays in your code.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

githarbor-0.8.0.tar.gz (66.9 kB view details)

Uploaded Source

Built Distribution

githarbor-0.8.0-py3-none-any.whl (82.7 kB view details)

Uploaded Python 3

File details

Details for the file githarbor-0.8.0.tar.gz.

File metadata

  • Download URL: githarbor-0.8.0.tar.gz
  • Upload date:
  • Size: 66.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for githarbor-0.8.0.tar.gz
Algorithm Hash digest
SHA256 ee3b5e36ee4dd8b1adcb19fe9696cdcae7809e09fc773886a744bb45db663fd6
MD5 2d8aa858978f85c3c32d6dbe6c1e2b12
BLAKE2b-256 04ca676569ec0fd61b9739cfff75603cfd8834dc6c9eae7664d46423e1d731a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for githarbor-0.8.0.tar.gz:

Publisher: build.yml on phil65/githarbor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file githarbor-0.8.0-py3-none-any.whl.

File metadata

  • Download URL: githarbor-0.8.0-py3-none-any.whl
  • Upload date:
  • Size: 82.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for githarbor-0.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f975c3ff9eee8208d4efabc8de31344e0835def5677ed4c2bb8af509688e2cba
MD5 998d057ff1e7260d04bad8759df58137
BLAKE2b-256 53bc2263ab90326679de68bda760eafd7877e64f2a3981c25ab7d11ed8988c92

See more details on using hashes here.

Provenance

The following attestation bundles were made for githarbor-0.8.0-py3-none-any.whl:

Publisher: build.yml on phil65/githarbor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page