Introduction

Overview

Eternity is a lightweight Python library designed for real-time data retrieval from the web. By leveraging Google’s Custom Search infrastructure, Eternity allows developers to programmatically access live search results, metadata, and web snippets with minimal setup.

Whether you are building a research tool, an AI agent that requires current information, or a data pipeline, Eternity provides a streamlined interface to fetch and process web content in seconds.

Key Features

• Real-Time Retrieval: Access the most current data available on the web via Google Custom Search.
• Structured Search: Retrieve raw JSON-like result objects including titles, links, and snippets.
• Content Aggregation: Automatically format and combine top search results into human-readable text blocks for easier consumption by LLMs or end-users.
• Simple Configuration: Minimal boilerplate required to get from installation to your first search query.

Quick Start

To begin using Eternity, you must provide a valid Google API Key and a Search Engine ID (CX).

from eternity import Eternity

# Initialize the client
et = Eternity(api_key="YOUR_GOOGLE_API_KEY", engine_id="YOUR_ENGINE_ID")

# Retrieve combined results as a formatted string
data = et.get_combined_text("Latest developments in quantum computing")
print(data)

Core Capabilities

Raw Search

The search() method provides direct access to the search results. This is ideal when you need to process specific metadata or iterate through all returned items.

• Input: query (string)
• Output: A list of dictionaries, where each dictionary represents a search result containing keys like title, link, and snippet.

results = et.search("Python web scraping best practices")

for item in results:
    print(f"Source: {item.get('title')}")
    print(f"Link: {item.get('link')}")

Combined Text Retrieval

The get_combined_text() method is a utility designed for rapid data extraction. It fetches the top 5 results and formats them into a single, structured string. This is particularly useful for providing context to Large Language Models (LLMs).

• Input: query (string)
• Output: A formatted string containing the Title, Snippet, and URL for the top 5 search results.

# Useful for RAG (Retrieval-Augmented Generation) applications
context = et.get_combined_text("Weather forecast Tokyo")

Requirements

Before using Eternity, ensure you have:

1. Requests: The library depends on the requests package for HTTP communication.
2. Google Cloud Console Project: An active project with the "Custom Search API" enabled.
3. Programmable Search Engine: A search engine ID created via Google Programmable Search.