More than 1 year has passed since last update.

richなcatコマンドを作った話

Python

Posted at 2022-05-08

作ったもの

コマンドシンタックスハイライトをしてくれたり、Markdown や Jupyter Notebook をプレビューしてくれたりと、出力が"rich"な cat コマンド「richcat」を作りました。

pip を用いてインストールして使うことができます。

$ pip install richcat

richcat の主な機能は以下の通りです。

シンタックスハイライティング

プレビューのサポート

Markdown

CSV

Jupyter Notebook

※ Jupyter Notebook をプレビューするには、予め Jupyter がインストールされている必要があります
※ Jupyter がインストールされていない場合はJSONファイルとしてプレビューされます

なぜ作ったのか？

fzf のプレビューウィンドウに出すファイルプレビューをもっと良い感じにしたかったからです。具体的には…

↓これを

↓こうしたかった

良い感じのファイルプレビューですが、ファイル形式ごとに適したツールは既に存在しています。

Python や JavaScript といったソースコード等のファイル　→ bat
CSV ファイル　→ column コマンド
Jupyter Notebook ファイル　→ nbconvert 、 nbcat

etc...

しかし、コマンドライン上やシェルスクリプト内でファイル形式ごとにそれらのツールを使い分けるのは難しく、メンテナンス性も良くありませんでした。そこで、「一発でファイル形式ごとに最適なプレビューを提供してくれるコマンド」を作って実現しよう、ということになりました。

※ なぜ「fzf のプレビューウィンドウに出すファイルプレビューをもっと良い感じにしたい」と思ったのかですが、知人が開発しているFuzzy-Explorer-on-Terminal (fet)という fzf 製 CUI ファイルエクスプローラで使いたかったからです。

どうやって作ったのか？

使用技術

言語：Python
ライブラリ：rich

技術選定は、標準出力を色々カスタマイズできるライブラリを探していたところ「rich」が見つかり、「rich」が Python 製だったので言語も Python に――というような流れで進みました。

仕組み

rich の次の 3 つの機能をファイル形式ごとに使い分けることで実現しています。

rich の機能	どんな機能か	利用しているファイル形式
`Markdown`	Markdown ファイルをプレビューする機能	`.md`
`Table`	罫線等を用いてテーブルをきれいに表示する機能	`.csv`
`Syntax`	シンタックスハイライトを付ける機能	その他

ただし、 .ipynb ファイルだけ Jupyter がインストールされているかどうかで利用する機能を切り替えています。

インストールされていなかった場合：
- JSON ファイルとして扱う　 → 　Syntax を利用
インストールされていた場合：
- Jupyter の nbconvert 機能で Markdown ファイルへ変換　 → 　Markdown を利用

実行～標準出力までの大まかな流れは以下の通りです。

コマンド引数を受け取る
引数中のファイルパスをチェックし、この後の処理に通して良いか調べる。チェックが通らなかった場合は、その原因を例外として標準出力する
ファイル形式を判別する。判別後、形式ごとに標準出力するための処理を行う
- .ipynb 形式だった場合：
  - Jupyter の nbconvert 機能で Markdown ファイルへ変換する（以後、.md 形式だった場合の処理と同様）
- .md 形式だった場合：
  - rich で Markdown ビューを作成する
- .csv 形式だった場合：
  - rich で Table ビューを作成する
- その他の場合：
  - rich でシンタックスハイライトをつける
標準出力する

工夫した点

抽象クラスして同じ処理を共通化

前述のとおり、 richcat は rich の 3つの機能（ Syntax 、 Markdown 、 Table ）を利用してプレビューを行っています。どの機能を利用するかで処理内容は異なりますが、実装すべき処理（次の4つ）はいずれも同じです。

ファイル読み込み
ターミナル幅の取得
プレビューの作成
プレビューの標準出力

そこで、抽象クラスを用意し、処理内容が同じものは共通化、異なるものは抽象メソッドを用意して実装を強要するようにしました。実際の実装のクラス図を次に示します。

これにより、各々実装したい部分のコードだけ書けば良いので実装負担が軽くなった他、メンテナンスもしやすくなりました。

エラーハンドリング

No such file of directory や Is a directory といった、エラー内容を標準出力する仕組みを richcat でも作りました。実装は、richcat のプログラム全体を try-except で囲い、エラーが発生したら対応する例外クラスを raise させる方法を採りました。イメージとして、以下にその実装コードの抜粋を示します。

def check_input_error(args):
    # Is exists
    if args.filepath is None:
        return
    if not os.path.exists(args.filepath):
        raise RichcatFileNotFoundError(args.filepath)
    # Is directory
    if os.path.isdir(args.filepath):
        raise RichcatIsDirectoryError(args.filepath)
    # Is able to access
    if not os.access(args.filepath, os.R_OK):
        raise RichcatPermissionError(args.filepath)

def richcat(args):
    try:
        # help
        if args.help:
            args.file_contents, args.filetype, args.filepath = print_help()
        # Checking input error
        check_input_error(args)
        # Infering FileType
        filepath, filetype = infer_filetype(args.filepath, args.filetype)
        # Print Rich
        try:
            print_rich(filetype, float(args.width), args.color_system, args.style, filepath=filepath, file_contents=args.file_contents)
        except BrokenPipeError:
            raise RichcatBrokenPipeError()
    except Exception as e:
        if 'print_error' in dir(e):
            e.print_error()
        else:
            raise e

これによりエラー後の処理を1か所にまとめることができ、似たようなエラー後処理があちこちに散らばるのを防ぐことができました。

シンタックスハイライトの自動決定処理の高速化

Syntax には .from_path() という、ファイルパスを与えればシンタックスハイライトを自動決定してくれるメソッドが用意されています。しかし、このメソッドを用いて実装したところ処理時間が
長かった（3行のファイルでもコマンド実行→標準出力まで一瞬ラグが出たくらい）ので、独自にシンタックスハイライト決定処理を作りました。

処理内容はざっくり以下の通りです。

予め「拡張子→シンタックスハイライト」の対応辞書を用意しておく
入力されたファイルパスから拡張子を識別し、用意した辞書を引いてシンタックスハイライトを決定する

拡張子とシンタックスハイライトの対応関係は、 pygments の LEXERS 変数の値を使いました（ pygments は rich がシンタックスハイライトをつけるために利用しているライブラリです）。また、辞書の更新方法も LEXERS 変数が定義されている _mapping.py の実装を参考にしました。

実際にシンタックスハイライトの決定処理がどの程度速くなったかを簡単に実験してみました。実験は、 .from_path() を利用する方法と予め辞書を用意する方法に対し、様々な形式のファイルをそれぞれ1000回ずつ読み込ませることで行いました。

以下に、各ファイル形式で処理にかかった時間の基本統計量を可視化したものを示します。

.from_path() を利用する方法：

予め辞書を利用する方法：

結果を見ると、予め辞書を用意したほうが10倍ほど速くなっていることが分かります。

実験コード：

`.ipynb` ファイルのプレビュー

.ipynb ファイルのプレビューは richcat 開発当初から実装したかった機能でした。実装方法としては、既存ツール（ Jupyter の nbconvert ）を利用する方法と独自に ipynb ファイルの parser を作る方法の2つを考えました。しかし、それぞれ次の問題を抱えていました。

既存ツールを利用する　→　依存が増えてしまう（目的：richcat 1つで様々なファイルをプレビューできるようにしたい）
独自に parser を作る　→「車輪の再開発」、作れたとしても既存プログラムの大規模改修必至

そこで、既に Jupyter がインストールされている場合はそれを利用し、そうでない場合はシンタックスハイライトをつけるよう、処理を分岐させることにしました。これにより、 richcat を使うための依存を増やさずに既存ツールを利用できるようになりました。

今後やりたいこと

Mac対応
richcat できるファイル形式を増やす
- ディレクトリも richcat できるようにする（rich の Tree 機能を使うと良さそう）
- ターミナル上で画像も richcat できるようにする（libsixel というライブラリを利用してうまくやれないか検討中）
- TensorBoard のログファイルを richcat できるようにする
- Excel 、 ZIP 、etc...

ターミナル上で中身を確認しづらいファイル形式に焦点を当て、そのようなファイル形式でも確認しやすくしていきたい思っています。最終目標としては、「 richcat さえあればどんなファイル形式でもターミナル上で rich に cat できる」ところを目指しています。

まとめ

この記事では、出力が"rich"な cat コマンド「richcat」について、その開発経緯や仕組みについて紹介しました。ぜひインストールして使ってみてください！なお、バグがあったり謎の実装をしていたりする個所があったりするかと思いますので、その場合はコメントやIssue等をいただけると助かります

ここまでお読みいただきありがとうございました！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up