将个人Python项目变成可发布的库

我是一名学者，而不是程序员，并且我有多年编写供自己使用的Python程序以支持我的研究的经验。我的最新项目可能对我和其他许多人都有用，并且我正在考虑将其作为开源Python库发布。

但是，从运行中的个人项目到可以被其他人轻松安装和使用的库，似乎有许多障碍需要克服。这个问题是关于我应该开始着手公开发布的第一步。

目前，我只有一个git存储库，其中包含使用该库以及该库本身的代码，并且我将git用作紧急撤消按钮，以防万一发生任何问题。所有这些对于单个用户都可以正常工作，但是如果我要释放它，显然不合适。我要结束的地方是我的库位于单独的存储库中，并且可以由其他人使用来安装pip，并且具有稳定的API。

一旦我想发布它，学习使用setuptools等可能就不那么困难了-我的问题是知道如何工作才能达到这一点。

所以我的问题是，为了开始准备供公众使用的Python库项目，应该采取的第一步步骤是什么？我应该如何重组我的目录结构，git仓库等，以便开始努力公开发布该库？

更一般而言，如果首次尝试使用已知有帮助的资源，那将非常有帮助。指向最佳实践和避免错误的指针等也将非常有帮助。

需要澄清的是：当前的答案是按照“如何使我的Python库成为其他人可以使用的好库？”的方式来解决一个问题。这很有用，但是与我要提出的问题不同。

我目前正处于发布项目的漫长旅程的开始。我的实现的核心工作正常（并且工作得很好），但是我对即将进行的大量工作感到不知所措，并且我正在寻找有关如何进行流程导航的指导。例如：

• 我的库代码当前已耦合到我自己的使用它的特定于域的代码。它位于子文件夹中，并且共享相同的git存储库。最终，需要将其制作成一个独立的库并放入其自己的存储库中，但是由于我不知道如何做，所以我一直在拖延。（既不是如何在“开发模式”下安装库以使我仍然可以对其进行编辑，也没有如何使两个git仓库保持同步。）

• 我的文档字符串很简洁，因为我知道最终我将不得不使用Sphinx或其他工具。但是这些工具似乎并不容易学习，因此这成为一个主要的子项目，我一直推迟进行。

• 在某些时候，我需要学习使用setuptools或其他工具来打包它并跟踪依赖项，这非常复杂。我不确定现在是否需要这样做，并且该文档对于新用户来说绝对是个迷宫，因此我决定以后再做。

• 我从来不需要进行系统的测试，但是我肯定会对此项目进行测试，因此，我必须（i）了解足够的测试知识，以了解哪种方法适合我的项目；（ii）了解哪些工具可用于我选择的方法；（iii）学习使用我选择的工具；（iv）为我的项目实施测试套件等。这本身就是一个项目。

• 我可能还有其他事情要做。例如，jonrsharpe发布了一个有用的链接，其中提到了git-flow，tox，TravisCI，virtualenv和CookieCutter，我以前从未听说过。（该帖子来自2013年，所以我还必须做一些工作来找出仍有多少钱。）

当您将所有这些放在一起时，这是一项巨大的工作，但是我敢肯定，如果我坚持不懈地完成工作，那么我就可以完成所有工作，而且我不着急。我的问题是知道如何将其分解为可管理的步骤，一次可以完成。

换句话说，我要问的是我现在可以采取哪些最重要的具体步骤，以便最终获得可发布的产品。如果我有空闲的周末，我应该关注哪些事情？哪一个（如果有的话）可以与其他人孤立地完成，这样我至少可以完成一个步骤而无需做整个事情？学习这些东西最有效的方法是什么，这样我仍然有时间专注于项目本身？（请记住，所有这些本质上都是一项业余项目，而不是我的工作。）我是否真的不需要做任何事情，从而为自己节省了大量时间和精力？

非常感谢所有答案，但是我特别欢迎关注这些项目管理方面的答案，尤其是对现代Python开发的引用。

如果需要使用库，则在必要时添加setup.py并不是最重要的步骤。更重要的是添加文档并公布您的库。由于第二点在很大程度上取决于库，因此让我宁愿关注文档方面。

1. 您了解图书馆的所有知识。这是有问题的。您已经知道如何安装以及如何使用它，因此许多事情对于您而言似乎是直观的或显而易见的。不幸的是，对于用户而言，相同的事情可能既不明显，也不直观。尝试看一下图书馆，就好像您对图书馆一无所知一样，更重要的是，请其他人使用它并尝试找出他们遇到的所有困难。

2. 用简单的英语解释您的图书馆的内容。太多的图书馆假设每个人都知道它们。如果不是这种情况，可能很难掌握库的目的。

3. 编写详细的技术文档，但也不要忘记一些简短的代码，这些代码显示了如何使用您的库执行某些任务。大多数开发人员都很着急，如果他们需要花费数小时来尝试了解基本操作，他们可能会倾向于使用其他库。

4. 包括您的联系信息。如果您的图书馆是成功的（我的经验表明，即使是相当陌生的图书馆也是如此），人们会遇到困难：错误或仅是理解或使用其中某些部分的困难。经常收到他们的反馈以改善您的图书馆是很有用的：对于每个报告问题的人，可能有数百人在遇到问题时更愿意切换到另一个图书馆。

除此之外：

1. 明确说明您的库是使用Python 2还是3或同时使用两者。

2. 如果该库在Windows上不起作用，请说出来。

3. 确保使用官方约定（使用pep8进行检查）。如果不是，请清楚地解释或修复它。

4. 注意处理边缘情况。如果使用错误的类型或不支持的值调用您的库，则应该以纯正的英语说出到底是什么错误。它不应该做的是在堆栈的10层以下引发一个神秘的异常，并让用户找出出了什么问题。

多年来，使用的库比成熟的库少了很多，一个关键的建议是一旦您选择了部署工具，请执行以下操作：库是否确实在做一些有用的事情来建立社区？

确定您的库依赖项。

尝试将其部署到清洁环境中，无论是容器还是虚拟机。我认为这一步骤至关重要，因为对于所有人而言，导致问题的个人环境常常会有一些独特之处。

考虑一下谁将在未来维护该图书馆，没有比遇到一个被人们宠爱的图书馆长达三，四年而又没有获得保持其最新状态的更新令人沮丧的了。

考虑您或您的团队是否要承诺对库进行测试和记录（单元测试和CI管道开始成为此处方程式的一部分）。

也许您可以在自己的领域中找到一个成熟的OSS项目并为该项目贡献代码？可能会有一些优点，例如：

• 您可以最大程度地贡献自己的力量。确实，许多“业余” OSS项目具有潜在价值，但社区很少使用（请参阅@ReaddyEddy答案）。首先要使该项目从头开始，然后进行维护，做广告，提供适当的示例和文档等，这是大量的工作。
• 您提到的许多技术问题将在成熟的项目中解决。
• 如果您的库为OSS项目增加了价值，则其贡献者可以帮助您将代码提高到项目标准。因此，您可以节省精力并获得经验。您还将获得有关Sphinx，TravisCI，CookieCutter和其他技术方面的具体答案。

如果有您喜欢并可能使用的相关OSS项目，为什么不提出问题或提出要求，或者与维护者取得联系？（一个好的开始方法可能是解决现有问题。）

现在是2019年，我强烈建议您从最先进的工具入手。您不需要a setup.py，这是Python社区中的人们想要摆脱的东西，我相信最终他们会这样做。

尝试诗歌，您将不会后悔。

您要问的是一个复杂的问题，我完全同意Arseni的回答。良好的文档编制是非常重要的方面。如果我没有通过几个简单的步骤就可以成功启动和运行您的库，那么我只是将其放在那里（除非我真的很想尝试一下）。

您一定要考虑的一些事情

• 考虑一下如何对库进行版本控制。您希望在某种程度上具有向后兼容性，并且还希望沿路线修正错误。阅读有关语义版本控制的信息
• 您以相对线性的方式使用git（撤消）。您是否熟悉git分支。确实没有那么困难，并且使生活变得轻松。一旦您掌握了分支机构。为您的存储库调整分支模型。选择该分支模型中您认为相关的部分。还要将此与您正在使用的存储库中的分支进行比较。
• 许可：您应该为您的图书馆提供许可。我不是这方面的法律专家，所以我只能共享一个链接，以比较普通许可证。不要掉以轻心。
• Bugtracker。您希望该用户可以为您提供错误报告。这可以帮助您提高代码质量。对于您解决的每个错误，在测试框架中添加一个测试，以确保将来不会出错（回归测试）。错误跟踪系统可用于功能请求。
• 用户贡献。您要用户贡献吗？我不确定这在开源产品上通常如何工作，但是我可以想象您可以允许用户创建功能分支。通过github，您似乎能够通过请求请求来控制它

我没有使用Python的相关经验，因此无法向您提供任何有关该方向的提示。但是，可以自动执行远程存储库中每次提交触发的所有测试（即使用Jenkins）。但是，我建议推迟此操作，因为在没有事先经验的情况下要进行大量工作。

这些是很好的问题。

关于迈向可发布库的重要的具体增量步骤：

• 将将成为库的文件与项目的其余部分分开。
  • 该库应该进入其自己的git存储库，但您可能会发现它是有用的中间步骤，可以将其放入当前存储库中的单独顶层目录中。当您将其制作为单独的存储库时，请将其存储在项目的其余部分附近，然后可以通过引用它，../library直到您完成pip打包和开发模式步骤为止。
  • 从项目的其余部分到该库的所有访问都应通过其公共API进行。您可能会发现一些相互依存的关系，需要分开。
• 逐步编写文档字符串以记录库的API。
  • 最终，文档字符串将输入到文档工具中，但是重要的工作是编写简洁，充分地向其他人解释API的文本。一次填充一次比一次一次填充要容易得多，并且通过编写草稿并在稍后想到更好的解释和示例时再返回会更好。
  • 如果您发现API的某些部分难以记录，请询问API的那部分是否还有改进的余地。会更简单吗？更常规吗？太笼统了吗？太专业了吗？可以使用更熟悉的名称吗？
  • 文档字符串可以使用工具可以检查的结构化注释来记录参数类型。我还没有找到真正的文档，但是PyCharm IDE将帮助构造这些文档字符串，并在编辑方法调用时立即检查参数类型。
  • 说到这，PyCharm是节省开发人员时间并提高代码质量的绝佳工具。在编辑代码时，它将运行“检查”以检查代码，例如，在可能的时候检查类型，检查丢失和未使用的导入，重复的方法，PEP 8样式错误等。
• 开始使用编写单元测试pytest。在发布之前很久，单元测试将通过在极端情况下发现错误并提供对代码更改不会破坏事情的信心来在您自己的开发中获得回报。同样，您可以随着时间的流逝建立起来。开始很容易。
• 仔细阅读GitHub上现有的开源库（大小大致相同），以了解它们如何组织文件和发行版。观察他们如何进行错误/问题跟踪并提取请求。如果您没有经验，可以贡献一个或多个来获得这些多人项目组织过程的经验。GitHub为这些过程提供了很好的工具。它可以README.md在顶级和任何目录中的文档文件以及许可证文件中完成出色的工作。
• 考虑招募合作者以获得关于库，其API和文档的反馈。
  • 发布时，有一个或多个协作者可以在您休假时修复错误，帮助回答用户问题以及同时开始执行带有代码审阅的Pull Request，分担发布库的任务，这将很有帮助，并带来有关项目管理和图书馆设计的更多经验。
• 到目前为止，您一直在执行线性git commit历史记录。最终，对特定的修复和更改使用“问题分支”，对发布的受控运行使用“发布分支”，对于尚未准备好进行合并的任何多人正在进行的工作，将使用“开发分支”进入master分支。因此，在需要依赖那些git技能之前，请花一两天的时间来学习这一点并开始进行练习。git非常灵活和有用，但是用户界面可能很烦。
  • Pro Git书中提供了一个有关git分支及其用法的地方。在使用分支的许多方法中，仅从“问题分支”开始。
  • GitHub Desktop应用程序是管理分支的绝佳工具。这对于进行提交也非常有用，因为它使得在审查所有更改时很容易编写提交消息。