> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoo.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Spoo.me Python SDK

The official Python library makes it easy to integrate Spoo.me's URL shortening service into your Python applications.

## Installation

Install the library using pip:

<CodeGroup>
  ```bash pip theme={null}
  pip install py_spoo_url
  ```

  ```bash pip3 theme={null}
  pip3 install py_spoo_url
  ```

  ```bash uv theme={null}
  uv add py_spoo_url
  ```
</CodeGroup>

## Quick Start

Here's a simple example to get you started:

```python theme={null}
from py_spoo_url import Shorten, Statistics

# Initialize the shortener
shortener = Shortener()

# Shorten a URL
long_url = "https://www.example.com"
short_url = shortener.shorten(long_url)
print(f"Shortened URL: {short_url}")
```

## Features

<CardGroup cols={2}>
  <Card title="URL Shortening" icon="link" color="#A855F7">
    Shorten URLs with custom aliases and settings
  </Card>

  <Card title="Statistics" icon="chart-line" color="#A855F7">
    Get detailed analytics for your shortened URLs
  </Card>

  <Card title="Data Export" icon="download" color="#A855F7">
    Export your URL data in various formats
  </Card>

  <Card title="Rate Limiting" icon="clock" color="#A855F7">
    Built-in rate limiting to respect API limits
  </Card>
</CardGroup>

## Usage Examples

### Basic URL Shortening

```python theme={null}
from py_spoo_url import Shortener

shortener = Shortener()

# Simple shortening
result = shortener.shorten("https://example.com")
print(result)  # https://spoo.me/abc123
```

### Advanced URL Shortening

```python theme={null}
from py_spoo_url import Shortener

shortener = Shortener()

# Shorten with custom parameters
result = shortener.shorten(
    url="https://example.com",
    alias="myalias",
    password="SuperSecretPassword@444",
    max_clicks=100
)
print(f"Shortened URL: {result}")
```

### URL Statistics

```python theme={null}
from py_spoo_url import Statistics

stats = Statistics()

# Get statistics for a shortened URL
url_stats = stats.get_stats("abc123")  # short code
print(url_stats)

# Get statistics for password-protected URL
protected_stats = stats.get_stats("xyz789", password="yourpassword")
print(protected_stats)
```

### Data Export

```python theme={null}
from py_spoo_url import DataExport

exporter = DataExport()

# Export data in JSON format
json_data = exporter.export_data("abc123", format="json")

# Export data in Excel format
excel_data = exporter.export_data("abc123", format="xlsx")

# Save exported data to file
with open("url_data.xlsx", "wb") as f:
    f.write(excel_data)
```

### Error Handling

```python theme={null}
from py_spoo_url import Shortener, SpooMeError

shortener = Shortener()

try:
    result = shortener.shorten("https://example.com", alias="taken-alias")
    print(result)
except SpooMeError as e:
    print(f"Error: {e.error_type} - {e.message}")
    # Handle specific error types
    if e.error_type == "AliasError":
        print("The alias is already taken, try another one")
```

## API Reference

### Shortener Class

#### `shorten()`

Shortens a URL with optional parameters. Returns a shortened URL string.

<ParamField path="url" type="string" required>
  The URL to shorten. Must be a valid HTTP or HTTPS URL.
</ParamField>

<ParamField path="alias" type="string">
  Custom alias for the shortened URL. If not provided, a random short code will be generated.
</ParamField>

<ParamField path="password" type="string">
  Password protection for the shortened URL. Users will need to enter this password to access the original URL.
</ParamField>

<ParamField path="max_clicks" type="integer">
  Maximum number of clicks allowed for this shortened URL. Once reached, the URL will become inactive.
</ParamField>

<ParamField path="block_bots" type="boolean">
  Whether to block bots from accessing the shortened URL. Default is `false`.
</ParamField>

#### `emoji_shorten()`

Creates emoji-based shortened URLs. Returns a shortened URL string with emojis.

<ParamField path="url" type="string" required>
  The URL to shorten. Must be a valid HTTP or HTTPS URL.
</ParamField>

<ParamField path="emojies" type="string">
  Custom emoji sequence for the shortened URL. If not provided, random emojis will be used.
</ParamField>

<ParamField path="password" type="string">
  Password protection for the shortened URL. Users will need to enter this password to access the original URL.
</ParamField>

<ParamField path="max_clicks" type="integer">
  Maximum number of clicks allowed for this shortened URL. Once reached, the URL will become inactive.
</ParamField>

<ParamField path="block_bots" type="boolean">
  Whether to block bots from accessing the shortened URL. Default is `false`.
</ParamField>

### Statistics Class

#### `get_stats()`

Retrieves statistics for a shortened URL. Returns a dictionary containing detailed statistics.

<ParamField path="short_code" type="string" required>
  The short code of the URL for which to retrieve statistics.
</ParamField>

<ParamField path="password" type="string">
  Password if the URL is protected. Required only for password-protected URLs.
</ParamField>

### DataExport Class

#### `export_data()`

Exports URL data in various formats. Returns raw data in the specified format.

<ParamField path="short_code" type="string" required>
  The short code of the URL for which to export data.
</ParamField>

<ParamField path="format" type="string" required>
  Export format. Supported formats: `"json"`, `"csv"`, `"xlsx"`, `"xml"`.
</ParamField>

<ParamField path="password" type="string">
  Password if the URL is protected. Required only for password-protected URLs.
</ParamField>

## Configuration

### Custom Base URL

```python theme={null}
from py_spoo_url import Shortener

# Use custom base URL (if needed)
shortener = Shortener(base_url="https://spoo.me")
```

### Rate Limiting Configuration

```python theme={null}
from py_spoo_url import Shortener

# Configure rate limiting
shortener = Shortener(
    rate_limit_per_minute=5,
    rate_limit_per_hour=50,
    rate_limit_per_day=500
)
```

## Error Types

The library provides specific error types for different scenarios:

<Accordion title="SpooMeError">
  Base exception class for all Spoo.me related errors.

  **Attributes:**

  * `error_type`: The type of error (e.g., "UrlError", "AliasError")
  * `message`: Detailed error message
  * `status_code`: HTTP status code
</Accordion>

<Accordion title="UrlError">
  Raised when the provided URL is invalid or missing.

  ```python theme={null}
  try:
      shortener.shorten("invalid-url")
  except UrlError as e:
      print(f"Invalid URL: {e.message}")
  ```
</Accordion>

<Accordion title="AliasError">
  Raised when the requested alias is invalid or already taken.

  ```python theme={null}
  try:
      shortener.shorten("https://example.com", alias="taken")
  except AliasError as e:
      print(f"Alias error: {e.message}")
  ```
</Accordion>

<Accordion title="PasswordError">
  Raised when the password doesn't meet requirements.

  ```python theme={null}
  try:
      shortener.shorten("https://example.com", password="weak")
  except PasswordError as e:
      print(f"Password error: {e.message}")
  ```
</Accordion>

<Accordion title="RateLimitError">
  Raised when API rate limits are exceeded.

  ```python theme={null}
  try:
      shortener.shorten("https://example.com")
  except RateLimitError as e:
      print(f"Rate limit exceeded. Retry after: {e.retry_after} seconds")
  ```
</Accordion>

## Complete Documentation

For comprehensive documentation, code examples, and advanced usage patterns, visit the complete library documentation:

<Card title="View Complete Documentation" icon="book-open" href="https://py-spoo-url.readthedocs.io/">
  Access detailed documentation, API reference, and advanced examples
</Card>

## Contributing

The library is open source and welcomes contributions:

<Card title="GitHub Repository" icon="github" href="https://github.com/spoo-me/py-spoo-url">
  Contribute to the project, report issues, or suggest improvements
</Card>

## Support

If you encounter any issues with the Python library:

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/spoo-me/py-spoo-url/issues">
    Report bugs or request features
  </Card>

  <Card title="Discord Support" icon="discord" href="https://spoo.me/discord">
    Get help from the community
  </Card>
</CardGroup>