Pyqtcli documentation (PyQt/PySide CLI Integration)

Документация на русском

PyQtCLI is a Python package that simplifies integrating command-line argument parsing into Qt-based GUI applications (PySide/PyQt). It allows you to easily combine the standard argparse module with the ability to display help messages in a graphical window (QMessageBox).

Features

• Backend Flexibility: Automatically detects the available Qt binding (PySide6, PyQt6, PyQt5, PySide2).
• Graphical Help: The GUIHelpParser class overrides the help output (-h, --help), displaying it not only in the console but also in a pop-up QMessageBox window.
• Convenient Mixin: The CLIMixin class provides all the methods of argparse.ArgumentParser (add_argument, parse_args, etc.) for easy addition to your classes.
• Ready-to-Use Integration: The QCLIApplication class is a ready-to-use subclass of QApplication with the CLIMixin functionality already built-in.
• Type Hints: Includes .pyi files for better autocompletion and type checking support in modern IDEs.

Installation

You can install the package directly from the repository or from PyPI after publication (replace with the actual command):

# From repository
pip install git+https://github.com/MagIlyasDOMA/pyqtcli.git

# Or after publication (example)
pip install pyqtcli

The package does not automatically install a specific Qt library. You need to install one of the supported bindings yourself:

# For example, for PySide6
pip install pyqtcli[pyside6]

# Or for PyQt5
pip install pyqtcli[pyqt5]

Usage

Quick Start with QCLIApplication

The easiest way to create an application with command-line argument support is to use the ready-made QCLIApplication class.

import sys
from pyqtcli import QCLIApplication
from PySide6.QtWidgets import QMainWindow, QLabel # Example for PySide6

# Create an application instance, passing the command-line arguments
# All additional parameters (prog, description, etc.) are passed to the parser.
app = QCLIApplication(
    sys.argv,
    description="My Super Application",
    epilog="Example of using QCLIApplication"
)

# Add your own arguments, just like in standard argparse
app.add_argument("-f", "--file", help="Path to the file to open")
app.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")

# Parse the arguments. Help (-h) will automatically be displayed in a graphical window.
args = app.parse_args()

# --- Standard Qt application code follows ---
window = QMainWindow()
if args.file:
    window.setCentralWidget(QLabel(f"Opened file: {args.file}"))
else:
    window.setCentralWidget(QLabel("Hello, world!"))
window.show()

sys.exit(app.exec())

Using CLIMixin in Your Own QApplication Class

If you need more control or want to add parsing functionality to your own application class, use CLIMixin.

import sys
from PySide6.QtWidgets import QApplication, QMainWindow, QLabel
from pyqtcli import CLIMixin

class MyApp(QApplication, CLIMixin):
    def __init__(self, argv):
        # First, initialize the mixin with parser parameters
        CLIMixin.__init__(self, description="My Custom Application")
        # Then initialize QApplication
        QApplication.__init__(self, argv)

        # Add your own arguments
        self.add_argument("--debug", action="store_true", help="Enable debug mode")

        # Parse the arguments
        self.args = self.parse_args()

        if self.args.debug:
            print("Debug mode enabled")

# Run the application
if __name__ == "__main__":
    app = MyApp(sys.argv)

    window = QMainWindow()
    window.setCentralWidget(QLabel("Application Window"))
    window.show()

    sys.exit(app.exec())

Using GUIHelpParser Directly

You can use the graphical parser directly, for example, to create a standalone tool.

import sys
from PySide6.QtWidgets import QApplication
from pyqtcli.argparser import GUIHelpParser

# Create the parser
app = QApplication(sys.argv)
parser = GUIHelpParser(prog="tool.py", description="Tool with GUI help")
parser.add_argument("-o", "--output", help="File to save the result")

# When parse_args() is called, help will be shown in a window
# if the -h or --help arguments are passed.
# Otherwise, parsing proceeds as usual.
args = parser.parse_args()
print(args)

Package Structure

• __init__.py: The main module, exporting the QCLIApplication, CLIMixin, and GUIHelpParser classes.
• _widgets.py: An internal module for automatically selecting and importing the required Qt binding.
• argparser.py: Contains the GUIHelpParser (parser with graphical help) and CLIMixin (mixin for adding a parser to any class) classes.

Документация пакета pyqtcli (PyQt/PySide CLI Integration)

Documentation in English

PyQtCLI — это пакет для Python, который упрощает интеграцию парсинга аргументов командной строки в приложениях с графическим интерфейсом на базе Qt (PySide/PyQt). Он позволяет легко комбинировать стандартный argparse с возможностью отображения справки в графическом окне (QMessageBox).

Возможности

• Гибкость бэкенда: Автоматически определяет доступную библиотеку Qt (PySide6, PyQt6, PyQt5, PySide2).
• Графическая справка: Класс GUIHelpParser переопределяет вывод справки (-h, --help), отображая её не только в консоли, а в всплывающем окне QMessageBox.
• Удобный миксин: Класс CLIMixin предоставляет все методы argparse.ArgumentParser (add_argument, parse_args и т.д.) для простого добавления в ваши классы.
• Готовая интеграция: Класс QCLIApplication является готовым к использованию наследником QApplication с уже встроенным функционалом CLIMixin.
• Типизация: В комплекте идут .pyi файлы для лучшей поддержки автодополнения и проверки типов в современных IDE.

Установка

Установить пакет можно напрямую из репозитория или после публикации из PyPI (замените на актуальную команду):

# Из репозитория
pip install git+https://github.com/MagIlyasDOMA/pyqtcli.git

# Или после публикации (пример)
pip install pyqtcli

Пакет не устанавливает автоматически конкретную Qt-библиотеку. Вам необходимо установить одну из поддерживаемых самостоятельно:

# Например, для PySide6
pip install pyqtcli[pyside6]

# Или для PyQt5
pip install pyqtcli[pyqt5]

Использование

Быстрый старт с QCLIApplication

Самый простой способ создать приложение с поддержкой аргументов командной строки — использовать готовый класс QCLIApplication.

import sys
from pyqtcli import QCLIApplication
from PySide6.QtWidgets import QMainWindow, QLabel # Пример для PySide6

# Создаем экземпляр приложения, передавая аргументы командной строки
# Все дополнительные параметры (prog, description и т.д.) уходят в парсер.
app = QCLIApplication(
    sys.argv,
    description="Мое супер приложение",
    epilog="Пример использования QCLIApplication"
)

# Добавляем свои аргументы, как в обычном argparse
app.add_argument("-f", "--file", help="Путь к файлу для открытия")
app.add_argument("-v", "--verbose", action="store_true", help="Подробный вывод")

# Парсим аргументы. Справка (-h) автоматически отобразится в графическом окне.
args = app.parse_args()

# --- Здесь стандартный код Qt приложения ---
window = QMainWindow()
if args.file:
    window.setCentralWidget(QLabel(f"Открыт файл: {args.file}"))
else:
    window.setCentralWidget(QLabel("Привет, мир!"))
window.show()

sys.exit(app.exec())

Использование CLIMixin в своем классе QApplication

Если вам нужно больше контроля или вы хотите добавить функционал парсинга в свой собственный класс приложения, используйте CLIMixin.

import sys
from PySide6.QtWidgets import QApplication, QMainWindow, QLabel
from pyqtcli import CLIMixin

class MyApp(QApplication, CLIMixin):
    def __init__(self, argv):
        # Сначала инициализируем миксин с параметрами парсера
        CLIMixin.__init__(self, description="Мое кастомное приложение")
        # Затем инициализируем QApplication
        QApplication.__init__(self, argv)

        # Добавляем свои аргументы
        self.add_argument("--debug", action="store_true", help="Включить режим отладки")

        # Парсим аргументы
        self.args = self.parse_args()

        if self.args.debug:
            print("Отладка включена")

# Запуск приложения
if __name__ == "__main__":
    app = MyApp(sys.argv)

    window = QMainWindow()
    window.setCentralWidget(QLabel("Окно приложения"))
    window.show()

    sys.exit(app.exec())

Использование GUIHelpParser напрямую

Вы можете использовать графический парсер напрямую, например, для создания отдельного инструмента.

import sys
from PySide6.QtWidgets import QApplication
from pyqtcli.argparser import GUIHelpParser

# Создаем парсер
app = QApplication(sys.argv)
parser = GUIHelpParser(prog="tool.py", description="Инструмент с GUI-справкой")
parser.add_argument("-o", "--output", help="Файл для вывода результата")

# При вызове parse_args() справка будет показана в окне,
# если переданы аргументы -h или --help.
# В противном случае парсинг пройдет как обычно.
args = parser.parse_args()
print(args)

Структура пакета

• __init__.py: Основной модуль, экспортирующий классы QCLIApplication, CLIMixin и GUIHelpParser.
• _widgets.py: Внутренний модуль для автоматического выбора и импорта нужного Qt биндинга.
• argparser.py: Содержит классы GUIHelpParser (парсер с графической справкой) и CLIMixin (миксин для добавления парсера в любой класс).