polars-japanese: Polars 日本語拡張ライブラリ (Polars Japanese Extension Library)

Polars DataFrame/Expression API に、日本語処理や日本固有の操作に関連する機能を追加する拡張ライブラリです。

(This is an extension library that adds functionalities related to Japanese text processing and Japan-specific operations to the Polars DataFrame/Expression API.)

概要 (Overview)

polars-japanese は、データ分析ライブラリ Polars の強力な機能を活用しつつ、日本語特有のデータ処理（全角/半角変換、漢数字変換、和暦変換、祝日判定など）を容易に行えるように設計されています。 Polars の Expression API を拡張し、.ja アクセサを通じて直感的にこれらの機能を利用できます。

インストール (Installation)

pip install polars-japanese

使い方 (Usage)

polars-japanese をインポートすると、Polars の Expression API に .ja アクセサが追加されます。

import polars as pl
import polars_japanese
from datetime import date

df = pl.DataFrame({
    "kanji_num": ["千二百三十四", "五十六", None],
    "wareki_str": ["令和6年1月1日", "平成1年12月31日", "昭和45年12月04日"],
    "seireki_date": [date(2024, 4, 18), date(1989, 1, 8), date(1970, 10, 10)],
    "text_zen": ["Ｐｏｌａｒｓ", "データ", "１２３"],
})

df = df.select(
    # 漢数字変換
    pl.col("kanji_num").ja.to_number().alias("num_from_kanji"),
    # 和暦/西暦変換
    pl.col("wareki_str").ja.to_datetime().alias("seireki_from_wareki"),
    # 祝日判定
    pl.col("seireki_date").ja.is_holiday().alias("is_holiday"),
    # 全角/半角変換
    pl.col("text_zen").ja.to_half_width().alias("to_half"),
    pl.col("text_zen").ja.normalize().alias("normalized"),
)

print(df)

# ┌────────────────┬─────────────────────┬────────────┬─────────┬────────────┐
# │ num_from_kanji ┆ seireki_from_wareki ┆ is_holiday ┆ to_half ┆ normalized │
# │ ---            ┆ ---                 ┆ ---        ┆ ---     ┆ ---        │
# │ i64            ┆ date                ┆ bool       ┆ str     ┆ str        │
# ╞════════════════╪═════════════════════╪════════════╪═════════╪════════════╡
# │ 1234           ┆ 2024-01-01          ┆ false      ┆ Polars  ┆ Polars     │
# │ 56             ┆ 1989-12-31          ┆ false      ┆ ﾃﾞｰﾀ     ┆ データ     │
# │ null           ┆ 1970-12-04          ┆ true       ┆ 123     ┆ 123        │
# └────────────────┴─────────────────────┴────────────┴─────────┴────────────┘

df.ja.write_csv("output_sjis.csv", encoding="shift_jis")

主な機能 (Features)

全角/半角変換・正規化:
- ja.to_half_width(): 全角文字を半角文字に変換します (Rust Plugin)。
- ja.to_full_width(): 半角文字を全角文字に変換します (Rust Plugin)。
- ja.normalize(): Unicode正規化 (NFKC) を行い、さらに日本語テキストでよく問題になる記号やスペースを統一的に処理します（例: ハイフン類を半角 - に、チルダ類を全角 ～ に、スペースを半角スペースに統一）。
漢数字変換: 文字列中の漢数字をアラビア数字に変換します (Powered by kanjize)。
- ja.to_number(): 漢数字（例: "千二百三十四"）を整数（例: 1234）に変換します
- ja.to_kanji(): 数値を漢数字に変換します。config引数でKanjizeConfigurationを指定できます。
和暦/西暦変換: 和暦文字列と西暦日付/文字列を相互に変換します (Powered by japanera)。
- ja.to_wareki(): 西暦日付/文字列を和暦文字列（例: "令和6年10月10日"）に変換します。format引数で出力フォーマットを指定できます。raise_error引数でエラー発生時の挙動を制御できます。
- ja.to_datetime(): 和暦文字列を西暦日付に変換します。format引数で入力フォーマットを指定できます。raise_error引数でエラー発生時の挙動を制御できます。
祝日判定: 指定された日付が日本の祝日かどうかを判定します (Powered by jpholiday)。
- ja.is_holiday(): 日付が祝日であれば True を返します
- ja.is_business_day(): 日付が営業日であれば True を返します
日本語の曜日取得: Date型またはDatetime型の列から、日本語の曜日（"月曜日"、"火曜日"など）を取得できます。
- ja.to_weekday_name(format: str = "%A"): Date/Datetime を日本語の曜日に変換します。format引数で "%A" (フル形式、例: "月曜日") または "%a" (短縮形式、例: "月") を指定できます。
JST変換: Datetime型の列を日本標準時(JST)に変換します。
- ja.to_jst(): Datetime を JST に変換します。
都道府県関連処理: 都道府県名と都道府県コードの相互変換、および地方名への変換を行います。
- ja_pref.to_code(): 都道府県名（漢字、ひらがな、カタカナ、ローマ字、コード文字列）を都道府県コード（整数）に変換します。
- ja_pref.to_kanji(): 都道府県名またはコードを正式な漢字表記に変換します。
- ja_pref.to_hiragana(): 都道府県名またはコードを正式なひらがな表記に変換します。
- ja_pref.to_katakana(): 都道府県名またはコードを正式なカタカナ表記に変換します。
- ja_pref.to_romaji(): 都道府県名またはコードを一般的なローマ字表記（大文字）に変換します。
- ja_pref.to_region(): 都道府県名またはコードを地方名（例: 「関東」「近畿」）に変換します。
CSVエンコーディング指定出力: DataFrameを指定したエンコーディングでCSVファイルに出力します。
- DataFrame.ja.write_csv(path, encoding="shift_jis", **kwargs): DataFrameをCSVファイルに書き込みます。