Pythonのdocstringの基本的な書き方とコード例10選

def calculate_area(length: float, width: float) -> float:
    """
    長方形の面積を計算します。

    Args:
        length (float): 長方形の長さ
        width (float): 長方形の幅

    Returns:
        float: 計算された面積

    Raises:
        ValueError: 長さまたは幅が負の値の場合

    Example:
        >>> calculate_area(5, 3)
        15.0
    """
    if length < 0 or width < 0:
        raise ValueError("長さと幅は正の値でなければなりません")
    return length * width

# 関数の使用例
result = calculate_area(5, 3)
print(f"面積: {result}")

class BankAccount:
    """
    銀行口座を表すクラス。

    口座の残高管理、入金、出金操作を行います。

    Attributes:
        account_number (str): 口座番号
        balance (float): 現在の残高

    Methods:
        deposit(amount): 指定額を入金します
        withdraw(amount): 指定額を出金します
        get_balance(): 現在の残高を返します
    """

    def __init__(self, account_number: str, initial_balance: float = 0):
        """
        BankAccountクラスのコンストラクタ。

        Args:
            account_number (str): 口座番号
            initial_balance (float, optional): 初期残高。デフォルトは0。
        """
        self.account_number = account_number
        self.balance = initial_balance

    def deposit(self, amount: float) -> None:
        """
        指定額を口座に入金します。

        Args:
            amount (float): 入金額

        Raises:
            ValueError: 入金額が0以下の場合
        """
        if amount <= 0:
            raise ValueError("入金額は正の値でなければなりません")
        self.balance += amount

    def withdraw(self, amount: float) -> None:
        """
        指定額を口座から出金します。

        Args:
            amount (float): 出金額

        Raises:
            ValueError: 出金額が0以下の場合、または残高不足の場合
        """
        if amount <= 0:
            raise ValueError("出金額は正の値でなければなりません")
        if amount > self.balance:
            raise ValueError("残高不足です")
        self.balance -= amount

    def get_balance(self) -> float:
        """
        現在の口座残高を返します。

        Returns:
            float: 現在の残高
        """
        return self.balance

# クラスの使用例
account = BankAccount("1234567890", 1000)
account.deposit(500)
account.withdraw(200)
print(f"残高: {account.get_balance()}円")

"""
数学的操作を行うユーティリティモジュール。

基本的な算術演算や幾何学的計算を提供します。

Functions:
    add(a, b): 2つの数値を加算します
    subtract(a, b): 2つの数値を減算します
    multiply(a, b): 2つの数値を乗算します
    divide(a, b): 2つの数値を除算します
    calculate_circle_area(radius): 円の面積を計算します

Constants:
    PI: 円周率の近似値
"""

import math

PI = 3.14159

def add(a: float, b: float) -> float:
    """2つの数値を加算します。"""
    return a + b

def subtract(a: float, b: float) -> float:
    """2つの数値を減算します。"""
    return a - b

def multiply(a: float, b: float) -> float:
    """2つの数値を乗算します。"""
    return a * b

def divide(a: float, b: float) -> float:
    """
    2つの数値を除算します。

    Args:
        a (float): 被除数
        b (float): 除数

    Returns:
        float: 商

    Raises:
        ZeroDivisionError: 除数が0の場合
    """
    if b == 0:
        raise ZeroDivisionError("0での除算はできません")
    return a / b

def calculate_circle_area(radius: float) -> float:
    """
    円の面積を計算します。

    Args:
        radius (float): 円の半径

    Returns:
        float: 円の面積
    """
    return PI * radius ** 2

# モジュールの使用例
result = add(5, 3)
print(f"5 + 3 = {result}")

area = calculate_circle_area(2)
print(f"半径2の円の面積: {area}")

"""
ファイル操作ユーティリティパッケージ

様々なファイル形式の読み書き、操作を行うための機能を提供します。

Modules:
    text_file: テキストファイルの読み書き操作
    csv_file: CSVファイルの読み書き操作
    json_file: JSONファイルの読み書き操作
    xml_file: XMLファイルの読み書き操作

Usage:
    from file_utils import text_file
    content = text_file.read('example.txt')
"""

# 各モジュールのインポート
from . import text_file
from . import csv_file
from . import json_file
from . import xml_file

# バージョン情報
__version__ = "1.0.0"

# 必要に応じて、パッケージレベルで使用する関数や変数をここで定義
def get_package_info():
    """パッケージの情報を返します。"""
    return f"File Utils Package version {__version__}"

#!/usr/bin/env python3
"""
簡単なコマンドライン計算機

このスクリプトは、コマンドライン引数として与えられた2つの数値と演算子を使用して
基本的な算術演算を行います。

使用方法:
    python calculator.py <数値1> <演算子> <数値2>

演算子:
    + : 加算
    - : 減算
    * : 乗算
    / : 除算

例:
    python calculator.py 5 + 3
    python calculator.py 10 * 2
    python calculator.py 15 / 3

注意:
    - 除算の場合、0での除算はエラーになります。
    - 不正な演算子や引数の数が間違っている場合はエラーメッセージが表示されます。
"""

import sys

def calculate(a: float, operator: str, b: float) -> float:
    """
    2つの数値に対して指定された演算を行います。

    Args:
        a (float): 1つ目の数値
        operator (str): 演算子 (+, -, *, /)
        b (float): 2つ目の数値

    Returns:
        float: 計算結果

    Raises:
        ValueError: 不正な演算子が指定された場合
        ZeroDivisionError: 0で除算しようとした場合
    """
    if operator == '+':
        return a + b
    elif operator == '-':
        return a - b
    elif operator == '*':
        return a * b
    elif operator == '/':
        if b == 0:
            raise ZeroDivisionError("0で除算することはできません")
        return a / b
    else:
        raise ValueError(f"不正な演算子です: {operator}")

def main():
    """
    メイン関数。コマンドライン引数を解析し、計算を実行します。
    """
    if len(sys.argv) != 4:
        print("使用方法: python calculator.py <数値1> <演算子> <数値2>")
        sys.exit(1)

    try:
        a = float(sys.argv[1])
        operator = sys.argv[2]
        b = float(sys.argv[3])

        result = calculate(a, operator, b)
        print(f"結果: {result}")
    except ValueError as e:
        print(f"エラー: {e}")
    except ZeroDivisionError as e:
        print(f"エラー: {e}")

if __name__ == "__main__":
    main()

def calculate_area(length: float, width: float) -> float:
    """長方形の面積を計算します。

    Args:
        length: 長方形の長さ
        width: 長方形の幅

    Returns:
        計算された面積

    Raises:
        ValueError: 長さまたは幅が負の値の場合
    """
    if length < 0 or width < 0:
        raise ValueError("長さと幅は正の値でなければなりません")
    return length * width

def calculate_area(length: float, width: float) -> float:
    """
    長方形の面積を計算します。

    :param length: 長方形の長さ
    :type length: float
    :param width: 長方形の幅
    :type width: float
    :return: 計算された面積
    :rtype: float
    :raises ValueError: 長さまたは幅が負の値の場合

    >>> calculate_area(5, 3)
    15.0
    """
    if length < 0 or width < 0:
        raise ValueError("長さと幅は正の値でなければなりません")
    return length * width

def calculate_area(length: float, width: float) -> float:
    """
    長方形の面積を計算します。

    Parameters
    ----------
    length : float
        長方形の長さ
    width : float
        長方形の幅

    Returns
    -------
    float
        計算された面積

    Raises
    ------
    ValueError
        長さまたは幅が負の値の場合

    Examples
    --------
    >>> calculate_area(5, 3)
    15.0
    """
    if length < 0 or width < 0:
        raise ValueError("長さと幅は正の値でなければなりません")
    return length * width

from typing import List, Dict, Union

def process_data(data: List[Dict[str, Union[int, str]]]) -> Dict[str, int]:
    """
    リスト内の辞書データを処理し、結果を新しい辞書で返します。

    Args:
        data (List[Dict[str, Union[int, str]]]): 処理するデータのリスト
            各辞書は 'id' (int) と 'name' (str) キーを持つ

    Returns:
        Dict[str, int]: 処理結果を格納した辞書
            キーは 'name'、値は 'id' の2倍

    Raises:
        ValueError: データが空の場合、または必要なキーが存在しない場合

    Example:
        >>> data = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
        >>> process_data(data)
        {'Alice': 2, 'Bob': 4}
    """
    if not data:
        raise ValueError("データが空です")

    result = {}
    for item in data:
        if 'id' not in item or 'name' not in item:
            raise ValueError("データに必要なキーが存在しません")
        result[item['name']] = item['id'] * 2

    return result

# 関数の使用例
sample_data = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
processed_data = process_data(sample_data)
print(processed_data)

import os

def read_config_file(file_path: str) -> dict:
    """
    指定されたパスから設定ファイルを読み込み、辞書形式で返します。

    Args:
        file_path (str): 設定ファイルのパス

    Returns:
        dict: 設定ファイルの内容を表す辞書

    Raises:
        FileNotFoundError: 指定されたファイルが存在しない場合
        PermissionError: ファイルを読み取る権限がない場合
        JSONDecodeError: ファイルの内容が有効なJSONでない場合

    Example:
        >>> config = read_config_file('config.json')
        >>> print(config['database']['host'])
        localhost
    """
    import json  # 関数内でインポートすることで、必要な時のみ読み込まれます

    try:
        with open(file_path, 'r') as file:
            config = json.load(file)
    except FileNotFoundError:
        raise FileNotFoundError(f"設定ファイル '{file_path}' が見つかりません")
    except PermissionError:
        raise PermissionError(f"設定ファイル '{file_path}' を読み取る権限がありません")
    except json.JSONDecodeError:
        raise json.JSONDecodeError(f"設定ファイル '{file_path}' の内容が有効なJSONではありません")

    return config

# 関数の使用例
try:
    config = read_config_file('config.json')
    print("データベースホスト:", config['database']['host'])
except (FileNotFoundError, PermissionError, json.JSONDecodeError) as e:
    print(f"エラーが発生しました: {e}")

from typing import Dict, List, Any

def analyze_text(text: str) -> Dict[str, Any]:
    """
    テキストを分析し、様々な統計情報を返します。

    Args:
        text (str): 分析対象のテキスト

    Returns:
        Dict[str, Any]: 以下のキーを含む辞書
            - word_count (int): 単語数
            - char_count (int): 文字数（空白を含む）
            - sentence_count (int): 文の数
            - average_word_length (float): 平均単語長
            - most_common_words (List[Tuple[str, int]]): 
                最も頻出する単語とその出現回数（上位5つ）

    Raises:
        ValueError: 空のテキストが渡された場合

    Example:
        >>> text = "This is a sample text. It has some words and sentences."
        >>> result = analyze_text(text)
        >>> print(result['word_count'])
        10
        >>> print(result['most_common_words'][0])
        ('is', 2)
    """
    if not text:
        raise ValueError("空のテキストは分析できません")

    words = text.split()
    sentences = text.split('.')

    word_count = len(words)
    char_count = len(text)
    sentence_count = len([s for s in sentences if s.strip()])
    average_word_length = sum(len(word) for word in words) / word_count

    word_freq = {}
    for word in words:
        word = word.lower()
        word_freq[word] = word_freq.get(word, 0) + 1
    most_common_words = sorted(word_freq.items(), key=lambda x: x[1], reverse=True)[:5]

    return {
        'word_count': word_count,
        'char_count': char_count,
        'sentence_count': sentence_count,
        'average_word_length': average_word_length,
        'most_common_words': most_common_words
    }

# 関数の使用例
sample_text = "This is a sample text. It has some words and sentences. This text is used for analysis."
analysis_result = analyze_text(sample_text)

print("単語数:", analysis_result['word_count'])
print("文字数:", analysis_result['char_count'])
print("文の数:", analysis_result['sentence_count'])
print("平均単語長:", round(analysis_result['average_word_length'], 2))
print("最も頻出する単語:")
for word, count in analysis_result['most_common_words']:
    print(f"  {word}: {count}回")

単語数: 15
文字数: 88
文の数: 3
平均単語長: 3.87
最も頻出する単語:
  is: 2回
  this: 2回
  a: 1回
  sample: 1回
  text: 1回

import time
from functools import wraps
from typing import Callable, Any

def timing_decorator(func: Callable[..., Any]) -> Callable[..., Any]:
    """
    関数の実行時間を計測し、結果をログに出力するデコレータ。

    このデコレータは、任意の関数に適用でき、その関数の実行にかかった時間を
    ミリ秒単位で計測します。計測結果は標準出力に表示されます。

    Args:
        func (Callable[..., Any]): 計測対象の関数

    Returns:
        Callable[..., Any]: 計測機能が追加された関数

    Example:
        @timing_decorator
        def slow_function():
            time.sleep(2)
            return "処理完了"

        result = slow_function()
        # 出力: 関数 'slow_function' の実行時間: 2000.12 ms
    """
    @wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        start_time = time.perf_counter()
        result = func(*args, **kwargs)
        end_time = time.perf_counter()
        execution_time = (end_time - start_time) * 1000  # ミリ秒に変換
        print(f"関数 '{func.__name__}' の実行時間: {execution_time:.2f} ms")
        return result
    return wrapper

# デコレータの使用例
@timing_decorator
def fibonacci(n: int) -> int:
    """
    フィボナッチ数列のn番目の値を計算します。

    Args:
        n (int): 計算したいフィボナッチ数列の項数

    Returns:
        int: n番目のフィボナッチ数

    Raises:
        ValueError: nが負の値の場合
    """
    if n < 0:
        raise ValueError("nは0以上の整数である必要があります")
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# 関数の実行
result = fibonacci(30)
print(f"fibonacci(30) の結果: {result}")

関数 'fibonacci' の実行時間: 308.45 ms
fibonacci(30) の結果: 832040

class DataProcessor:
    """
    データ処理を行うクラス。

    このクラスは、与えられたデータに対して様々な処理を適用します。
    公開メソッドを通じてデータを処理し、結果を取得できます。

    Attributes:
        data (list): 処理対象のデータリスト
    """

    def __init__(self, data: list):
        """
        DataProcessorクラスのコンストラクタ。

        Args:
            data (list): 処理対象の初期データ
        """
        self.data = data

    def process_data(self) -> list:
        """
        データに一連の処理を適用し、結果を返します。

        Returns:
            list: 処理済みのデータリスト
        """
        cleaned_data = self._clean_data()
        normalized_data = self._normalize_data(cleaned_data)
        return self._transform_data(normalized_data)

    def _clean_data(self) -> list:
        """
        データのクリーニングを行います。

        空の要素や無効な値を除去します。

        Returns:
            list: クリーニング済みのデータリスト

        Note:
            このメソッドは内部使用を想定しています。
        """
        return [item for item in self.data if item and isinstance(item, (int, float))]

    def _normalize_data(self, data: list) -> list:
        """
        データの正規化を行います。

        全ての値を0-1の範囲に収めます。

        Args:
            data (list): 正規化対象のデータリスト

        Returns:
            list: 正規化されたデータリスト

        Note:
            このメソッドは内部使用を想定しています。
        """
        if not data:
            return []
        min_val, max_val = min(data), max(data)
        return [(x - min_val) / (max_val - min_val) for x in data]

    def _transform_data(self, data: list) -> list:
        """
        データの変換処理を行います。

        各要素を2乗します。

        Args:
            data (list): 変換対象のデータリスト

        Returns:
            list: 変換されたデータリスト

        Note:
            このメソッドは内部使用を想定しています。
        """
        return [x ** 2 for x in data]

# クラスの使用例
raw_data = [1, 2, None, 4, 'invalid', 5, 6]
processor = DataProcessor(raw_data)
processed_data = processor.process_data()
print("処理結果:", processed_data)

.. automodule:: mymodule
   :members:
   :undoc-members:
   :show-inheritance:

def greet(name):
    """
    挨拶を返す関数。
        Args:
            name (str): 挨拶する相手の名前
        Returns:
            str: 挨拶文
    """
    return f"こんにちは、{name}さん！"

def greet(name):
    """
    挨拶を返す関数。

    Args:
        name (str): 挨拶する相手の名前
    Returns:
        str: 挨拶文
    """
    return f"こんにちは、{name}さん！"

def calculate_area(radius):
    """円の面積を計算する関数。

    Args:
        radius (float): 円の半径
    Returns:
        float: 円の面積

    return 3.14 * radius ** 2

def calculate_area(radius):
    """円の面積を計算する関数。

    Args:
        radius (float): 円の半径
    Returns:
        float: 円の面積
    """
    return 3.14 * radius ** 2

def add_numbers(a, b):
    return a + b

def add_numbers(a, b):
    """
    2つの数値を加算する関数。

    Args:
        a (int): 1つ目の数値
        b (int): 2つ目の数値

    Returns:
        int: aとbの和
    """
    return a + b

"""
プロジェクトXのdocstringスタイルガイド

1. フォーマット: Google Style
2. 基本構造:
   """
   関数の簡潔な説明。

   詳細な説明（複数行可）。

   Args:
       引数名 (型): 説明

   Returns:
       型: 説明

   Raises:
       例外名: 発生条件

   Example:
       使用例（可能な限り記載）
   """

3. 特記事項:
   - 全ての公開関数・メソッドにdocstringを付ける
   - 引数と戻り値の型は必ず記載する
   - 例外は発生し得る全てのものを記載する
   - 可能な限り使用例を含める
"""

def example_function(arg1: int, arg2: str) -> bool:
    """整数と文字列を受け取り、条件を満たすかどうかを返す。

    arg1が10より大きく、arg2の長さが5文字以上の場合にTrueを返す。
    それ以外の場合はFalseを返す。

    Args:
        arg1 (int): 比較する整数値
        arg2 (str): 長さを確認する文字列

    Returns:
        bool: 条件を満たす場合はTrue、そうでない場合はFalse

    Raises:
        TypeError: arg1が整数でない、またはarg2が文字列でない場合

    Example:
        >>> example_function(15, "hello")
        True
        >>> example_function(5, "hi")
        False
    """
    if not isinstance(arg1, int) or not isinstance(arg2, str):
        raise TypeError("引数の型が正しくありません")
    return arg1 > 10 and len(arg2) >= 5

def calculate_discount(price: float, discount_rate: float) -> float:
    """割引価格を計算する。

    Args:
        price: 元の価格
        discount_rate: 割引率（0から1の間）

    Returns:
        割引後の価格
    """
    return price * (1 - discount_rate)

.. automodule:: mymodule
   :members:
   :undoc-members:
   :show-inheritance: