GitHub API Integration

Relevant source files

The following files were used as context for generating this wiki page:

• core/commands.py
• core/bot.py
• core/helpers.py
• core/integrations.py
• requirements.txt
• tests/test_commands.py

The GitHub API Integration within GentelmeN-CorE provides the bot with the capability to search for and retrieve information about public repositories directly from GitHub. This feature allows users to query repositories by keywords, receiving a curated list of top results based on popularity (stargazers).

The integration is primarily handled through the github_search function, which utilizes the GitHub REST API v3 to perform searches and return formatted data to the Telegram interface. It supports optional authentication via environment variables to increase rate limits and access broader search capabilities.

Sources: core/commands.py:166-193, core/bot.py:24-25

Architecture and Components

The integration follows a request-response pattern where the bot acts as a middleware between the Telegram user and the GitHub API.

Request Flow

When a user executes the /github command, the bot processes the query, constructs an API request with appropriate headers, and transmits it to GitHub's search endpoint. The results are then parsed and returned to the user via an "intelligent response" helper.

This diagram shows the flow of a GitHub search request from user initiation to the final message delivery.
Sources: core/commands.py:166-193, core/helpers.py:1-13

Key Components

Component	Responsibility
github_search	Primary command handler for /github requests. Manages input parsing and API communication.
inteligentna_odpowiedz	Helper function used to send formatted Markdown responses back to the chat.
GITHUB_TOKEN	Environment variable used for authenticated requests to the GitHub API.
requests	Library used for making synchronous HTTP calls to GitHub.

Sources: core/commands.py:16-166, core/helpers.py:1, requirements.txt:2

Implementation Details

API Configuration

The integration targets the GitHub Search Repositories endpoint. The query is configured to sort results by stars in descending order, limiting the response to the top 3 items to maintain message brevity.

• Endpoint: https://api.github.com/search/repositories
• Headers: Includes application/vnd.github.v3+json for API versioning and an optional Authorization token.
• Parameters:
  • q: User-provided keywords.
  • sort: Set to stars.
  • order: Set to desc.
  • per_page: Fixed at 3.

Sources: core/commands.py:177-181

Data Handling

The system extracts specific fields from the GitHub API response to build the user notification:

1. Full Name: The repository identifier (e.g., owner/repo).
2. HTML URL: Direct link to the repository.
3. Stargazers Count: The number of stars.
4. Description: A brief overview of the project.

# Implementation snippet of result formatting
text = f"🐙 **GitHub dla '{query}':**\n\n"
for r in response['items']:
    text += (
        f"🔹 [{r['full_name']}](https://github.com/marekdkropiewnicki-dotcom/GentelmeN-CorE/blob/2d43b5ec1061a00351c282f237e2b41f1a36202d/%7Br%5B'html_url'%5D%7D) (⭐ {r['stargazers_count']})\n"
        f"   {r.get('description', '')}\n\n"
    )

Sources: core/commands.py:183-189

Error Handling

The integration includes error handling for empty search results and network exceptions. If the API returns no items, the bot informs the user that no repositories were found. General exceptions during the request process (e.g., timeouts or connection issues) are caught and reported back to the chat to assist in debugging.

Sources: core/commands.py:191-193, tests/test_commands.py:442-450

Execution Sequence

The following sequence diagram illustrates the interaction between the core bot modules and the external GitHub API during a search operation.

The sequence highlights the synchronous nature of the search and the utilization of helper functions for message delivery.
Sources: core/commands.py:166-193, core/helpers.py:1-13

Summary

The GitHub API Integration is a specialized utility within the GentelmeN-CorE project that leverages the GitHub REST API to provide repository discovery features. By using stars as a sorting metric and providing direct links, it serves as an efficient tool for developers to find popular software projects directly within the Telegram interface.

Sources: core/commands.py:166-193, core/bot.py:44