Metadata-Version: 2.4
Name: hypestat
Version: 0.0.1
Summary: A Python package to fetch website statistics from Hypestat.com
Author: Luna-Marika Dahl
Author-email: Luna-Marika Dahl <lunamarika@proton.me>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.32.5
Requires-Python: >=3.10
Project-URL: HomePage, https://github.com/simplylu/hypestat
Project-URL: Issues, https://github.com/simplylu/hypestat/issues
Description-Content-Type: text/markdown

# hypestat

A Python package to fetch website statistics from [Hypestat.com](https://hypestat.com).

## Overview

`hypestat` provides a simple interface to scrape and retrieve comprehensive website statistics from Hypestat.com, including traffic data, rankings, revenue estimates, and visitor information.

## Installation

```bash
pip install hypestat
```

## Features

- Fetch website statistics including:
  - Global rank
  - Percentage of global internet users
  - Daily impressions
  - Visitor countries
  - Daily revenue estimates
  - Estimated website value
  - Daily visitors
  - Monthly visits
- Automatic update of outdated statistics
- Session-based requests for efficient data fetching

## Usage

### Basic Example

```python
from hypestat import HypeStat

# Create an instance
hs = HypeStat()

# Get statistics for a domain
stats = hs.get_stats("example.com")

# Access the statistics
print(f"Global Rank: #{stats.rank}")
print(f"Daily Visitors: {stats.daily_visitors}")
print(f"Monthly Visits: {stats.monthly_visits}")
print(f"Daily Revenue: ${stats.daily_revenue}")
print(f"Estimated Value: ${stats.estimated_value}")
print(f"Global Internet Users: {stats.global_internet_users}%")
print(f"Daily Impressions: {stats.impressions}")
print(f"Visitor Countries: {', '.join(stats.visitor_countries)}")
```

## API Reference

### `HypeStat` Class

Main class for interacting with Hypestat.com.

#### Methods

- **`get_stats(domain: str) -> Stats`**
  
  Fetches and returns comprehensive statistics for the specified domain. Automatically attempts to update statistics if they're outdated.
  
  - **Parameters:** `domain` - The domain name to fetch statistics for (e.g., "example.com")
  - **Returns:** `Stats` object containing all website statistics

- **`update_stats(domain: str) -> bool`**
  
  Manually triggers a statistics update for a domain if the data is outdated.
  
  - **Parameters:** `domain` - The domain name to update
  - **Returns:** `True` if update was initiated, `False` if statistics are current or update unavailable

### `Stats` Class

Data class holding website statistics.

#### Attributes

- **`rank`** (int): Global rank of the website
- **`global_internet_users`** (float): Percentage of global internet users
- **`impressions`** (int): Number of daily impressions
- **`visitor_countries`** (list[str]): List of visitor countries
- **`daily_revenue`** (float): Daily revenue estimate in USD
- **`estimated_value`** (float): Estimated value of the website in USD
- **`daily_visitors`** (int): Number of daily visitors
- **`monthly_visits`** (int): Number of monthly visits

## License

This project is licensed under the GPLv3 License - see the LICENSE file for details.

## Disclaimer

This package scrapes data from Hypestat.com. Please be respectful of their terms of service and use this tool responsibly. The accuracy of the data depends on Hypestat.com's own data collection and estimation methods.
