Документація має значення

Мене підвела незрозуміла документація. Я створюю сучасний термінальний інтерфейс на Python за допомогою чудового фреймворку Textual. Він елегантний, швидкий і, якщо чесно, працювати з ним доволі весело. Та нещодавно я зайшов у глухий кут, намагаючись передати власне повідомлення від компонента до головного застосунку.

Усе виглядало правильно:

class InitialSetup(Container):

    class SubmitForm(Message):
        def __init__(self, form_data: dict) -> None:
            super().__init__()
            self.form_data = form_data

    async def on_button_pressed(self, event: Button.Pressed) -> None:
        self.app.post_message(self.SubmitForm({"foo": "bar"}))

Я очікував, що метод on_submit_form у застосунку отримає це повідомлення. Але нічого не сталося. Жодної помилки. Жодного збою. Просто… тиша.

Після двох днів налагодження — перевірок ідентифікаторів, успадкування та маршрутів доставки повідомлень — я нарешті виявив проблему: вкладені класи повідомлень не обробляються належним чином, коли вони використовуються через межі модулів.

Інакше кажучи, документація стверджувала, що ось так можна:

class SomeWidget:
    class MyMessage(Message): ...

Але в реальному застосунку з кількома файлами та імпортами це просто мовчки не працювало. Щойно я виніс клас повідомлення SubmitForm із вкладеного класу на верхній рівень, усе запрацювало чудово.

Якось я написав листа Гвідо

Багато років тому я три дні намагався зрозуміти, як працює одна можливість Python. Зрештою випадково натрапив на слайд із доповіді Гвідо ван Россума, який усе прояснив.

Тоді я написав йому електронного листа. Чемно пояснив проблему й запропонував додати це пояснення до офіційної документації.

І він відповів! Дуже люб’язно. А потім… додав мене до списку авторів документації Python.

Моє ім’я досі можна знайти в документації Python 3.2.2. Непоганий результат для повідомлення про проблему.

Документація має значення

Цей досвід вплинув на моє ставлення до документації. Коли вона правильна, її навіть не помічаєш. Але коли в ній є помилки, навіть ледь помітні, вони можуть коштувати кількох днів життя.

Тому я відкрив задачу на GitHub для команди Textual і звернув увагу, що їхній приклад із «вкладеним класом повідомлень» працює лише в однофайлових застосунках. Його потрібно виправити або принаймні додати застереження.

Бо якщо це сталося зі мною, станеться й із кимось іншим. І не кожному трапиться слайд від Гвідо, який врятує ситуацію.

• 2026 19
• 2025 16
• 2024 2