backlog-sdk 0.2.4
Python SDK for Backlog API v2
License: MIT
Requires Python: >=3.12

# Backlog Python SDK

🚀 **Nulab 社の Backlog API v2 の Python クライアントライブラリ**

Python3.12+に対応した、型安全で使いやすい Backlog API クライアントです。
コマンドラインツールも付属しており、Backlog を API や CLI から効率的に操作できます。

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![CI](https://github.com/yourusername/backlog-sdk/workflows/CI/badge.svg)](https://github.com/yourusername/backlog-sdk/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/backlog-sdk.svg)](https://badge.fury.io/py/backlog-sdk)
[![codecov](https://codecov.io/gh/yourusername/backlog-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/backlog-sdk)

## 📦 インストール

```bash
pip install backlog-sdk
```

開発版を使用する場合：

```bash
git clone https://github.com/yourusername/backlog-sdk.git
cd backlog-sdk
uv sync
uv pip install -e .
```

## 🚀 使用方法

### Python API

#### 基本的な使用方法

```python
from backlog_sdk import BacklogClient

# APIキー認証でクライアントを初期化
client = BacklogClient(
    space_id="your-space",
    auth="your-api-key"
)

# スペース情報を取得
space = client.space.get()
print(f"スペース: {space.name}")

# プロジェクト一覧を取得
for project in client.projects.list():
    print(f"プロジェクト: {project.name} ({project.project_key})")
```

#### 課題の操作

```python
from backlog_sdk.models.issue import AddIssueRequest

# 課題を作成
issue_request = AddIssueRequest(
    project_id=1,
    summary="新しい課題",
    issue_type_id=1,
    priority_id=3,
    description="課題の詳細説明"
)
new_issue = client.issues.create(issue_request)
print(f"課題を作成しました: {new_issue.issue_key}")

# 課題一覧を取得（ページネーション対応）
for issue in client.issues.list(project_id=1, status_id=[1, 2, 3]):
    print(f"{issue.issue_key}: {issue.summary}")

# 課題の詳細を取得
issue = client.issues.get("PROJ-123")
print(f"担当者: {issue.assignee.name if issue.assignee else '未割り当て'}")

# コメントを追加
comment = client.issues.add_comment("PROJ-123", "進捗を確認しました")
print(f"コメントを追加: {comment.id}")
```

#### OAuth2.0 認証

```python
from backlog_sdk import BacklogClient
from backlog_sdk.auth import OAuth2Auth

# OAuth2認証の設定
auth = OAuth2Auth(
    client_id="your-client-id",
    client_secret="your-client-secret",
    redirect_uri="http://localhost:8080/callback"
)

# 認可URLを生成
auth_url = auth.get_authorization_url("your-space.backlog.jp")
print(f"認証URL: {auth_url}")

# 認可コードを取得後、アクセストークンを取得
token_data = auth.get_access_token_sync("your-space.backlog.jp", "authorization-code")

# OAuth2認証でクライアントを初期化
client = BacklogClient(space_id="your-space", auth=auth)
```

#### Wiki 操作

```python
# Wiki一覧を取得
for wiki in client.wiki.list(project_id=1):
    print(f"Wiki: {wiki.name}")

# Wikiページを作成
from backlog_sdk.models.wiki import AddWikiRequest

wiki_request = AddWikiRequest(
    project_id=1,
    name="新しいWikiページ",
    content="# Wikiコンテンツ\n\nここに内容を書きます。"
)
new_wiki = client.wiki.create(wiki_request)
print(f"Wikiを作成: {new_wiki.name}")
```

### CLI

#### 初期設定

```bash
# 対話的に設定ファイルを作成
backlog config setup

# または環境変数で設定
export BACKLOG_SPACE_ID="your-space"
export BACKLOG_API_KEY="your-api-key"

# 設定確認
backlog config show

# 接続テスト
backlog config validate
```

#### スペース操作

```bash
# スペース情報を表示
backlog space info

# スペースユーザー一覧
backlog space users --limit 50

# 最近の更新を表示
backlog space activities
```

#### プロジェクト操作

```bash
# プロジェクト一覧
backlog project list

# プロジェクト詳細
backlog project info PROJECT-KEY

# プロジェクトメンバー
backlog project users PROJECT-KEY
```

#### 課題操作

```bash
# 課題一覧（フィルタリング）
backlog issue list --project PROJECT-KEY --status 1 2 3 --limit 20

# 課題の詳細表示
backlog issue show PROJ-123

# 課題のコメント一覧
backlog issue comments PROJ-123 --limit 10

# 課題数をカウント
backlog issue count --project PROJECT-KEY --status 1 2
```

## 📚 API リファレンス

### 対応 API エンドポイント

| 機能             | Python API            | CLI                   | 状態 |
| ---------------- | --------------------- | --------------------- | ---- |
| スペース情報     | `client.space.get()`  | `backlog space info`  | ✅   |
| ユーザー管理     | `client.users.list()` | `backlog space users` | ✅   |
| プロジェクト管理 | `client.projects.*`   | `backlog project *`   | ✅   |
| 課題管理         | `client.issues.*`     | `backlog issue *`     | ✅   |
| Wiki             | `client.wiki.*`       | -                     | ✅   |
| Git              | `client.git.*`        | -                     | ✅   |
| Webhook          | `client.webhook.*`    | -                     | ✅   |

### エラーハンドリング

```python
from backlog_sdk.exceptions import (
    BacklogAPIError,
    BacklogNotFoundError,
    BacklogPermissionError,
    BacklogRateLimitError
)

try:
    issue = client.issues.get("INVALID-KEY")
except BacklogNotFoundError:
    print("課題が見つかりません")
except BacklogPermissionError:
    print("アクセス権限がありません")
except BacklogRateLimitError:
    print("API呼び出し制限に達しました")
except BacklogAPIError as e:
    print(f"APIエラー: {e}")
```

## 🔧 開発

### 開発環境のセットアップ

```bash
# リポジトリをクローン
git clone https://github.com/yourusername/backlog-sdk.git
cd backlog-sdk

# 依存関係のインストール（uvを推奨）
uv sync

# 開発モードでインストール
uv pip install -e .
```

### テスト

```bash
# 全テストを実行
uv run python -m pytest

# カバレッジ付きで実行
uv run python -m pytest --cov=backlog_sdk

# 特定のテストのみ実行
uv run python -m pytest tests/test_client.py -v

# CLIテスト
uv run python -m pytest tests/test_cli.py -v
```

### コード品質チェック

```bash
# リントとフォーマット
uv run ruff check --fix
uv run ruff format

# 型チェック
uv run mypy src/backlog_sdk

# すべてのチェックを実行
uv run ruff check && uv run mypy src/backlog_sdk && uv run python -m pytest
```

### パッケージビルド

```bash
# ビルド
uv build

# 生成されたファイルを確認
ls dist/
```

## 🤝 貢献

バグ報告、機能要求、プルリクエストを歓迎します！

1. このリポジトリをフォーク
2. feature ブランチを作成 (`git checkout -b feature/amazing-feature`)
3. 変更をコミット (`git commit -m 'feat: Add some amazing feature'`)
4. ブランチにプッシュ (`git push origin feature/amazing-feature`)
5. プルリクエストを作成

### 開発ガイドライン

- コミットメッセージは日本語で記述
- 新機能には必ずテストを追加
- コードは`ruff`でフォーマット
- 型ヒントは必須
- docstring は日本語で記述

## 📄 ライセンス

MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照してください。

## 🙏 謝辞

- [Nulab](https://nulab.com/) - Backlog API の提供
- [Pydantic](https://docs.pydantic.dev/) - データバリデーション
- [httpx](https://www.python-httpx.org/) - HTTP クライアント
- [Click](https://click.palletsprojects.com/) - CLI フレームワーク

## 📊 プロジェクト統計

- **Python バージョン**: 3.12+
- **テストカバレッジ**: 95%+
- **対応 API**: 50+ エンドポイント
- **コード品質**: Ruff + mypy + pytest