Metadata-Version: 2.4
Name: google-search-resource
Version: 0.0.2
Summary: A tool for researching and analyzing Google search page behavior and structure
Author-email: Yaacov Zamir <kobi.zamir@gmail.com>
Maintainer-email: Yaacov Zamir <kobi.zamir@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yaacov/gsr
Project-URL: Documentation, https://github.com/yaacov/gsr#readme
Project-URL: Repository, https://github.com/yaacov/gsr
Project-URL: Issues, https://github.com/yaacov/gsr/issues
Keywords: google,search,research,web-scraping,playwright,captcha-detection,browser-automation,analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Browsers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Dynamic: license-file

# Google Search Resource (GSR)

A tool for researching and analyzing Google search page behavior and structure.

## Purpose

GSR is designed for legitimate research purposes:
- Understanding how Google search pages are structured
- Analyzing search result formatting
- Studying how search interfaces change over time
- Educational purposes and web development learning

## Installation

### From PyPI

```bash
# Install the package
pip install google-search-resource

# Install playwright browsers
playwright install chromium firefox
```

### From Source

```bash
# Clone the repository
git clone https://github.com/yaacov/gsr.git
cd gsr

# Complete setup (create venv, install dependencies and browsers)
make setup

# Activate virtual environment
source venv/bin/activate
```

## Usage

### Command Line Interface

After installation, use the `gsr` command:

```bash
# Basic usage with default query
gsr

# Custom search query
gsr --query "machine learning"

# Headless mode (no browser window)
gsr --headless --query "python web scraping"

# Get help
gsr --help
```

### Available CLI Options

```bash
gsr [OPTIONS]

Options:
  --query, -q TEXT          Search query
  --headless                Run browser in headless mode
  --new-session             Force create new session
  --session-id TEXT         Use specific session ID
  --typing [fast|normal|slow]  Typing speed style
  --max-results INT         Maximum results to display
  --verbose, -v             Increase verbosity (-v: INFO, -vv: DEBUG)
  --quiet                   Suppress all output except results
  --timeout INT             Timeout in seconds
  --browser [chromium|firefox]  Browser to use
  --output-format [text|json|csv]  Output format
  --no-images               Disable image loading
  --config PATH             Load configuration from YAML/JSON file
```

## Usage Examples

### Library Usage

```python
from gsr.searcher import HumanLikeGoogleSearcher
from gsr.enums import SearchStatus

# Simple search with defaults
searcher = HumanLikeGoogleSearcher()

try:
    result = searcher.search("python programming")
    
    if result.status == SearchStatus.SUCCESS:
        for r in result.results:
            print(f"{r['title']}: {r['url']}")
    
    elif result.status == SearchStatus.CAPTCHA_DETECTED:
        print("Rate limit reached - stopping research")
        
finally:
    searcher.close()
```

## Development

### Setup for Contributors

```bash
# Clone and setup
git clone https://github.com/yaacov/gsr.git
cd gsr

# Install with dev dependencies
make install-dev
make install-browsers

# Code quality tools
make format        # Auto-format code
make lint          # Check code style
make format-check  # Check formatting without changes
```

### Building and Publishing

```bash
# Build package
make build

# Test on TestPyPI
make publish-test

# Publish to PyPI (production)
make publish
```

## License

MIT License - Copyright (c) 2025 Yaacov Zamir

For educational and research purposes.
