Skip to content

Command Line Options JP

Jump to bottom
Hiromichi Yokoyama edited this page Aug 7, 2026 · 2 revisions

コマンドラインオプション

MoleditPy の CLI は main.py 内で argparse（prog="moleditpy"）により定義されています。このページでは、すべてのフラグ、位置引数、そして実行時の挙動を変える環境変数を解説します。

usage: moleditpy [-h] [--version] [--safe] [--install-plugin PATH] [file]

位置引数

file（省略可）

nargs="?", default=None — 「起動時に開くファイル」

指定すると、MoleditPy はこのファイルを起動直後に開きます。File ▸ Open／Import の該当アクションを使ったのとまったく同じ扱いです。パーサ自体には拡張子の制限はありません — 実際に何が起きるかはファイルの中身次第で、対応していない/壊れたファイルは GUI の「開く」ダイアログから開いた場合とまったく同じ失敗の仕方をします。

moleditpy molecule.mol
moleditpy project.pmeprj

フラグ

-h, --help

標準の argparse ヘルプテキストです。使用方法を表示して終了します。

--version

action="version" — MoleditPy {VERSION}（moleditpy-linux ディストリビューションから実行している場合は MoleditPy (Linux) {VERSION} — __file__ に "moleditpy_linux" が含まれるかで判定）を表示して即座に終了します。Qt をインポートするより前に 実行されます。VERSION は moleditpy/src/moleditpy/utils/constants.py から取得されます。

moleditpy --version
# MoleditPy <version>

--safe

action="store_true", default=False — 「セーフモードで起動：すべてのプラグインの読み込みをスキップ」

MainWindow(initial_file=..., safe_mode=True) にそのまま渡されます。ui/main_window_init.py では、セーフモード時は self.host.plugin_manager = None として PluginManager 自体をまったく構築せず、"Safe mode: plugins disabled." とログに記録します。結果として：

  • ~/.moleditpy/plugins/ 以下のプラグイン .py ファイルは一切検出・読み込み・initialize() されません — ファイルオープナーや 3D スタイル、メニューアクションを提供するプラグインも含みます。
  • Plugin ▸ Plugin Manager... を開くと、プラグイン一覧の代わりに「Plugins are disabled (safe mode).」という情報ダイアログが表示されます（PluginManager インスタンスが存在せず一覧できないため）。
  • 壊れた/非互換なプラグインが原因のクラッシュから復旧したい場合や、問題の切り分けでプラグインの有無を確認したい場合に使用します。
moleditpy --safe

--install-plugin PATH

metavar="PATH" — 「.py ファイル、.zip、またはフォルダからプラグインをインストール（ヘッドレス）」

GUI を まったく起動せずに プラグインをインストールします — QApplication が作られる前に実行・終了する独立したコードパスです。

  1. PATH を絶対パスに解決します。存在しない場合は Error: Plugin path not found: {path} を表示して終了コード 1 で終了します。
  2. プラグインの SHA-256 を計算します（PluginManager.compute_sha256）— .py ファイルや .zip の場合はファイル自体のハッシュ、フォルダの場合は内容から導出されたハッシュです。
  3. パスが __init__.py を含むフォルダの場合、その __init__.py からメタデータ（PLUGIN_NAME、PLUGIN_AUTHOR、PLUGIN_VERSION、PLUGIN_DESCRIPTION の各定数、get_plugin_info_safe 参照）を読み取ります。単体の .py ファイルも同様です。.zip の場合はインストール前のメタデータプレビューはありません。
  4. 確認用のサマリー（名前・作者・バージョン・説明・パス・SHA-256）を表示し、対話的に確認を求めます： 
    Do you want to proceed with installation? (y/N):
    y の入力のみが処理を続行させます。それ以外（Enter のみを含む）は Installation aborted. と表示して終了コード 0 で終了します。
  5. y の場合、PluginManager.install_plugin(path) を呼び出し、そのファイル/zip/フォルダを ~/.moleditpy/plugins/ にコピーします（「インストール」の詳細は Using Plugins を参照）。成功時は Success: {msg} を表示して終了コード 0、失敗時は Error: {msg} を表示して終了コード 1 です。

このパスは input() を呼び出すため、対話的なターミナル利用を想定しています（初回セットアップのスクリプト化など）— 完全に無人実行するための --yes/--force のようなフラグで確認をスキップする手段はありません。

moleditpy --install-plugin ~/Downloads/my_plugin.py
moleditpy --install-plugin ~/Downloads/some_plugin.zip
moleditpy --install-plugin ~/Downloads/some_plugin_folder/

未知の引数（Qt へのパススルー）

パーサは parse_args() ではなく parser.parse_known_args() を呼び出しています。これは Qt 自身のコマンドライン引数（例：-platform offscreen、-style、-geometry）をそのまま QApplication に渡すためです — argparse が認識しない引数はすべて remaining として転送され、QApplication 生成時に QApplication([sys.argv[0]] + remaining) として追加されます。つまり MoleditPy 独自のフラグと Qt のフラグを組み合わせて使えます：

moleditpy --safe -platform offscreen

環境変数

これらは argparse ではなく os.environ から直接読み取られます — 起動前にシェルで設定してください。

MOLEDITPY_HEADLESS

2箇所でチェックされています：

  • main.py: setup_logging() — 設定されている場合（真とみなされる文字列であれば何でも）、GUI のエラーダイアログハンドラ（_ErrorDialogHandler。ERROR/CRITICAL のログレコードごとに QMessageBox をポップアップします）はインストールされません。自動化/ヘッドレス実行がクリックされることのないモーダルダイアログで止まってしまうのを防ぐためです。
  • ui/io_logic.py: _report_load_error() — 設定されている場合、読み込みエラーダイアログ（QMessageBox.warning）は表示されず、ステータスバーへのメッセージのみになります。設定しないと、ヘッドレス環境でファイル読み込みに失敗した際にモーダルの警告ボックスが表示されてしまいます。

これはメイン app の CLAUDE.md にある通り、MoleditPy 自体のテストスイートの実行方法でもあります：MOLEDITPY_HEADLESS=1 QT_QPA_PLATFORM=offscreen python tests/run_all_tests.py ...。main.py の CLI パースでは一切読み取られません — 起動フラグではなく、起動後の挙動 を変えるものです。

QT_QPA_PLATFORM

MoleditPy 自身のコードでは読み取られていません — これは Qt/PyQt6 の環境変数 であり、moleditpy の Python コードが動く前に Qt のプラットフォーム抽象化レイヤー自体が読み取ります。offscreen に設定すると、実際のディスプレイ/X サーバ/コンポジタなしで Qt を描画できるようになります。これにより、ヘッドレスな CI ランナーや DISPLAY のない SSH セッションでも MoleditPy を起動できます。実ディスプレイもこの変数もない状態では、Qt はプラットフォームプラグインエラーで初期化に失敗します（Troubleshooting Common Issues 参照）。

MOLEDITPY_HEADLESS=1 QT_QPA_PLATFORM=offscreen moleditpy --safe

「次回」起動に影響する設定（CLI フラグではないが、起動時に読み取られるもの）

main.py は Qt/ロギングの構成前に ~/.moleditpy/settings.json を読み取ります（_read_startup_log_settings()）。具体的には、通常は Settings ▸ Settings... ▸ Other から設定する 2 つのキーです：

キー 起動時の効果
log_to_file（bool、既定 False） true の場合、RotatingFileHandler が接続され ~/.moleditpy/moleditpy.log に書き込まれます（1 ファイルあたり 1 MiB、バックアップ 3 世代）。
log_level_debug（bool、既定 False） true の場合、ルートロガーのレベルが INFO ではなく DEBUG になります。

これらは CLI フラグではありません — --log-to-file のようには設定できません — が、ウィンドウが開く前にディスクから読み取られるという点で起動時設定のように振る舞います。解析に失敗した場合（ファイルなし、JSON 不正など）は静かに (False, False) にフォールバックします。

関連ページ

  • Troubleshooting Common Issues — QT_QPA_PLATFORM/OpenGL/プラグイン読み込みの問題への対処
  • Using Plugins — --install-plugin を超えたインストール/アンインストール/セーフモードの全体像

Clone this wiki locally