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
Eternityyou 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:
- Open an issue and label it as a Feature Request.
- Explain the use case—how does this help a user retrieving web data?
- 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:
- Fork the repository on GitHub.
- Clone your fork locally:
git clone https://github.com/yourusername/eternity.git cd eternity - Install dependencies:
Note: The library requires the
pip install -e .requestspackage.
Pull Request Process
- Create a branch for your fix or feature:
git checkout -b feature/your-feature-name - Implement your changes. If you are adding a new method to the
Eternityclass, ensure it follows the existing pattern of usingself.api_keyandself.engine_idfor authentication. - 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")) - 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
searchorget_combined_text), include a docstring explaining the parameters and the return type. - Keep it Modular: Focus on the
Eternityclass 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) |