Metadata-Version: 2.4
Name: naze-api
Version: 2.1.0
Summary: Official Python Client SDK for Naze API (https://naze.dev)
Author-email: nazedev <devnaze@gmail.com>
License: ISC
Project-URL: Homepage, https://naze.dev
Project-URL: Documentation, https://naze.dev/docs
Project-URL: Repository, https://github.com/nazedev/naze-api-python
Project-URL: Bug Tracker, https://github.com/nazedev/naze-api-python/issues
Keywords: naze,naze-api,sdk,api,downloader,tiktok-downloader,ai,gemini,tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

<div align="center">

# naze-api (Python SDK)

[![PyPI Version](https://img.shields.io/pypi/v/naze-api.svg?style=flat-square)](https://pypi.org/project/naze-api/)
[![Python Versions](https://img.shields.io/pypi/pyversions/naze-api.svg?style=flat-square)](https://pypi.org/project/naze-api/)
[![License](https://img.shields.io/github/license/nazedev/naze-api-python.svg?style=flat-square)](https://github.com/nazedev/naze-api-python/blob/main/LICENSE)

<br/>

**The official enterprise-grade Python client SDK for [Naze API](https://naze.dev).**

Fast, lightweight, strictly typed, with native synchronous and asynchronous (`asyncio`) support.

</div>

---

## Features

- **🚀 1,290+ Endpoints**: Full programmatic access to the entire Naze API ecosystem across 30 categories.
- **⚡ Dual Mode (Sync & Async)**: Supports both traditional synchronous scripts and high-concurrency `asyncio` (FastAPI, Telethon, aiogram, discord.py).
- **🎯 Dynamic Method Dispatch**: Call any endpoint semantically via `client.<category>.<endpoint>(**kwargs)`.
- **🛡️ Built-in Error Handling**: Typed exceptions (`RateLimitError`, `AuthenticationError`, `NazeApiError`).
- **📦 Clean Dot-Accessible Response**: Access fields directly (`res.data`, `res.success`) or as standard dictionaries (`res["data"]`).

---

## Installation

Install using `pip`:

```bash
pip install naze-api
```

Or with `uv`:

```bash
uv add naze-api
```

---

## Quick Start (Synchronous)

```python
from naze import Naze

# Initialize client (automatically reads NAZE_API_KEY from environment if omitted)
client = Naze(api_key="YOUR_API_KEY")

# 1. Download TikTok Video
result = client.download.tiktok(url="https://www.tiktok.com/@user/video/123456789")
print(result.data)

# 2. AI Chat
chat_res = client.ai.chat(message="Halo Naze AI!")
print(chat_res.data.response)

# 3. Check Domain WHOIS
whois = client.tools.whois(domain="naze.dev")
print(whois.data)

# 4. Verify API Key and Quota
auth_info = client.auth.verify()
print(auth_info.data)
```

---

## Asynchronous Usage (`asyncio` / Bot Development)

Perfect for Telegram bots (`aiogram`, `telethon`, `pyrogram`), Discord bots (`discord.py`), or FastAPI backends:

```python
import asyncio
from naze import AsyncNaze

async def main():
    async with AsyncNaze(api_key="YOUR_API_KEY") as client:
        # Download video
        res = await client.download.tiktok(url="https://www.tiktok.com/@user/video/123")
        print("Download URL:", res.data)

        # AI prompt
        ai = await client.ai.chat(message="Jelaskan konsep asynchronous di Python.")
        print("AI Response:", ai.data.response)

if __name__ == "__main__":
    asyncio.run(main())
```

---

## Category Namespaces (30 Categories)

The SDK organizes all 1,290+ endpoints into structured namespaces:

| Namespace | Access via | Description |
| :--- | :--- | :--- |
| **Authentication** | `client.auth` | Key verification, quota introspection, remaining daily hit |
| **AI** | `client.ai` | Gemini, DeepSeek, ChatGPT, Copilot, image generation |
| **Animals** | `client.animals` | Animal facts, breeds, converters |
| **Anime** | `client.anime` | Jikan, anime search, wallpapers, schedules |
| **Bypass** | `client.bypass` | Link decoders and shortener bypassers |
| **Create** | `client.create` | Brat generator, meme maker, image filters, text styling |
| **Developer** | `client.developer` | DNS lookup, whois, package info, IP intelligence |
| **Downloader** | `client.download` | TikTok, YouTube, Instagram, Douyin, Spotify, Facebook |
| **Education** | `client.education` | Quran, space datasets, math solvers, astronomy |
| **Entertainment** | `client.entertainment` | Jokes, trivia, text transforms |
| **Ephoto360** | `client.ephoto360` | 3D typography and text photo effects |
| **Finance** | `client.finance` | Currency rates, bank code lookup, stocks, crypto |
| **Games** | `client.games` | Game ID stalkers, ML, FreeFire, Genshin stats |
| **Geography** | `client.geography` | Country info, coordinates, geospatial tools, patents |
| **Health** | `client.health` | Medical calculators, BMI, calorie metrics |
| **Media** | `client.media` | Subtitle search, stream helpers, media metadata |
| **Music** | `client.music` | Song search, track details, lyrics, Spotify |
| **News** | `client.news` | Real-time global and Indonesian news feeds |
| **Other** | `client.other` | CleanURL, postal codes, fear & greed index |
| **Photofunia** | `client.photofunia` | Billboard, retro, graffiti templates |
| **Primbon** | `client.primbon` | Weton, ramalan jodoh, arti mimpi, hari baik |
| **Random** | `client.random` | Quotes, memes, random facts |
| **Religion** | `client.religion` | Hadith, daily prayers, Islamic schedules |
| **Search** | `client.search` | Web search, YouTube, TikTok search, Google CSE |
| **Social** | `client.social` | Stalker tools, profile metrics, follower analysis |
| **Sports** | `client.sports` | Sports fixtures, standings, tournament tables |
| **Text** | `client.text` | Morse, Zalgo, ciphers, language detector |
| **Textpro** | `client.textpro` | 100+ TextPro 3D neon, glowing, and glitch banners |
| **Tools** | `client.tools` | 2FA, QR code generator, barcode, NIK checker |
| **Upload** | `client.upload` | Temporary file and image uploaders |
| **Weather** | `client.weather` | BMKG weather forecasts, earthquake alerts |

---

## Error Handling

```python
from naze import Naze
from naze.exceptions import RateLimitError, AuthenticationError, NazeApiError

client = Naze(api_key="YOUR_API_KEY")

try:
    res = client.download.tiktok(url="https://...")
except AuthenticationError:
    print("Invalid or expired API Key!")
except RateLimitError as e:
    print(f"Rate limit exceeded! Retry after {e.retry_after} seconds.")
except NazeApiError as e:
    print(f"API Error [{e.status_code}]: {e.message}")
```

---

## License

ISC License © [Naze Dev](https://naze.dev).
