ja-stopword-filter

分かち書き済みの日本語トークンから、ストップワードや指定した種類のトークンを除去する Python ライブラリです。実行時の外部依存はありません。Python 3.12 以上に対応しています。

English

このライブラリは分かち書きを行いません。 文全体を文字列で渡さず、文字列または Token のリストを渡してください。

インストールと最小例

pip install ja-stopword-filter

配布名は ja-stopword-filter、インポート名は ja_stopword_filter です。

from ja_stopword_filter import JaStopwordFilter

words = ["これ", "は", "東京", "。", "🤖"]
print(JaStopwordFilter().remove(words))  # Output: ['は', '東京', '。', '🤖']

デフォルトで有効なのは内蔵の語リストと、照合用の NFKC 正規化だけです。内蔵リストは 310 語で、は、が、です、ます などは含みません。必要な語や品詞を追加してください。

ルールを組み合わせる

from ja_stopword_filter import JaStopwordFilter

stopword_filter = JaStopwordFilter(
    use_date=True,
    use_numbers=True,
    use_symbols=True,
    use_spaces=True,
    use_emojis=True,
    custom_wordlist=["は"],
)
words = ["これ", "は", "東京", "。", "!!!", "🤖", "２０２４年１１月", "123", "", "2024年11月発売"]
print(stopword_filter.remove(words))  # Output: ['東京', '2024年11月発売']

挙動の境界

• NFKC は単なる全角→半角変換ではありません。ｶﾀｶﾅ → カタカナ、① → 1、㍑ → リットル も含みます。convert_to_halfwidth() で同じ変換を明示的に利用できます。
• remove() は新しいリストを返します。順序、重複、残した文字列の元の表記、Token のオブジェクト同一性を保ちます。入力リストや surface は変更しません。
• 日付は形式の照合だけです。2024年99月99日 も一致します。実在日付の検証や 2024-11-26 の解析は行いません。2024年11月発売 は日付ルールでは除去しません。
• 数字ルールは 123 や １２３ を除去しますが、-123、3.14、1,000、一 は残します。
• 記号ルールは 。、!!!、￥ を除去し、C++ や a-b は残します。一部の絵文字も S カテゴリなので、このルールと絵文字ルールは重複します。複合絵文字には use_emojis を使用してください。
• 絵文字は Unicode の fully-qualified / minimally-qualified / unqualified 表記を検出します。❤、国旗、肌色修飾、ZWJ、キーキャップを含みます。単独の 1、#、*、国旗の片側の地域指示文字は絵文字扱いしません。絵文字列の厳密な妥当性検証ではなく、含有判定です。
• 文字数は正規化後の Python 文字列の長さです。表示上の一文字とは限りません。空白は str.strip() に従い、ゼロ幅スペース U+200B は除去しません。
• どれか一つの有効なルールに一致すれば除去します。空文字列を自分で custom_wordlist に追加した場合、use_spaces=False でも除去されます。

品詞・独自属性によるフィルタ

Token(surface, pos) の pos は呼び出し側が与える文字列です。内蔵ルールは品詞を判定しません。コールバックは内蔵ルールより先に実行され、正規化前の文字列または元の Token を受け取ります。

from ja_stopword_filter import JaStopwordFilter, Token

class CountedToken(Token):
    def __init__(self, surface: str, pos: str, frequency: int) -> None:
        super().__init__(surface, pos)
        self.frequency = frequency

def exclude(token: CountedToken) -> bool:
    return token.pos == "助詞" or token.frequency < 2

words = [CountedToken("東京", "名詞", 5), CountedToken("は", "助詞", 8), CountedToken("例", "名詞", 1)]
filtered = JaStopwordFilter(custom_filter=exclude).remove(words)
print([token.surface for token in filtered])  # Output: ['東京']

コールバックは入力の型に合わせてください。文字列と Token を混在させる場合は isinstance で分岐します。混在入力の例 と、分かち書きから実行する Janome の例 を用意しています。Janome は例専用で、本ライブラリの依存には含めません。

型注釈と py.typed を同梱しています。JaStopwordFilter はコールバックの型を推論し、remove() は入力の要素型（Token のサブクラスを含む）を維持します。

公開 API

• JaStopwordFilter(...).remove(tokens)：分かち書き済みのリストやタプルをフィルタ。生の文字列・bytes や、str / Token 以外の要素には TypeError。
• Token(surface: str, pos: str)：拡張可能なトークン。残されたオブジェクトはコピーしません。
• get_stopwords() -> list[str]：空行を除いた内蔵語リストの新しいリストを返します。
• convert_to_halfwidth(text: str) -> str：Unicode NFKC を適用します。関数名は互換性のため維持しています。

License

Python の実装は Apache License 2.0、Unicode データから生成した絵文字パターンは Unicode License v3 に基づきます。