Руководство по поддержке Torchvision

Документ предназначен для документирования пользовательских политик / принципов, используемых при разработке и поддержке torchvision. Другая информация для поддержки (например, процесс выпуска) может быть найдена в мета-внутреннем вики.

Что является публичным, а что приватным?

Для Python API, torchvision в основном следует политике PyTorch, которая согласована с другими основными пакетами (numpy, scikit-learn и т.д.). Мы признаем, что эта политика несколько несовершенна для некоторых краевых случаев, и что трудно придумать точное техническое определение. В общих чертах, которые обычно хорошо понимаются пользователями, политика заключается в следующем:

• модули, которые можно получить доступ к без ведущего подчеркивания, являются публичными
• объекты в публичном файле, которые не имеют ведущего подчеркивания, являются публичными
• атрибуты класса являются публичными, если они не имеют ведущего подчеркивания
• остальные модули / объекты / атрибуты класса считаются приватными

Публичный API имеет гарантии обратной совместимости (BC), определенные в нашей политике устаревания (см. ниже). Приватный API не имеет гарантий BC.Для C++, код является приватным. Для сотрудников Meta: если изменение C++ нарушает fbcode, исправьте fbcode или отмените изменение. Мы должны быть осторожны с моделями, работающими в продакшне и зависящими от операций torchvision.

Папка test не импортируется и является приватной. Даже мета-внутренние проекты не должны зависеть от неё (это было в прошлом и теперь программно невозможно).

Обучающие ссылки не имеют гарантий обратной совместимости. Возможны изменения, но мы должны убедиться, что учебники продолжают работать правильно, и что их намеренная история сохраняется (например, проверяя выходные данные и т.д.).

Остальные папки (build, android, ios и т.д.) являются приватными и не имеют гарантий BC.

Политика устаревания.

Поскольку они нарушают работу, устаревание следует использовать с осторожностью.

Мы в основном следуем политике PyTorch: изменения, нарушающие работу, требуют периода устаревания как минимум в две версии. Устаревшие элементы должны четко указывать крайний срок в документации и предупреждающих сообщениях. Избегайте отсутствия конкретного срока или поддержания устаревших API слишком долго: это не стимулирует пользователей обновлять свой код, создает противоречивые сообщения ("почему этот API был удален, а этот другой все ещё существует?") и накапливает долг в проекте.### Должна ли эта атрибута быть публичной? Должна ли эта функция быть приватной?

При проектировании API не всегда очевидно, что следует выставлять как публичное, а что оставлять как приватная деталь реализации. Следующие руководства могут быть полезными:

• Функциональная последовательность по всей библиотеке является приоритетом для пользователей и разработчиков. В случае сомнений и если это явно не неправильно, выставляйте то, что выставляют другие похожие классы.
• Тщательно подумайте о пользователях и их сценариях использования, и попытайтесь выставить то, что они будут использовать для решения этих сценариев. Агрессивно сохраняйте все остальное приватным. Помните, что направление "приватное -> публичное" намного гладче, чем "публичное -> приватное": в случае сомнений, сохраняйте его приватным.
• При рассмотрении сценариев использования, общее правило API применимо: делайте то, что просто и распространено, легко доступным, и делайте то, что сложное, возможным (правило 80% / 20%). Может быть около 1% не решено: это нормально. Также, делайте то, что неправильно, очень трудным, если не невозможным.

Как хорошая практика, всегда создавайте новые файлы и даже классы с начальным подчеркиванием в их названии. Таким образом, все является приватным по умолчанию, а единственная публичная поверхность явно присутствует в файле __init__.py.