Metadata-Version: 2.5
Name: pyzaimflow
Version: 0.0.3
Summary: マネー・プラットフォーム「Zaim」からデータを取得するためのパッケージ
Project-URL: Repository, https://github.com/fniplot/pyzaimflow.git
Project-URL: Issues, https://github.com/fniplot/pyzaimflow/issues
Author-email: fniplot <cyari.buran@gmail.com>
License: MIT License
        
        Copyright (c) 2026 fniplot
        
        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
Requires-Python: >=3.10
Requires-Dist: certifi==2026.7.22
Requires-Dist: charset-normalizer==3.4.9
Requires-Dist: idna==3.18
Requires-Dist: oauthlib==3.3.1
Requires-Dist: requests-oauthlib==2.0.0
Requires-Dist: requests==2.34.2
Requires-Dist: urllib3==2.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# pyzaimflow

`pyzaimflow` は、株式会社くふうカンパニーホールディングスが運営するマネー・プラットフォーム「Zaim」からデータを取得・連携するための Python パッケージです。主に Zaim API のラッパー機能を提供し、今後は Web 画面のスクレイピング機能も追加予定です。

## 概要

`pyzaimflow` が提供する主な機能は次のとおりです。

- Zaim API を利用したデータの取得・登録・更新・削除
  - Zaim が提供する Web API を扱いやすくするラッパー機能を提供します。
  - Zaim の OAuth 1.0a 認証を支援する CLI を提供します（今後提供予定）。
- Zaim の Web 画面をスクレイピングして、API では取得できないデータを収集します（今後提供予定）。
  - たとえば、銀行／クレジットカードの明細など、API では取得できない情報を補完します。

## パッケージが提供する API 一覧

API の一覧と詳細は、GitHub の [Wiki](https://github.com/fniplot/pyzaimflow/wiki) を参照してください。

## 推奨環境

- Python 3.10.12 以上

## 事前準備

[くふう.Zaim](https://zaim.net/) にアクセスして Zaim のアカウントを作成してください。アカウントの作成方法については、リンク先を参照してください。本ドキュメントでは、アカウント作成手順については省略します。

## インストール

```bash
pip install pyzaimflow
```

## パッケージの使い方

Zaim API を呼び出すには、コンシューマ ID とコンシューマシークレットが必要です。取得方法については、GitHub の [Wiki](https://github.com/fniplot/pyzaimflow/wiki) を参照してください。

以下のコード例では、取得したコンシューマ ID とコンシューマシークレットを使って OAuth 認証フローを開始し、アクセストークンとアクセストークンシークレットを生成する方法を示します。

```python
from pyzaimflow import OAuthConfig, OAuthFlow

# OAuthConfig を作成
config = OAuthConfig(
    "コンシューマ ID",
    "コンシューマシークレット",
)

# OAuth 認証フローを初期化
flow = OAuthFlow(config)

# OAuth 認証フローを開始
flow.start()

# 出力した認可 URL にアクセスし、Zaim の認証画面で「ログインして許可する」ボタンをクリックしてください。「認証が完了」画面に遷移し、画面に検証コードが表示されます。表示された検証コードをコピーして、ターミナルに貼り付けてください。
print("認可 URL:", flow.authorize_url())

verifier = input("検証コードを入力してください: ")

access = flow.complete(verifier)

print("アクセストークン:", access.oauth_token)
print("アクセストークンシークレット:", access.oauth_token_secret)
```

Zaim API を呼び出すには、上記のコード例で取得したアクセストークンとアクセストークンシークレットを使って、`pyzaimflow` の API クライアントを初期化してください。

```python
from pyzaimflow import ZaimApi, ZaimConfig

# ZaimConfig を作成
zaim_config = ZaimConfig(
    "コンシューマ ID",
    "コンシューマシークレット",
    "アクセストークン",
    "アクセストークンシークレット",
)

# ZaimApi を初期化
zaim_api = ZaimApi(zaim_config)

# たとえば、2026年1月1日の家計簿の記録を取得する場合は、以下のようにします。
money = zaim_api.list_money(
    start_date="2026-01-01",
    end_date="2026-01-01",
)

# 取得した家計簿の記録を出力する場合は、以下のようにします。
print(money)
```
