Превращение личного проекта Python в освобождаемую библиотеку

Я академик, а не программист, и у меня есть многолетний опыт написания программ на Python для собственного использования, чтобы поддержать мои исследования. Мой последний проект, вероятно, будет полезен многим другим, а также мне, и я думаю выпустить его как библиотеку Python с открытым исходным кодом.

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

В настоящее время у меня есть один репозиторий git, содержащий мой код, который использует библиотеку, а также саму библиотеку, и я использую git в качестве аварийной кнопки отмены на случай, если что-то сломается. Все это прекрасно работает для одного пользователя, но явно не подходит, если я хочу его выпустить. Я хочу закончить тем, что моя библиотека находится в отдельном репозитории и может быть установлена ​​другими с pipпомощью стабильного API.

Научиться использовать setuptools и т. Д., Вероятно, не так уж и сложно, когда я захочу опубликовать его - моя проблема в том, чтобы узнать, как мне следует работать, чтобы достичь этой точки.

Итак, мой вопрос: какие первые шаги нужно предпринять, чтобы начать подготовку проекта библиотеки Python для общественного потребления? Как мне реорганизовать структуру каталогов, репозиторий git и т. Д., Чтобы начать работу над публичным выпуском библиотеки?

В целом, было бы очень полезно, если бы были ресурсы, которые, как известно, будут полезны при попытке сделать это впервые. Указатели на лучшие практики и ошибки, которых следует избегать и т. Д., Также будут очень полезны.

Некоторое уточнение: текущие ответы касаются вопроса в духе «как я могу сделать мою библиотеку Python подходящей для использования другими?» Это полезно, но отличается от вопроса, который я намеревался задать.

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

• Мой библиотечный код в настоящее время связан с моим собственным доменным кодом, который его использует. Он живет в подпапке и использует один и тот же git-репозиторий. В конце концов, его нужно будет превратить в отдельную библиотеку и поместить в собственный репозиторий, но я продолжаю откладывать это, потому что не знаю, как это сделать. (Ни о том, как установить библиотеку в «режиме разработки», чтобы я все еще мог ее редактировать, ни о том, как синхронизировать два репозитория git.)

• Мои строки документации лаконичны, потому что я знаю, что в конечном итоге мне придется использовать Sphinx или какой-то другой инструмент. Но эти инструменты, кажется, не просты в освоении, поэтому это становится основным подпроектом, и я продолжаю откладывать его.

• В какой-то момент мне нужно научиться использовать setuptools или какой-либо другой инструмент для его упаковки и отслеживания зависимостей, которые являются довольно сложными. Я не уверен, нужно ли мне делать это сейчас или нет, и документация - абсолютный лабиринт для нового пользователя, поэтому я продолжаю принимать решение позже.

• Мне никогда не приходилось проводить систематическое тестирование, но я определенно буду участвовать в этом проекте, поэтому мне нужно (i) узнать достаточно о тестировании, чтобы знать, какая методология подходит для моего проекта; (ii) узнать, какие инструменты доступны для выбранной мной методологии; (iii) научиться использовать выбранный мной инструмент; (iv) внедрить тестовые наборы и т. д. для моего проекта. Это проект сам по себе.

• Могут быть и другие вещи, которые я должен сделать. Например, Джонршарп опубликовал полезную ссылку, в которой упоминаются git-flow, tox, TravisCI, virtualenv и CookieCutter, о которых я раньше не слышал. (Сообщение написано в 2013 году, поэтому мне также нужно проделать определенную работу, чтобы выяснить, сколько еще актуально.)

Когда вы соберете все это воедино, это будет огромный объем работы, но я уверен, что смогу сделать все это, если буду продолжать это делать, и я не спешу. Моя проблема в том, чтобы знать, как разбить его на управляемые шаги, которые можно выполнять по одному.

Другими словами, я спрашиваю, какие из наиболее важных конкретных шагов я могу предпринять сейчас, чтобы в конечном итоге достичь выпускаемого продукта. Если у меня будут свободные выходные, на каких вещах я должен сосредоточиться? Что (если таковое имеется) может быть сделано в отрыве от других, чтобы я мог сделать хотя бы один шаг без необходимости делать все это? Какой самый эффективный способ изучить эти вещи, чтобы у меня все еще было время сосредоточиться на самом проекте? (Имея в виду, что все это, по сути, проект хобби, а не моя работа.) Есть ли что-то, что мне на самом деле не нужно , что экономит мне огромное количество времени и усилий?

Все ответы очень ценятся, но я бы особенно хотел получить ответы, которые сосредоточены на этих аспектах управления проектами, с конкретной ссылкой на современную разработку Python.

Добавление файла setup.py, при необходимости, не является самым важным шагом, если вы хотите, чтобы ваша библиотека использовалась. Более важно добавить документацию и рекламировать свою библиотеку. Поскольку второй момент сильно зависит от библиотеки, позвольте мне сосредоточиться на аспекте документации.

1. Вы знаете все о своей библиотеке. И это проблематично. Вы уже знаете, как установить и использовать его, поэтому многие вещи могут показаться вам интуитивно понятными или очевидными. К сожалению, одно и то же не может быть ни очевидным, ни интуитивно понятным для пользователей. Попробуйте взглянуть на свою библиотеку так, как будто вы ничего не знаете об этом, и, что более важно, попросите других людей использовать ее и постарайтесь выявить все трудности, с которыми они столкнулись.

2. Объясните простым языком, о чем ваша библиотека. Слишком много библиотек предполагают, что о них все знают. Когда это не так, может быть трудно понять, какова цель библиотеки.

3. Пишите подробную техническую документацию, но также не забывайте о коротких фрагментах кода, которые показывают, как выполнять некоторые задачи с вашей библиотекой. Большинство разработчиков спешат, и если им нужно часами пытаться понять, как сделать что-то простое, они могут переключиться на другие библиотеки.

4. Включите вашу контактную информацию. Если ваша библиотека пользуется успехом (и мой собственный опыт показал, что это относится даже к довольно неизвестным), люди столкнутся с трудностями: либо ошибками, либо просто трудностями в понимании или использованием некоторых ее частей. Часто полезно получить их отзывы для улучшения вашей библиотеки: для каждого человека, который сообщил о проблеме, возможно, есть сотни, которые, столкнувшись с ней, просто предпочли бы переключиться на другую библиотеку.

В дополнение к этому:

1. Укажите, работает ли ваша библиотека с Python 2 или 3 или с обоими.

2. Если библиотека не работает в Windows, скажем так.

3. Убедитесь, что вы используете официальные соглашения (используйте pep8 для проверки). Если нет, либо объясните это ясно, либо исправьте.

4. Позаботьтесь о крайних случаях. Когда ваша библиотека вызывается с неправильным типом или со значением, которое не поддерживается, на простом английском языке следует сказать, что именно является неправильным. Чего не следует делать, так это поднять загадочное исключение на десять уровней вниз по стеку и позволить пользователю выяснить, что пошло не так.

Используя несколько менее чем зрелых библиотек в течение многих лет, ключевой совет - как только вы выберете свой инструмент развертывания, сделайте следующее: Ваша библиотека делает что-то действительно полезное, что вы можете создать сообщество вокруг?

Определите зависимости вашей библиотеки.

Попытайтесь выполнить развертывание в чистой среде, либо в Docket-контейнере, либо в VM. Я считаю этот шаг крайне важным, так как часто в личной среде есть что-то уникальное, что вызывает проблемы.

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

Подумайте, хотите ли вы или ваша команда взять на себя обязательство по проверке и документированию библиотеки (юнит-тесты и конвейеры CI становятся частью уравнения здесь).

Возможно, вы могли бы найти зрелый проект OSS в своей области и внести свой код в этот проект? Там может быть несколько преимуществ, таких как:

• Вы можете увеличить свой вклад. Действительно, многие «хобби» проекты OSS потенциально ценны, но мало используются сообществом (см. @ReaddyEddy answer). Это просто много усилий, чтобы сначала создать проект с нуля, а затем поддерживать его, рекламировать, предоставлять надлежащие примеры и документацию и т. Д.
• Многие из упомянутых вами технических проблем уже будут решены в зрелом проекте.
• Если ваша библиотека добавляет ценность проекту OSS, ее участники могут помочь вам привести ваш код в соответствие со стандартами проекта. Таким образом, вы можете сэкономить усилия и получить опыт. Вы также получите конкретные ответы о Sphinx, TravisCI, CookieCutter и других технических аспектах.

Если есть соответствующий проект OSS, который вам нравится и, возможно, используется, почему бы не открыть вопрос или запрос на извлечение или иным образом не связаться с сопровождающими? (Хороший способ начать - решить существующую проблему.)

Наступил 2019 год, я настоятельно рекомендую начать с самых современных инструментов. Вам не нужно, это setup.pyто, от чего люди в сообществе Python хотят избавиться, и я верю, что в конце концов они это сделают.

Попробуйте поэзию , вы не пожалеете об этом.

Это сложный вопрос, который вы задаете, и я полностью согласен с ответом Арсения . Хорошая документация - очень важный аспект. Если мне не удастся запустить вашу библиотеку с помощью нескольких простых шагов, я просто оставлю ее прямо здесь (если только я действительно не хочу попробовать ее).

Некоторые вещи, которые вы определенно считаете

• Подумайте, как вы собираетесь создавать версии вашей библиотеки. Вы хотите иметь обратную совместимость до некоторого уровня, а также исправления ошибок по маршруту. Читайте о семантическом версионировании
• Вы используете Git относительно линейным способом (чтобы отменить). Вы знакомы с ветвлением в git . Это действительно не так сложно, и делает жизнь легкой. Как только вы овладели ветками. Адаптируйте модель ветвления для своего хранилища. Выберите части этой модели ветвления, которые вы считаете уместными. Также сравните это с ветками из репозиториев, которые вы используете.
• Лицензирование: вы должны предоставить лицензию для своей библиотеки. Я не специалист по правовым вопросам в этом вопросе, поэтому я могу только поделиться ссылкой на это сравнение между общими лицензиями . Не принимайте этот выбор легко.
• Баг трекер. Вы хотите, чтобы этот пользователь мог предоставлять вам отчеты об ошибках. Это поможет вам улучшить качество кода. Для каждой ошибки, которую вы исправляете, добавьте тест к вашей структуре тестирования, которая гарантирует, что она не будет тормозить в будущем (регрессионное тестирование). Система отслеживания ошибок может использоваться для запросов функций.
• Вклады пользователей. Вы хотите, чтобы пользовательский вклад? Я не уверен, как это обычно работает на продуктах с открытым исходным кодом, но я могу представить, что вы можете позволить пользователям создавать ветки функций. С помощью github вы, кажется, сможете контролировать это с помощью запросов на получение доступа.

У меня нет соответствующего опыта работы с Python, поэтому я не могу дать вам никаких советов в этом направлении. Тем не менее, можно автоматизировать все тесты, запускаемые каждым коммитом в вашем удаленном хранилище (то есть с использованием Jenkins ). Я, однако, предлагаю отложить это, потому что это много работы, чтобы настроить без предварительного опыта.

Это замечательные вопросы.

О важных конкретных дополнительных шагах в направлении выпускаемой библиотеки:

• Отделите файлы, которые станут библиотекой, от остальной части проекта.
  • Библиотека должна идти в свой собственный репозиторий git, но вы можете посчитать полезным промежуточный шаг, чтобы поместить ее в отдельный каталог верхнего уровня в вашем текущем репозитории. Когда вы сделаете его отдельным хранилищем, сохраните его рядом с остальной частью вашего проекта, который затем можно будет ссылаться на него ../libraryдо тех пор, пока не дойдете до этапов упаковки и разработки pip.
  • Все доступы от остальной части проекта к этой библиотеке должны проходить через ее публичный API. Вы можете найти некоторые взаимозависимости, чтобы дразнить друг от друга.
• Постепенно пишите строки документов для документирования API библиотеки.
  • В конечном итоге строки документов будут использоваться в инструменте документирования, но важной задачей является написание текста, который объясняет API кратко и в достаточной степени для других людей. Проще заполнить его немного за раз, чем сразу, и гораздо лучше получится, если написать черновики и вернуться к ним позже, когда придут лучшие объяснения и примеры.
  • Если вы обнаружите, что некоторую часть API трудно документировать, спросите, есть ли у этой части API возможности для улучшения. Может ли быть проще? Более регулярный? Это слишком общее? Слишком специализированный? Может ли он использовать более знакомые имена?
  • Строки документов могут документировать типы аргументов с помощью структурированных комментариев, которые могут проверять инструменты. Я еще не нашел реальной документации по этому вопросу, но PyCharm IDE поможет сконструировать эти строки документов и сразу же проверит типы аргументов при редактировании вызовов методов.
  • Кстати, PyCharm - замечательный инструмент для экономии времени разработчиков и улучшения качества кода. Он будет запускать «проверки», чтобы проверять код во время его редактирования, например проверять типы, когда это возможно, проверять отсутствующие и неиспользуемые импорта, дублирующие методы, ошибки стиля PEP 8 и так далее.
• Начните писать модульные тесты, используя pytest. Задолго до того, как вы выпустите релиз, модульные тесты окупятся в вашей собственной разработке, выявляя ошибки в ключевых случаях и обеспечивая уверенность в том, что изменения кода не сломали вещи. Опять же, вы можете создать это со временем. Это довольно легко начать.
• Просмотрите существующие библиотеки с открытым исходным кодом (примерно одинакового размера) на GitHub, чтобы увидеть, как они организуют файлы и выпуски. Посмотрите, как они выполняют отслеживание ошибок / ошибок и извлекают запросы. Внесите свой вклад в один или несколько из них, чтобы получить опыт работы с этими процессами организации проекта из нескольких человек, если у вас нет такого опыта. GitHub имеет хорошие инструменты для этих процессов. Он хорошо работает с README.mdфайлами документации на верхнем уровне и в любом каталоге, а также с файлом лицензии.
• Подумайте над тем, чтобы привлечь коллаборатора для получения отзывов о библиотеке, ее API и документации.
  • Когда вы выпускаете, это поможет одному или нескольким сотрудникам исправлять ошибки, когда вы находитесь в отпуске, помогать отвечать на вопросы пользователей, а между тем начинать выполнять запросы на извлечение с обзорами кода, чтобы разделять задачи по выпуску библиотек, и привнести дополнительный опыт управления проектами и библиотекой.
• До сих пор вы делали линейную историю git commit. В конце концов будет полезно использовать «ветки выпуска» для конкретных исправлений и изменений, «ветки выпуска» для контролируемой подготовки к выпуску и «ветки разработки» для любой выполняемой работы с несколькими людьми, которая не готова к объединению в мастер ветку. Так что выделите день или два на этом пути, чтобы узнать об этом и начать практиковаться с ним, прежде чем вам нужно будет полагаться на эти навыки git. Git очень гибок и полезен, но пользовательский интерфейс может быть чреват .
  • Одно из мест, где можно прочитать о ветвях git и их использовании, находится в книге Pro Git . Из множества способов использования веток начните с «выдачи веток».
  • Приложение GitHub Desktop - отличный инструмент для управления филиалами. Он также отлично подходит для совершения коммитов, поскольку позволяет легко написать сообщение о коммите, просматривая все изменения.