python-github-plus 0.0.1__py3-none-any.whl

python_github_plus/__init__.py

@@ -0,0 +1,11 @@
+from dotenv import load_dotenv
+
+from python_github_plus.github_plus import GitHubPRStatus, GitHubWorkflowStatus, GitHubClient
+
+load_dotenv()
+
+__all__ = [
+    'GitHubPRStatus',
+    'GitHubWorkflowStatus',
+    'GitHubClient'
+]

python_github_plus/github_plus.py

@@ -0,0 +1,302 @@
+import os
+import time
+from enum import Enum
+from typing import Optional, List
+
+from github import Github, Auth, GithubException
+from github.GitRef import GitRef
+from github.GitTag import GitTag
+from github.Repository import Repository
+from github.Branch import Branch
+from github.Tag import Tag
+from github.PullRequest import PullRequest
+from github.ContentFile import ContentFile
+from custom_python_logger import get_logger
+from github.Workflow import Workflow
+from github.WorkflowRun import WorkflowRun
+
+
+class GitHubPRStatus(Enum):
+    OPEN = "open"
+    CLOSED = "closed"
+    MERGED = "merged"
+
+
+class GitHubWorkflowStatus(Enum):
+    COMPLETED = "completed"
+    IN_PROGRESS = "in_progress"
+    QUEUED = "queued"
+
+
+class GitHubProjectService:
+    def __init__(self, repo: Repository):
+        self.logger = get_logger(self.__class__.__name__)
+        self.repo = repo
+
+    def get_info(self) -> Repository:
+        return self.repo
+
+    def list_members(self):
+        return list(self.repo.get_collaborators())
+
+    def add_member(self, username: str, permission: str = "push") -> None:
+        try:
+            self.repo.add_to_collaborators(username, permission)
+            self.logger.info(f"✅ Added member '{username}' with '{permission}' permission.")
+        except GithubException as e:
+            self.logger.error(f"❌ Failed to add member {username}: {e}")
+
+    def remove_member(self, username: str) -> None:
+        try:
+            self.repo.remove_from_collaborators(username)
+            self.logger.info(f"✅ Removed member '{username}'.")
+        except GithubException as e:
+            self.logger.error(f"❌ Failed to remove member {username}: {e}")
+
+
+class GitHubWorkflowService:
+    def __init__(self, repo: Repository):
+        self.logger = get_logger(self.__class__.__name__)
+        self.repo = repo
+
+    def list(self) -> list[Workflow]:
+        """List workflows configured in the repo (.github/workflows)."""
+        return list(self.repo.get_workflows())
+
+    def trigger(self, workflow_name: str, branch_name: str = "main", inputs: Optional[dict] = None) -> Workflow:
+        """
+        Dispatch a workflow by name on a given branch.
+        Requires 'workflow_dispatch' defined in the workflow YAML.
+        """
+        workflows = {wf.name: wf for wf in self.repo.get_workflows()}
+        if workflow_name not in workflows:
+            raise ValueError(f"❌ Workflow '{workflow_name}' not found.")
+
+        workflow = workflows[workflow_name]
+        workflow.create_dispatch(ref=branch_name, inputs=inputs or {})
+        self.logger.info(f"🚀 Triggered workflow '{workflow_name}' on branch '{branch_name}'")
+
+        # Note: This returns immediately; to track status, use wait_until_finished
+        return workflow
+
+    def get_workflow_by_id(self, workflow_id: int) -> Workflow:
+        return self.repo.get_workflow(workflow_id)
+
+    def list_runs(self, workflow_name: str, branch: Optional[str] = None) -> List[WorkflowRun]:
+        workflows = {wf.name: wf for wf in self.repo.get_workflows()}
+        if workflow_name not in workflows:
+            raise ValueError(f"❌ Workflow '{workflow_name}' not found.")
+
+        runs = workflows[workflow_name].get_runs(branch=branch) if branch else workflows[workflow_name].get_runs()
+        return list(runs)
+
+    def last_run_by_id(self, workflow_id: int) -> WorkflowRun:
+        return self.repo.get_workflow(workflow_id).get_runs()[0]
+
+    def status(self, run_id: int) -> str:
+        """ Get the current status of a workflow run. run_id is the ID of the run, not the workflow. """
+        run = self.repo.get_workflow_run(run_id)
+        return run.status  # "queued", "in_progress", "completed"
+
+    def conclusion(self, run_id: int) -> Optional[str]:
+        """ Get the conclusion of a completed workflow run. None if still running. run_id is the ID of the run, not the workflow. """
+        run = self.repo.get_workflow_run(run_id)
+        return run.conclusion  # "success", "failure", "cancelled", None if still running
+
+    def wait_until_finished(self, run_id: int, check_interval=10, timeout: Optional[int] = None) -> str:
+        start_time = time.time()
+        while True:
+            run = self.repo.get_workflow_run(run_id)
+
+            if run.status == "completed":
+                self.logger.info(f"✅ Workflow run {run_id} finished with conclusion = {run.conclusion}")
+                return run.conclusion
+
+            if timeout and (time.time() - start_time) > timeout:
+                raise TimeoutError(f"⏰ Workflow run {run_id} did not complete within {timeout} seconds.")
+
+            self.logger.debug(f"⏳ Workflow run {run_id} still {run.status}...")
+            time.sleep(check_interval)
+
+
+class GitHubBranchService:
+    def __init__(self, repo: Repository):
+        self.logger = get_logger(self.__class__.__name__)
+        self.repo = repo
+
+    def create(self, branch_name: str, from_branch: str) -> GitRef:
+        ref = self.repo.get_git_ref(f"heads/{from_branch}")
+        new_ref = self.repo.create_git_ref(ref=f"refs/heads/{branch_name}", sha=ref.object.sha)
+        self.logger.info(f"✅ Branch '{branch_name}' created from '{from_branch}'")
+        return new_ref
+
+    def delete(self, branch_name: str) -> None:
+        ref = self.repo.get_git_ref(f"heads/{branch_name}")
+        ref.delete()
+        self.logger.info(f"✅ Branch '{branch_name}' deleted")
+
+    def list(self) -> list[Branch]:
+        return list(self.repo.get_branches())
+
+    def protect(
+        self,
+        branch_name: str,
+        enforce_admins: bool = True,
+        require_pull_request_reviews: bool = True,
+        dismiss_stale_reviews: bool = True,
+        required_approving_review_count: int = 1,
+        require_status_checks: bool = False,
+        status_check_contexts: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Protect a branch with common settings.
+        """
+        branch = self.repo.get_branch(branch_name)
+        branch.edit_protection(
+            required_approving_review_count=required_approving_review_count,
+            enforce_admins=enforce_admins,
+            dismiss_stale_reviews=dismiss_stale_reviews,
+            require_code_owner_reviews=require_pull_request_reviews,
+            contexts=status_check_contexts if require_status_checks else None,
+        )
+        self.logger.info(f"✅ Branch '{branch_name}' protected")
+
+    def unprotect(self, branch_name: str) -> None:
+        branch = self.repo.get_branch(branch_name)
+        branch.remove_protection()
+        self.logger.info(f"✅ Branch '{branch_name}' unprotected")
+
+
+class GitHubTagService:
+    def __init__(self, repo: Repository):
+        self.logger = get_logger(self.__class__.__name__)
+        self.repo = repo
+
+    def create_by_sha(self, tag_name: str, sha: str, message: Optional[str] = None) -> GitTag:
+        tag = self.repo.create_git_tag(tag=tag_name, message=message or tag_name, object="main", type="commit")
+        self.repo.create_git_ref(ref=f"refs/tags/{tag_name}", sha=tag.sha)
+        self.logger.info(f"✅ Tag '{tag_name}' created at commit {sha}")
+        return tag
+
+    def create_by_branch(self, tag_name: str, from_branch: str, message: Optional[str] = None) -> GitTag:
+        branch = self.repo.get_branch(from_branch)
+        sha = branch.commit.sha
+        return self.create_by_sha(tag_name=tag_name, sha=sha, message=message)
+
+    def delete(self, tag_name: str) -> None:
+        ref = self.repo.get_git_ref(f"tags/{tag_name}")
+        ref.delete()
+        self.logger.info(f"✅ Tag '{tag_name}' deleted")
+
+    def list(self) -> list[Tag]:
+        return list(self.repo.get_tags())
+
+
+class GitHubPRService:
+    def __init__(self, repo: Repository):
+        self.logger = get_logger(self.__class__.__name__)
+        self.repo = repo
+
+    def get_info(self, number: int) -> PullRequest:
+        return self.repo.get_pull(number)
+
+    def create(self, title: str, from_branch: str, target: str) -> PullRequest:
+        pr = self.repo.create_pull(title=title, head=from_branch, base=target)
+        self.logger.info(f"✅ PR '{title}' created: #{pr.number}")
+        return pr
+
+    def assign(self, pr_number: int, assignees: str) -> None:
+        issue = self.repo.get_issue(pr_number)  # fetch the same PR as an issue
+        issue.add_to_assignees(assignees)  # or multiple users
+        self.logger.info(f"✅ PR #{pr_number} assigned to {assignees}")
+
+    def status(self, number: int) -> str:
+        pr = self.repo.get_pull(number)
+        if pr.merged:
+            return GitHubPRStatus.MERGED.value
+        return pr.state
+
+    def merge(self, number: int) -> None:
+        pr = self.repo.get_pull(number)
+        pr.merge()
+        self.logger.info(f"✅ PR #{number} merged.")
+
+    def close(self, number: int) -> None:
+        pr = self.repo.get_pull(number)
+        pr.edit(state="closed")
+        self.logger.info(f"✅ PR #{number} closed.")
+
+    def reopen(self, number: int) -> None:
+        pr = self.repo.get_pull(number)
+        pr.edit(state="open")
+        self.logger.info(f"✅ PR #{number} reopened.")
+
+    def add_comment(self, number: int, comment: str) -> None:
+        pr = self.repo.get_pull(number)
+        pr.create_issue_comment(comment)
+        self.logger.info(f"✅ Comment added to PR #{number}.")
+
+    def approve(self, number: int, body: str = "LGTM ✅") -> None:
+        pr = self.repo.get_pull(number)
+        pr.create_review(event="APPROVE", body=body)
+        self.logger.info(f"✅ PR #{number} approved.")
+
+
+class GitHubFileService:
+    def __init__(self, repo: Repository):
+        self.logger = get_logger(self.__class__.__name__)
+        self.repo = repo
+
+    def get(self, path: str, ref: str = "main") -> ContentFile:
+        return self.repo.get_contents(path, ref=ref)
+
+    def fetch_content(self, file_path: str, ref: str = "main") -> str:
+        file = self.repo.get_contents(file_path, ref=ref)
+        return file.decoded_content.decode("utf-8")
+
+    # def update(self, path: str, branch: str, content: str, message: str) -> None:
+    #     file = self.repo.get_contents(path, ref=branch)
+    #     self.repo.update_file(path, message, content, file.sha, branch=branch)
+    #     self.logger.info(f"✅ File '{path}' updated on branch '{branch}'")
+    #
+    # def create(self, path: str, branch: str, content: str, message: str) -> None:
+    #     self.repo.create_file(path, message, content, branch=branch)
+    #     self.logger.info(f"✅ File '{path}' created on branch '{branch}'")
+    #
+    # def delete(self, path: str, branch: str, message: str) -> None:
+    #     file = self.repo.get_contents(path, ref=branch)
+    #     self.repo.delete_file(path, message, file.sha, branch=branch)
+    #     self.logger.info(f"✅ File '{path}' deleted on branch '{branch}'")
+
+
+# ----------------------- #
+# Facade / User Interface #
+# ----------------------- #
+
+class GitHubClient:
+    def __init__(self, access_token: Optional[str], repo_full_name: str):
+        self.logger = get_logger(self.__class__.__name__)
+        self.github_access_token = access_token or os.environ.get("GITHUB_ACCESS_TOKEN")
+
+        self.github = Github(auth=Auth.Token(self.github_access_token))
+        self.is_connected(raise_if_not_connected=True)
+
+        repo = self.github.get_repo(repo_full_name)
+        self.project = GitHubProjectService(repo)
+        self.workflow = GitHubWorkflowService(repo)
+        self.branch = GitHubBranchService(repo)
+        self.tag = GitHubTagService(repo)
+        self.pull_request = GitHubPRService(repo)
+        self.file = GitHubFileService(repo)
+
+    def is_connected(self, raise_if_not_connected: bool = False) -> bool:
+        try:
+            user = self.github.get_user().login
+            self.logger.info(f"✅ Successfully connected to GitHub as {user}")
+            return True
+        except Exception as e:
+            msg = f"❌ Failed to authenticate with GitHub: {e}"
+            if raise_if_not_connected:
+                raise ValueError(msg)
+            self.logger.exception(msg)
+            return False

python_github_plus-0.0.1.dist-info/METADATA

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: python-github-plus
+Version: 0.0.1
+Summary: Enhanced Python GitHub client.
+Home-page: https://github.com/aviz92/python-github-plus
+Author: Avi Zaguri
+Author-email: 
+Project-URL: Repository, https://github.com/aviz92/python-github-plus
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools
+Requires-Dist: wheel
+Requires-Dist: python-dotenv
+Requires-Dist: pytest
+Requires-Dist: pygithub
+Requires-Dist: custom-python-logger
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Python GitHub Plus
+An enhanced Python client for GitHub that extends the functionality of the official `pygithub` package, providing better error handling, merge request management, branch operations, and more.
+
+---
+
+## Features
+- ✅ Simplified connection to GitHub instances
+- ✅ Robust error handling with comprehensive logging
+- ✅ **Service-based architecture** for organized functionality
+- ✅ **Project management** (members, info, etc.)
+- ✅ **Branch operations** (create, delete, protect, list, etc.)
+- ✅ **Pull Request management** (create, merge, approve, assign, comment, etc.)
+- ✅ **Workflow operations** (trigger, monitor, wait for completion, etc.)
+- ✅ **Tag management** (create, delete, list, etc.)
+- ✅ **File operations** (read, create, update, delete, etc.)
+
+---
+
+## Installation
+```bash
+pip install python-github-plus
+```
+
+---
+
+## Configuration
+The package uses environment variables for authentication and configuration:
+
+```bash
+# Required environment variables
+GitHub_ACCESS_TOKEN=your_github_access_token
+GitHub_URL=https://github.com  # Your GitHub instance URL (default: github.com)
+```
+
+## Examples
+
+### Basic Setup and Connection
+```python
+from python_github_plus import GitHubClient
+
+# Initialize GitLab client with service-based architecture
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Access different services
+project_service = github_client.project
+branch_service = github_client.branch
+pr_service = github_client.pull_request
+workflows_service = github_client.workflows
+tag_service = github_client.tag
+file_service = github_client.file
+```
+
+### Branch Management
+```python
+from python_github_plus import GitHubClient
+
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Create a new branch
+branch = github_client.branch.create(
+    branch_name="feature/new-feature",
+    from_branch="main"
+)
+print(f"Created branch: {branch.ref}")
+
+# List branches
+branches = github_client.branch.list()
+for branch in branches:
+    print(f"Branch: {branch.name}")
+
+# Protect a branch
+github_client.branch.protect("main")
+
+# Delete a branch
+github_client.branch.delete("feature/old-feature")
+```
+
+### Pull Request Management
+```python
+from python_github_plus import GitHubClient
+
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Create a pull request
+pr = github_client.pull_request.create(
+    title="Add new feature",
+    from_branch="feature/new-feature",
+    target="main"
+)
+print(f"Created PR: !{pr.number}")
+
+# Assign PR to a user
+github_client.pull_request.assign(pr.number, "username")
+
+# Add a comment
+github_client.pull_request.add_comment(pr.number, "Great work!")
+
+# Approve the PR
+github_client.pull_request.approve(pr.number)
+
+# Merge the PR
+github_client.pull_request.merge(pr.number)
+```
+
+### Workflow Operations
+
+```python
+import time
+from python_github_plus import GitHubClient
+
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Trigger a workflows
+workflows = github_client.workflow.trigger(
+    workflow_name="CI",
+    branch_name="main",
+)
+print(f"Workflow triggered: {workflows.id}")
+
+time.sleep(5)  # wait a bit for the workflow to register
+run_id = github_client.workflow.last_run_by_id(workflow_id=workflows.id)
+
+# Check workflow run status
+status = github_client.workflow.status(run_id=run_id.id)
+print(f"Workflow run status: {status}")
+
+# Wait for workflows completion
+final_status = github_client.workflow.wait_until_finished(
+    run_id=run_id.id,
+    check_interval=30,
+    timeout=3600
+)
+print(f"Workflow run completed with status: {final_status}")
+```
+
+### File Operations
+```python
+from python_github_plus import GitHubClient
+
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Read file content
+file_content = github_client.file.fetch_content(
+    file_path="README.md",
+    ref="main"
+)
+print(f"File content: {file_content[:100]}...")
+```
+
+### Tag Management
+```python
+from python_github_plus import GitHubClient
+
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Create a tag
+tag = github_client.tag.create_by_branch(
+    tag_name="v1.0.0",
+    from_branch="main",
+    message="Release version 1.0.0"
+)
+print(f"Created tag: {tag.name}")
+
+# List tags
+tags = github_client.tag.list()
+for tag in tags:
+    print(f"Tag: {tag.name}")
+
+# Delete a tag
+github_client.tag.delete("v0.9.0")
+```
+
+### Project Management
+```python
+from python_github_plus import GitHubClient
+
+github_client = GitHubClient(
+    access_token="your_access_token",  # Note: parameter name changed
+    repo_full_name="your-repo-owner/your-repo-name",
+)
+
+# Get project information
+project_info = github_client.project.get_info()
+print(f"Project: {project_info.name}")
+print(f"Description: {project_info.description}")
+
+# List project members
+members = github_client.project.list_members()
+for member in members:
+    print(f"Member: {member.username}")
+
+# Add a member
+github_client.project.add_member("newuser", 30)  # 30 = Developer access level
+
+# Remove a member
+github_client.project.remove_member("olduser")
+```
+
+---
+
+## 🤝 Contributing
+If you have a helpful tool, pattern, or improvement to suggest:
+Fork the repo <br>
+Create a new branch <br>
+Submit a pull request <br>
+I welcome additions that promote clean, productive, and maintainable development. <br>
+
+---
+
+## 🙏 Thanks
+Thanks for exploring this repository! <br>
+Happy coding! <br>

python_github_plus-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+python_github_plus/__init__.py,sha256=MO6TwnFs1o64c3qmWrnFD85RQZ2yHCMoVblkzTsjnRU,225
+python_github_plus/github_plus.py,sha256=1wfLgbM60HSPkHb6lNU_aS5fSO-LzcUO4LH6otEo30c,12078
+python_github_plus-0.0.1.dist-info/licenses/LICENSE,sha256=cSikHY6SZFsPZSBizCDAJ0-Bjjzxt-JtX6TVbKxwimo,1067
+python_github_plus-0.0.1.dist-info/METADATA,sha256=4LJcwAx0vRd4QQDV7aThFEV04n-scFpH3VoW54DVgz4,6636
+python_github_plus-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+python_github_plus-0.0.1.dist-info/top_level.txt,sha256=lm_rQAamcpxcN00h3Thamd05_z5PdTfy-RVSuCpN_xA,19
+python_github_plus-0.0.1.dist-info/RECORD,,

python_github_plus-0.0.1.dist-info/WHEEL

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

python_github_plus-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Avi Zaguri
+
+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.

python_github_plus-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+python_github_plus