git-recap 0.1.3__tar.gz → 0.1.5__tar.gz

{git_recap-0.1.3 → git_recap-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-recap
-Version: 0.1.3
+Version: 0.1.5
 Summary: A modular Python tool that aggregates and formats user-authored messages from repositories.
 Author: Bruno V.
 Author-email: bruno.vitorino@tecnico.ulisboa.pt
@@ -21,8 +21,16 @@ Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: summary
 
+<a href="https://www.uneed.best/tool/gitrecap">
+  <img src="https://www.uneed.best/POTD2A.png" style="width: 250px;" alt="Uneed POTD2 Badge" />
+</a>
+
+---
+
 # Git Recap
 
+🎉 **Featured in Uneed's Latest Newsletter as a Staff Pick!** 🎉
+
 Git Recap is a modular Python tool that aggregates and formats user-authored messages from repositories hosted on GitHub, Azure DevOps, and GitLab. It fetches commit messages, pull requests (along with their associated commits), and issues, then consolidates and sorts these events into a clear, chronological summary. This summary is output as a plain text string that can serve as context for large language models or other analysis tools.
 
 ## Features

{git_recap-0.1.3 → git_recap-0.1.5}/README.md

@@ -1,5 +1,13 @@
+<a href="https://www.uneed.best/tool/gitrecap">
+  <img src="https://www.uneed.best/POTD2A.png" style="width: 250px;" alt="Uneed POTD2 Badge" />
+</a>
+
+---
+
 # Git Recap
 
+🎉 **Featured in Uneed's Latest Newsletter as a Staff Pick!** 🎉
+
 Git Recap is a modular Python tool that aggregates and formats user-authored messages from repositories hosted on GitHub, Azure DevOps, and GitLab. It fetches commit messages, pull requests (along with their associated commits), and issues, then consolidates and sorts these events into a clear, chronological summary. This summary is output as a plain text string that can serve as context for large language models or other analysis tools.
 
 ## Features
@@ -110,4 +118,4 @@ This project is licensed under the terms of the [MIT License](LICENSE).
 
 - [PyGitHub](https://pygithub.readthedocs.io/en/stable/)
 - [Azure DevOps Python API](https://github.com/microsoft/azure-devops-python-api)
-- [python-gitlab](https://python-gitlab.readthedocs.io/)
+- [python-gitlab](https://python-gitlab.readthedocs.io/)

{git_recap-0.1.3 → git_recap-0.1.5}/git_recap/providers/azure_fetcher.py

@@ -1,12 +1,29 @@
 from azure.devops.connection import Connection
 from msrest.authentication import BasicAuthentication
 from datetime import datetime
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional
 from git_recap.providers.base_fetcher import BaseFetcher
 
 class AzureFetcher(BaseFetcher):
+    """
+    Fetcher implementation for Azure DevOps repositories.
+
+    Supports fetching commits, pull requests, and issues.
+    Release fetching is not supported and will raise NotImplementedError.
+    """
+
     def __init__(self, pat: str, organization_url: str, start_date=None, end_date=None, repo_filter=None, authors=None):
-        # authors should be passed as a list of unique names (e.g., email or unique id)
+        """
+        Initialize the AzureFetcher.
+
+        Args:
+            pat (str): Personal Access Token for Azure DevOps.
+            organization_url (str): The Azure DevOps organization URL.
+            start_date (datetime, optional): Start date for filtering entries.
+            end_date (datetime, optional): End date for filtering entries.
+            repo_filter (List[str], optional): List of repository names to filter.
+            authors (List[str], optional): List of author identifiers (e.g., email or unique id).
+        """
         super().__init__(pat, start_date, end_date, repo_filter, authors)
         self.organization_url = organization_url
         credentials = BasicAuthentication('', self.pat)
@@ -20,17 +37,37 @@ class AzureFetcher(BaseFetcher):
             self.authors = []
 
     def get_repos(self):
+        """
+        Retrieve all repositories in all projects for the organization.
+        Returns:
+            List of repository objects.
+        """
         projects = self.core_client.get_projects().value
         # Get all repositories in each project
         repos = [self.git_client.get_repositories(project.id) for project in projects]
         return repos
 
     @property
-    def repos_names(self)->List[str]:
-        "to be implemented later"
+    def repos_names(self) -> List[str]:
+        """
+        Return the list of repository names.
+
+        Returns:
+            List[str]: List of repository names.
+        """
+        # To be implemented if needed for UI or listing.
         ...
 
     def _filter_by_date(self, date_obj: datetime) -> bool:
+        """
+        Check if a datetime object is within the configured date range.
+
+        Args:
+            date_obj (datetime): The datetime to check.
+
+        Returns:
+            bool: True if within range, False otherwise.
+        """
         if self.start_date and date_obj < self.start_date:
             return False
         if self.end_date and date_obj > self.end_date:
@@ -38,11 +75,26 @@ class AzureFetcher(BaseFetcher):
         return True
 
     def _stop_fetching(self, date_obj: datetime) -> bool:
+        """
+        Determine if fetching should stop based on the date.
+
+        Args:
+            date_obj (datetime): The datetime to check.
+
+        Returns:
+            bool: True if should stop, False otherwise.
+        """
         if self.start_date and date_obj < self.start_date:
             return True
         return False
 
     def fetch_commits(self) -> List[Dict[str, Any]]:
+        """
+        Fetch commits for all repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of commit entries.
+        """
         entries = []
         processed_commits = set()
         for repo in self.repos:
@@ -77,6 +129,12 @@ class AzureFetcher(BaseFetcher):
         return entries
 
     def fetch_pull_requests(self) -> List[Dict[str, Any]]:
+        """
+        Fetch pull requests and their associated commits for all repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of pull request and commit_from_pr entries.
+        """
         entries = []
         processed_pr_commits = set()
         projects = self.core_client.get_projects().value
@@ -138,6 +196,12 @@ class AzureFetcher(BaseFetcher):
         return entries
 
     def fetch_issues(self) -> List[Dict[str, Any]]:
+        """
+        Fetch issues (work items) assigned to the configured authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of issue entries.
+        """
         entries = []
         wit_client = self.connection.clients.get_work_item_tracking_client()
         # Query work items for each author using a simplified WIQL query.
@@ -160,4 +224,93 @@ class AzureFetcher(BaseFetcher):
                     entries.append(entry)
                 if self._stop_fetching(created_date):
                     break
-        return entries
+        return entries
+
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for Azure DevOps repositories.
+
+        Not implemented for Azure DevOps.
+
+        Raises:
+            NotImplementedError: Always, since release fetching is not supported for AzureFetcher.
+        """
+        # If Azure DevOps release fetching is supported in the future, implement logic here.
+        raise NotImplementedError("Release fetching is not supported for Azure DevOps (AzureFetcher).")
+
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        
+        Returns:
+            List[str]: List of branch names.
+        
+        Raises:
+            NotImplementedError: Always, since branch listing is not yet implemented for AzureFetcher.
+        """
+        # TODO: Implement get_branches() for Azure DevOps support
+        # This would use: git_client.get_branches(repository_id, project)
+        # and extract branch names from the returned objects
+        raise NotImplementedError("Branch listing is not yet implemented for Azure DevOps (AzureFetcher).")
+
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        
+        Validates that the source branch exists, filters out branches with existing
+        open PRs from source, excludes the source branch itself, and optionally
+        checks if source is ahead of target.
+        
+        Args:
+            source_branch (str): The source branch name.
+        
+        Returns:
+            List[str]: List of valid target branch names.
+        
+        Raises:
+            NotImplementedError: Always, since PR target validation is not yet implemented for AzureFetcher.
+        """
+        # TODO: Implement get_valid_target_branches() for Azure DevOps support
+        # This would require:
+        # 1. Verify source_branch exists using git_client.get_branch()
+        # 2. Get all branches using get_branches()
+        # 3. Filter out source branch
+        # 4. Check for existing pull requests using git_client.get_pull_requests()
+        # 5. Filter out branches with existing open PRs from source
+        # 6. Optionally check branch policies and protection rules
+        raise NotImplementedError("Pull request target branch validation is not yet implemented for Azure DevOps (AzureFetcher).")
+
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request between two branches with optional metadata.
+        
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata (url, number, state, success) or error information.
+        
+        Raises:
+            NotImplementedError: Always, since PR creation is not yet implemented for AzureFetcher.
+        """
+        # TODO: Implement create_pull_request() for Azure DevOps support
+        # This would use: git_client.create_pull_request() with appropriate parameters
+        # Would need to handle reviewers, work item links (assignees), labels, and draft status
+        raise NotImplementedError("Pull request creation is not yet implemented for Azure DevOps (AzureFetcher).")

git_recap-0.1.5/git_recap/providers/base_fetcher.py

@@ -0,0 +1,209 @@
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import List, Optional, Dict, Any
+
+class BaseFetcher(ABC):
+    def __init__(
+        self,
+        pat: str,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None,
+        repo_filter: Optional[List[str]] = None,
+        authors: Optional[List[str]] = None
+    ):
+        self.pat = pat
+        if start_date is not None:
+            self.start_date = start_date if start_date.tzinfo is not None else start_date.replace(tzinfo=timezone.utc)
+        else:
+            self.start_date = None
+
+        if end_date is not None:
+            self.end_date = end_date if end_date.tzinfo is not None else end_date.replace(tzinfo=timezone.utc)
+        else:
+            self.end_date = None
+
+        self.repo_filter = repo_filter or []
+        self.limit = -1
+        self.authors = [] if authors is None else authors
+
+    @property
+    @abstractmethod
+    def repos_names(self) -> List[str]:
+        """
+        Return the list of repository names accessible to this fetcher.
+
+        Returns:
+            List[str]: List of repository names.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_commits(self) -> List[Dict[str, Any]]:
+        """
+        Fetch commit entries for the configured repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of commit entries.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_pull_requests(self) -> List[Dict[str, Any]]:
+        """
+        Fetch pull request entries for the configured repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of pull request entries.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_issues(self) -> List[Dict[str, Any]]:
+        """
+        Fetch issue entries for the configured repositories and authors.
+
+        Returns:
+            List[Dict[str, Any]]: List of issue entries.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_releases(self) -> List[Dict[str, Any]]:
+        """
+        Fetch releases for all repositories accessible to this fetcher.
+
+        Returns:
+            List[Dict[str, Any]]: List of releases, each as a structured dictionary.
+                The dictionary should include at least:
+                  - tag_name: str
+                  - name: str
+                  - repo: str
+                  - author: str
+                  - published_at: datetime
+                  - created_at: datetime
+                  - draft: bool
+                  - prerelease: bool
+                  - body: str
+                  - assets: List[Dict[str, Any]] (if available)
+        Raises:
+            NotImplementedError: If the provider does not support release fetching.
+        """
+        raise NotImplementedError("Release fetching is not implemented for this provider.")
+
+    @abstractmethod
+    def get_branches(self) -> List[str]:
+        """
+        Get all branches in the repository.
+        
+        Returns:
+            List[str]: List of branch names.
+        
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement get_branches() to return all repository branches")
+
+    @abstractmethod
+    def get_valid_target_branches(self, source_branch: str) -> List[str]:
+        """
+        Get branches that can receive a pull request from the source branch.
+        
+        Validates that the source branch exists, filters out branches with existing
+        open PRs from source, excludes the source branch itself, and optionally
+        checks if source is ahead of target.
+        
+        Args:
+            source_branch (str): The source branch name.
+        
+        Returns:
+            List[str]: List of valid target branch names.
+        
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement get_valid_target_branches() to return valid PR target branches for the given source branch")
+
+    @abstractmethod
+    def create_pull_request(
+        self,
+        head_branch: str,
+        base_branch: str,
+        title: str,
+        body: str,
+        draft: bool = False,
+        reviewers: Optional[List[str]] = None,
+        assignees: Optional[List[str]] = None,
+        labels: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a pull request between two branches with optional metadata.
+        
+        Args:
+            head_branch: Source branch for the PR.
+            base_branch: Target branch for the PR.
+            title: PR title.
+            body: PR description.
+            draft: Whether to create as draft PR (default: False).
+            reviewers: List of reviewer usernames (optional).
+            assignees: List of assignee usernames (optional).
+            labels: List of label names (optional).
+        
+        Returns:
+            Dict[str, Any]: Dictionary containing PR metadata (url, number, state, success) or error information.
+        
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement create_pull_request() to create a pull request with the specified parameters")
+
+    def get_authored_messages(self) -> List[Dict[str, Any]]:
+        """
+        Aggregates all commit, pull request, and issue entries into a single list,
+        ensuring no duplicate commits (based on SHA) are present, and then sorts
+        them in chronological order based on their timestamp.
+
+        Returns:
+            List[Dict[str, Any]]: Aggregated and sorted list of entries.
+        """
+        commit_entries = self.fetch_commits()
+        pr_entries = self.fetch_pull_requests()
+        try:
+            issue_entries = self.fetch_issues()
+        except Exception:
+            issue_entries = []
+
+        all_entries = pr_entries + commit_entries + issue_entries
+
+        # For commit-related entries, remove duplicates (if any) based on SHA.
+        unique_entries = {}
+        for entry in all_entries:
+            if entry.get("type") in ["commit", "commit_from_pr"]:
+                sha = entry.get("sha")
+                if sha in unique_entries:
+                    continue
+                unique_entries[sha] = entry
+            else:
+                # For pull requests and issues, we can create a unique key.
+                key = f"{entry['type']}_{entry['repo']}_{entry['timestamp']}"
+                unique_entries[key] = entry
+
+        final_entries = list(unique_entries.values())
+        # Sort all entries by their timestamp.
+        final_entries.sort(key=lambda x: x["timestamp"])
+        return self.convert_timestamps_to_str(final_entries)
+
+    @staticmethod
+    def convert_timestamps_to_str(entries: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Converts the timestamp field from datetime to string format for each entry in the list.
+
+        Args:
+            entries (List[Dict[str, Any]]): List of entries with possible datetime timestamps.
+
+        Returns:
+            List[Dict[str, Any]]: Entries with timestamps as ISO-formatted strings.
+        """
+        for entry in entries:
+            if isinstance(entry.get("timestamp"), datetime):
+                entry["timestamp"] = entry["timestamp"].isoformat()
+        return entries