Metadata-Version: 2.4
Name: naipy
Version: 3.0.0
Summary: A simple and efficient Python wrapper for Naver API (Search, Papago Translation)
Home-page: https://github.com/d3vksy/Naipy
Author: devksy
Author-email: devksy <d3vksy@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/d3vksy/Naipy
Project-URL: Documentation, https://naipy.notion.site/
Project-URL: Repository, https://github.com/d3vksy/Naipy.git
Project-URL: Issues, https://github.com/d3vksy/Naipy/issues
Keywords: naver,api,search,papago,translation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Korean
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

<div align="center">
  <h1>Naipy(네이피)</h1>
  <p><strong>누구나 쉽게 사용할 수 있는 네이버 API 래퍼</strong></p>
</div>

![image](https://user-images.githubusercontent.com/103942316/184539416-9568fad2-24ed-4832-8f01-e2775a89fafe.png)

[![PyPI version](https://img.shields.io/pypi/v/naipy.svg)](https://pypi.python.org/pypi/naipy)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> [2022 공개SW 개발자 대회 이노그리드 대표상 수상 작품](https://www.oss.kr/dev_competition_activities/show/8df8c099-9b18-454f-a3e1-29baa00116ad)

Naipy는 **네이버 API를 쉽게 사용**할 수 있도록 만든 파이썬 래퍼 라이브러리입니다.

## 주요 특징

- **동기/비동기 모두 지원** - 상황에 맞게 선택해서 사용
- **9가지 검색 API** - 이미지, 블로그, 도서, 백과사전 등
- ~~**번역 기능** - 언어감지 및 다중언어 번역 지원~~ (Papago API 서비스 종료 2024-02-29)
- **타입 안정성** - 완벽한 타입 힌팅으로 IDE 자동완성 지원
- **최신 Python** - Python 3.10+ 표준 준수
- **포괄적 문서** - 명확한 문서화와 예제 제공

## 설치

```bash
pip install naipy
```

또는 최신 개발 버전을 사용하려면:

```bash
pip install git+https://github.com/d3vksy/Naipy.git
```

## 빠른 시작

### 동기 방식

```python
from naipy import sync

# API 키 없이 사용 가능 (샘플키 사용)
search = sync.Search()

# 이미지 검색
result = search.image("강아지")
print(result.title)
print(result.link)
print(result.thumbnail)

# 블로그 검색
blog_result = search.blog("파이썬 튜토리얼")
print(blog_result.bloggername)
print(blog_result.postdate)
```

### 비동기 방식

```python
import asyncio
from naipy import client

async def main():
    search = client.Search()

    result = await search.image("고양이")
    print(result.title)
    print(result.link)

asyncio.run(main())
```

## API 키 발급

프로덕션 환경에서는 **반드시 본인의 API 키를 발급받아 사용**하세요.

1. [네이버 개발자 센터](https://developers.naver.com/main/) 방문
2. 애플리케이션 등록
3. 발급받은 Client ID와 Client Secret 사용

```python
from naipy import sync

search = sync.Search(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
```

## 지원되는 API

### 검색 API

| 메서드                      | 설명               |
| --------------------------- | ------------------ |
| `search.image(query)`       | 이미지 검색        |
| `search.blog(query)`        | 블로그 검색        |
| `search.book(query)`        | 도서 검색          |
| `search.encyc(query)`       | 백과사전 검색      |
| `search.cafearticle(query)` | 카페 글 검색       |
| `search.kin(query)`         | 네이버 지식인 검색 |
| `search.webkr(query)`       | 웹페이지 검색      |
| `search.shop(query)`        | 쇼핑 검색          |
| `search.doc(query)`         | 전문자료 검색      |

### ~~번역 API~~ (서비스 종료)

> **Papago API가 2024-02-29부로 종료되었습니다.** 아래 메서드는 더 이상 동작하지 않습니다.

| 메서드                                         | 설명           |
| ---------------------------------------------- | -------------- |
| ~~`translator.detect(text)`~~                      | 언어 감지      |
| ~~`translator.translation(text, target)`~~         | 텍스트 번역    |
| ~~`translator.dual_translation(text, [targets])`~~ | 다중 언어 번역 |

## 응답 객체

각 검색 결과는 전문화된 데이터 클래스로 반환됩니다:

### ImageNaipy

- `title` - 이미지 제목
- `link` - 이미지 링크
- `thumbnail` - 썸네일 URL
- `sizeheight` - 이미지 높이
- `sizewidth` - 이미지 너비

### BlogNaipy

- `title` - 포스트 제목
- `link` - 포스트 링크
- `description` - 포스트 설명
- `bloggername` - 블로거 이름
- `bloggerlink` - 블로거 링크
- `postdate` - 발행일

### ShopNaipy

- `title` - 상품명
- `link` - 상품 링크
- `image` - 상품 이미지
- `lprice` - 최저가
- `hprice` - 최고가
- `mallName` - 쇼핑몰명
- `productId` - 상품 ID
- `brand` - 브랜드명

자세한 사항은 [공식 문서](https://naipy.notion.site/)를 참고하세요.

## 에러 처리

```python
from naipy import sync
from naipy.error import (
    NaipyException,
    AuthenticationError,
    PermissionError,
    RateLimitError,
    ValidationError,
)

try:
    search = sync.Search()
    result = search.image("test")
except AuthenticationError:
    print("API 인증 실패")
except RateLimitError:
    print("요청 한도 초과")
except ValidationError as e:
    print(f"입력값 오류: {e}")
except NaipyException as e:
    print(f"Naipy 오류: {e}")
```

## 고급 사용법

### ~~다중 언어 번역~~ (서비스 종료)

> Papago API 종료로 인해 동작하지 않습니다.

### 에러 핸들링 with 재시도

```python
import asyncio
from naipy import client
from naipy.error import RateLimitError

async def search_with_retry(query, max_retries=3):
    search = client.Search()

    for attempt in range(max_retries):
        try:
            return await search.image(query)
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt
                print(f"{wait_time}초 대기 후 재시도...")
                await asyncio.sleep(wait_time)
            else:
                raise

asyncio.run(search_with_retry("python"))
```

## 라이선스

이 프로젝트는 MIT 라이선스 하에서 배포됩니다. - [LICENSE](LICENSE) 파일 참고

## 기여

버그 리포트, 기능 제안, PR은 언제나 환영합니다!
