Contribution Guidelines

How to Contribute

Thank you for your interest in improving Eternity. As a real-time data retrieval library, we value contributions that enhance search accuracy, improve data formatting, and expand the utility of the public API.

Reporting Bugs

If you encounter unexpected behavior or errors (such as issues with the requests handling or API parsing), please open an issue on GitHub. To help us resolve the problem quickly, please include:

• A clear, descriptive title.
• The version of Python and Eternity you are using.
• A minimal code snippet to reproduce the error.
• The expected outcome versus the actual outcome.

Suggesting Features

We welcome ideas for new functionality, such as additional search parameters or new formatting methods in the Eternity class. When suggesting a feature:

1. Open an issue and label it as a Feature Request.
2. Explain the use case—how does this help a user retrieving web data?
3. Outline the proposed public interface (e.g., new method names or arguments).

Development Setup

To contribute code, follow these steps to set up your local development environment:

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/yourusername/eternity.git
   cd eternity
   

3. Install dependencies:

   pip install -e .
   

   Note: The library requires the requests package.

Pull Request Process

1. Create a branch for your fix or feature:

   git checkout -b feature/your-feature-name
   

2. Implement your changes. If you are adding a new method to the Eternity class, ensure it follows the existing pattern of using self.api_key and self.engine_id for authentication.
3. Test your changes. You can verify your changes by creating a local test script:

   from eternity import Eternity
   
   # Use your Google Custom Search credentials
   client = Eternity(api_key="YOUR_KEY", engine_id="YOUR_ID")
   
   # Test existing and new functionality
   print(client.get_combined_text("Open Source Contribution"))
   

4. Submit the PR. Provide a clear description of what was changed and reference any related issues.

Coding Standards

To maintain a clean and usable public API, please adhere to the following:

• PEP 8 Compliance: Follow standard Python style guidelines.
• Documentation: If you add or modify a public method (like search or get_combined_text), include a docstring explaining the parameters and the return type.
• Keep it Modular: Focus on the Eternity class interface. Avoid adding complex internal logic that isn't exposed through a clear, user-facing method.

Public Interface Overview

When contributing, keep the primary user interface in mind:

| Method | Role | Input | Output | | :--- | :--- | :--- | :--- | | __init__ | Configuration | api_key (str), engine_id (str) | Instance | | search | Raw Data Retrieval | query (str) | List of dictionaries (raw items) | | get_combined_text | Formatted Retrieval | query (str) | Formatted string (top 5 results) |