Metadata-Version: 2.4
Name: gfg-search
Version: 0.1.0
Summary: Unofficial Python client for GeeksforGeeks search API
Author: gfg-search contributors
License: MIT
Project-URL: Homepage, https://www.geeksforgeeks.org
Project-URL: Repository, https://www.geeksforgeeks.org
Project-URL: Issues, https://www.geeksforgeeks.org
Keywords: geeksforgeeks,search,api,gfg
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# gfg-search

`gfg-search` is an unofficial Python client for the GeeksforGeeks search API.

It wraps the endpoint:

`https://www.geeksforgeeks.org/gfg-assets/_next/data/<build-id>/search.json?gq=<query>`

and automatically discovers the current `<build-id>` from the GeeksforGeeks homepage.

## Features

- Simple one-line search function.
- Reusable client class with connection/session reuse.
- Typed result model via `dataclass`.
- Raw response access when needed.

## Installation

From PyPI (after publishing):

```bash
pip install gfg-search
```

From local source:

```bash
pip install .
```

## Quick Start

```python
from gfg_search import search

results = search("dsa", max_results=5)
for item in results:
    print(item.title)
    print(item.link)
    print(item.snippet)
    print("-")
```

## Client Usage

```python
from gfg_search import GFGSearchClient

client = GFGSearchClient(timeout=12)
results = client.search("python")

first = results[0]
print(first.title)
print(first.link)
```

## Raw Response Usage

```python
from gfg_search import GFGSearchClient

client = GFGSearchClient()
raw_items = client.search_raw("graph")

print(type(raw_items))
print(raw_items[0].keys())
```

## API Reference

### `search(query, *, max_results=None, timeout=10.0)`

- `query` (`str`): Search text.
- `max_results` (`int | None`): Limit the number of returned results.
- `timeout` (`float`): Timeout (seconds) for HTTP requests.

Returns `list[SearchResult]`.

### `GFGSearchClient(timeout=10.0, base_url="https://www.geeksforgeeks.org", session=None)`

Methods:

- `search(query, *, max_results=None) -> list[SearchResult]`
- `search_raw(query) -> list[dict]`

### `SearchResult`

Main fields:

- `title`
- `link`
- `snippet`
- `display_link`
- `formatted_url`
- `html_title`
- `html_snippet`
- `kind`
- `pagemap`

## Error Handling

```python
from gfg_search import GFGSearchClient, GFGSearchHTTPError, GFGSearchParsingError

client = GFGSearchClient()

try:
    print(client.search("dynamic programming", max_results=3))
except GFGSearchHTTPError as exc:
    print("Network error:", exc)
except GFGSearchParsingError as exc:
    print("Response format error:", exc)
```

## Notes

- This package is unofficial and not affiliated with GeeksforGeeks.
- Since this endpoint is internal to their web app, response shape or route behavior may change in future.

## Development

Run a local editable install:

```bash
pip install -e .
```

Build distribution artifacts:

```bash
python -m build
```

## License

MIT
