Metadata-Version: 2.4
Name: hotpepper-gourmet-tddschn
Version: 0.0.8
Summary: A simple Python client of Hotpepper API
Project-URL: Repository, https://github.com/tddschn/hotpepper-gourmet
Author: Miura Kosuke, T
Maintainer: Miura Kosuke
License: MIT License
        
        Copyright (c) 2022 Miura Kosuke
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.txt
Keywords: api,client,hotpepper
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.2.0
Description-Content-Type: text/markdown

# hotpepper-gourmet-tddschn

[![PyPI version](https://badge.fury.io/py/hotpepper-gourmet-tddschn.svg)](https://badge.fury.io/py/hotpepper-gourmet-tddschn)
![workflow badge](https://github.com/tddschn/hotpepper-gourmet-tddschn/actions/workflows/ci.yml/badge.svg)
![workflow badge](https://github.com/tddschn/hotpepper-gourmet-tddschn/actions/workflows/publish.yml/badge.svg)

## About

Fork of hotpepper-gourmet package on pypi (https://github.com/paperlefthand/hotpepper-gourmet) that uses https instead of http.

[ホットペッパーグルメAPI](https://webservice.recruit.co.jp/doc/hotpepper/reference.html)のシンプルなクライアントライブラリです

## API Coverage

This library now covers all official Hotpepper Gourmet endpoints (12/12).

| API (Official)            | Python method (sync / async)                                    |
| :------------------------ | :-------------------------------------------------------------- |
| Gourmet Search            | `search` / `search_async`                                       |
| Shop Name Search          | `name_search` / `name_search_async`                             |
| Budget Master             | `budget_master` / `budget_master_async`                         |
| Large Service Area Master | `large_service_area_master` / `large_service_area_master_async` |
| Service Area Master       | `service_area_master` / `service_area_master_async`             |
| Large Area Master         | `large_area_master` / `large_area_master_async`                 |
| Middle Area Master        | `middle_area_master` / `middle_area_master_async`               |
| Small Area Master         | `small_area_master` / `small_area_master_async`                 |
| Genre Master              | `genre_master` / `genre_master_async`                           |
| Credit Card Master        | `credit_card_master` / `credit_card_master_async`               |
| Special Master            | `special_master` / `special_master_async`                       |
| Special Category Master   | `special_category_master` / `special_category_master_async`     |

## Language Notation (Japan topics)

In this project, when we reference Japan-related proper nouns or useful markers, we include:

- Japanese + Romaji (e.g., 東京, Tōkyō)
- zh_TW for kana terms (e.g., グルメ, gurume, 美食)
- Original language for katakana transliterations (e.g., ホットペッパー, Hotto Peppaa, Hot Pepper)

Examples:

- 東京 (とうきょう, Tōkyō, 東京)
- 新宿 (しんじゅく, Shinjuku, 新宿)
- ラーメン (raamen, 拉麵, ramen)
- ジャンル (janru, 類型, genre)

## How To Use

### keyidの取得

ホットペッパーグルメAPIに登録し, token(keyid)を取得

CLI利用時は環境変数 `HOTPEPPER_API_KEY` を使用します:

```bash
export HOTPEPPER_API_KEY="YOUR_KEYID"
```

### サンプルコード

同期版

```python
>>> from pygourmet import Api, Option
>>> api = Api(keyid=YOUR_KEYID)
>>> option = Option(lat=35.170915, lng=136.8793482, keyword="ラーメン", range=4, count=3)
>>> shops = api.search(option)
>>> len(shops)
3
>>> shops[0].name
'shop name'
```

複数値クエリと拡張レスポンス (`type=special+credit_card`) の例:

```python
from pygourmet import Api, Option

api = Api(keyid="YOUR_KEYID")
option = Option(
    keyword="焼肉",
    large_area=["Z011", "Z012"],
    budget=["B001", "B002"],
    type=["special", "credit_card"],
)

shops = api.search(option)
first = shops[0]

# `type=special+credit_card` を指定した場合もモデルで取得可能
if first.special:
    print(first.special[0].name)
if first.credit_card:
    print(first.credit_card[0].name)
```

マスタAPIの例（ジャンル + 大エリア）:

```python
from pygourmet import Api, GenreMasterOption, LargeAreaMasterOption

api = Api(keyid="YOUR_KEYID")

genres = api.genre_master(GenreMasterOption(keyword="居酒屋"))
areas = api.large_area_master(LargeAreaMasterOption(keyword="東京"))

print(genres[0].code, genres[0].name)
print(areas[0].code, areas[0].name)
```

非同期版

```python
async def call_search_async():
    shops = await api.search_async(option=option)
    print(len(shops))

loop = asyncio.get_event_loop()
loop.run_until_complete(call_search_async())
```

### CLI: hotpepper-cli

インストール後は `hotpepper-cli` コマンドが利用できます.

グルメ検索（東京 / とうきょう / Tōkyō / 東京）:

```bash
hotpepper-cli search --keyword "ラーメン" --large-area Z011 --count 5
```

店名サーチ（新宿 / しんじゅく / Shinjuku / 新宿）:

```bash
hotpepper-cli name-search --keyword 新宿 --count 10
```

ジャンルマスタ取得（JSON出力）:

```bash
hotpepper-cli -j genre --keyword 居酒屋
```

特集カテゴリ取得:

```bash
hotpepper-cli special-category
```

補足:

- `-j`, `--json`: JSONを標準出力
- 省略時は Rich テーブルで整形表示
- APIキーは `--api-key` で直接指定も可能

## 開発者向けガイド

このリポジトリは [uv](https://docs.astral.sh/uv/) によるパッケージ管理を採用しています.
Python バージョンは 3.12, 3.13, 3.14 をサポート対象としています.

### セットアップ

```bash
# 依存関係のインストール（開発環境構築）
uv sync
```

### よく使うコマンド

原則として `uv run` を介して実行します.

```bash
# テスト実行
uv run pytest -v

# 統合テスト実行（要 HOTPEPPER_KEYID 環境変数）
# ローカル環境でのみ実行し、APIキーを利用して実際にリクエストを送ります
uv run pytest --run-integration

# 静的型チェック
uv run ty check

# Lint チェック
uv run ruff check .

# コードフォーマット適用
uv run ruff format .

# コミット前チェック（Lint/Format/TypeCheck 等を一括実行）
uv run prek

# API ドキュメント生成
uv run pdoc src/pygourmet

# 特定バージョンの動作確認（tox）
uv run tox -e py314
```

### コーディング規約

- **Style**: Ruff 準拠 (4スペースインデント, ダブルクォート, スネークケース). クラス名は PascalCase.
- **Docstring**: Google Style.
- **Type**: Pydantic v2 を活用し, `Any` を排除した厳格な型注釈を行う.

### テストガイドライン

- **基本**: `pytest` + `pytest-httpx` (モック).
- **統合テスト**: `@pytest.mark.integration` を付与. `uv run pytest --run-integration` でのみ実行される.
- **非同期**: `pytest-asyncio` を使用.

### コミット・PRガイドライン

- コミットメッセージは **Conventional Commits** 形式.
- コミット前に必ず `uv run prek` をパスさせること.
- PR には変更の目的, テスト結果, ドキュメント更新の有無を記載.

### CI/CD

- **CI**: GitHub Actions + `tox-uv` (Python 3.12, 3.13, 3.14).
- **TestPyPI**: `dev` ブランチへの push で自動デプロイ.
- **PyPI / Docs**: `v*` タグ (例: `v1.0.0`) の push で本番リリースおよび GitHub Pages 更新.

### セキュリティ

- API Key (`HOTPEPPER_KEYID`) は絶対コミットしない.
- ローカル開発では `.env` を利用する (`python-dotenv` 対応).

___

Powered by [ホットペッパー Webサービス](https://webservice.recruit.co.jp/)
