Есть библиотека на Python со множеством сущностей. Часть сущностей разработчик библиотеки считает приватными, а часть - публичными. Что значит «приватный» и «публичный» в контексте этого треда и моего вопроса:
- Приватный = «я не предполагаю, что сторонние пользователи будут использовать эти интерфейсы, я не уверен в стабильности этого интерфейса, не хочу показывать его во вне и хочу зарезервировать за собой право менять интерфейс без предупреждения»
- Публичный = «я предполагаю, что сторонние пользователи будут использовать эти интерфейсы, я буду стараться их не ломать, или, по крайней мере, ломать gracefully, например через deprecation warning-и, release note-ы или иные инструменты»
Теперь возникает технический и организационный вопрос, как выделить публичные интерфейсы, и тут есть варианты:
- Через соглашение об именовании приватных сущностей, например
_my_variableили_MyClass. Плюсы:
- Описано в PEP-8
Минусы:
- По-умолчанию, я предполагаю свой класс «приватным» в контексте библиотеки, т.к. лучше сначала всё закрыть и запретить, и только потом разрешить/открыть малую часть. Это значит, что 90% моих классов, которые по сути приватны, будут начинаться с
_? Код превратится в кашу!
- При помощи
__all__Плюсы:
- Описано в PEP
Вопросы:
__all__говорит «это можно импортировать», но не говорит, где импортировать - для внутреннего использования внутри библиотеки или для внешнего пользователем. Вариантом решения тут могло бы быть именование package, начиная с_, например:
mylib/__init__.py
mylib/_gears/__init__.py # <-- тут __all__ = ['X']
mylib/mylib.py # <-- тут from ._gears import X
и тогда код вида from mylib import Y будет явно публичным, но from mylib._gears import X - «ошибочным», т.к. мы явно залезаем в приватную часть либы.
Минусы/вопросы:
- Так кто-то еще делает? Выглядит велосипедно немного?…
- Есть версия, что «The RealDefinition™ is that whatever we include in the docs is public, otherwise not.» Плюсы:
- Просто и понятно
Минусы:
- Требует документации
- Недостаточно формально. Если с приватными пакетами можно явно сказать «у вас в импорте подчеркивание, сами виноваты», то тут надо «а где это описано в документации? вы уверены, что можете это импортировать? давайте читать доки…»
NOTE: другие языки или изменения языка программирования как способ решить задачу не рассматривается. Пожалуйста, не советуйте, этого! Это вопрос про Python.
