python_boilerplate_template 1.0.1

安装

安装软件包的最简单方法是通过easy_install或pip：

$ easy_install python_boilerplate_template

请注意，该包是paster工具的插件paster工具由PasteScript包提供（它将随python_boilerplate_template一起自动安装）。可执行文件paster应该出现在python的bin/（在windows Scripts/）目录中。可能需要将该目录添加到PATH中才能运行可执行文件。

用法

要为新项目初始化目录布局，请确保paster位于您的路径中并运行：

$ paster create -t python_boilerplate <project_name>

在提出一些基本问题后，该工具将为您创建以下项目布局：

<project_name>/
  |
  +-- .gitignore           # Git configuration
  +-- .travis.yml          # Travis-CI configuration
  +-- bootstrap.py         # Buildout bootstrap-script
  +-- buildout.cfg         # Buildout project configuration
  +-- setup.cfg            # Configuration for py.test and other tools
  +-- README.md            # Information on how to use the project
  +-- src/                 # Directory for keeping (possible multiple) project eggs
      |
      +- <egg_name>/       # First egg of the project
         |
         +-- package/      # Python source files
         +-- tests/        # Tests
         +-- .gitignore    # Git configuration
         +-- .travis.yml   # Travis-CI configuration
         +-- setup.cfg     # Configuration for py.test and other tools
         +-- setup.py      # Package metadata
         +-- MANIFEST.in   # Files to include in the package
         +-- README.rst    # Package description
         +-- LICENSE.txt   # License
         +-- CHANGELOG.txt # Changelog

此结构建议您将项目开发为一个eggs集合，每个egg在src/中有其单独的子目录。每个egg使用标准的setuptools布局，整个项目依赖于buildout来组织各个部分

项目准备

创建项目布局之后，下一步要做的是将代码添加到版本控制存储库中。有两个常用选项供您选择：

1. For smaller single-package projects you might want to keep only the Python’s package code (i.e. ^{tt13}$) under version control, and consider the rest (the ^{tt14}$ and all that comes with it) to be your local development environment.
2. For larger projects you should consider keeping the whole development environment (including ^{tt14}$, perhaps several eggs under ^{tt16}$, docs in ^{tt17}$, etc) under version control.

如果您决定支持选项1：

• Create a version control repository under ^{tt13}$. Here is an example with Git:

  > cd src/<egg_name>
  > git init
  > git add .
  > git commit -m "Initial package structure"
  

  If you are using Github, proceed by creating a <your-project> repository on the Github website, and then doing:

  > git remote add origin https://github.com/<username>/<your-project>.git
  > git push origin master
  

• You can safely delete the ^{tt19}$ file in the root of the project (but leave the one within the ^{tt13}$ directory).

如果您决定支持选项2：

• Create a version control repository under the project root. The Git/Github example above applies, except for the first ^{tt21}$ line.
• Drop ^{tt19}$ from the ^{tt13}$ directory (leave the one in the project root).

在开始开发代码之前，您可能希望优化src/<egg_name>/README.rst文件。此文件应包含软件包应执行的操作的详细说明。特别是，当您将包提交给pypi时，该文件的内容将显示在包索引页上。

此外，样板代码中包含的LICENSE.txt是MIT许可证的副本如果项目使用其他许可证，请替换此文件以匹配

最后，您还需要编辑README.md，以反映应用于项目的开发说明

最后，查看src/<egg_name>/setup.py中的设置（例如，classifiers参数可能需要调整）。

完成准备工作后，可以通过运行python bootstrap.py然后运行buildout开始开发。见下一节。

共同发展任务

• Setting up the development environment before first use:

  > python bootstrap.py
  > export PATH=$PWD/bin:$PATH
      (in Windows: set PATH=%CD%\bin;%PATH%)
  > buildout
  

• Running tests

  Tests are kept in the tests directory and are run using:

  > py.test
  

• Creating Sphinx documentation:

  > sphinx-quickstart
  (Fill in the values, edit documentation, add it to version control)
  (Generate documentation by something like "cd docs; make html")
  

  (See this guide for more details)

• Specifying dependencies for your package:

  Edit the ^{tt32}$ line in ^{tt28}$ by listing all the dependent packages.
• Producing executable scripts:

  Edit the ^{tt34}$ section of ^{tt35}$ in ^{tt28}$. Then run ^{tt31}$. The corresponding scripts will be created in the ^{tt8}$ subdirectory. Note that the boilerplate project already contains one dummy script as an example.
• Debugging the code manually:

  Simply run ^{tt39}$. This generated interpreter script has the project package included in the path.

• Publishing the package on Pypi:

  > cd src/<egg_name>
  > python setup.py register sdist upload
  

• Creating an egg or a windows installer for the package:

  > cd src/<egg_name>
  > python setup.py bdist_egg
   or
  > python setup.py bdist_wininst
  

• Travis-CI integration:

  To use the Travis-CI continuous integration service, follow the instructions at the Travis-CI website to register an account and connect your Github repository to Travis. The boilerplate code contains a minimal ^{tt19}$ configuration file that might help you get started.
• Other tools:

  The initial ^{tt14}$ includes several useful code-checking tools under the ^{tt42}$ section. Adapt this list to your needs (remember to run ^{tt31}$ each time you change ^{tt14}$).
• Working with setup.py:

  If you are working on a small project you might prefer to drop the whole ^{tt31}$ business completely and only work from within the package directory (i.e. make ^{tt46}$ your project root). In this case you should know that you can use

  > python setup.py develop
  

  to include the package into the system-wide Python path. Once this is done, you can run tests via:

  > python setup.py test
  

  Finally, to remove the package from the system-wide Python path, run:

  > python setup.py develop -u
  

• Developing multi-package projects:

  Sometimes you might need to split your project into several packages, or use a customized version of some package in your project. In this case, put additional packages as subdirectories of ^{tt12}$ alongside the original ^{tt13}$, and register them in ^{tt14}$. For example, if you want to add a new package to your project, do

  > cd src/
  > cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git
    or
  > paster create <new_package_name>
  

  Then add ^{tt50}$ to version control and add the directory ^{tt50}$ to the ^{tt52}$ list in ^{tt14}$. Also, if necessary, add ^{tt54}$ to the ^{tt55}$ part of ^{tt14}$ and mention it in the ^{tt57}$ configuration section of ^{tt58}$.

参考文献

• PyPI Page: http://pypi.python.org/pypi/python_boilerplate_template
• Github: https://github.com/konstantint/python-boilerplate-template
• Cookiecutter version: https://github.com/konstantint/cookiecutter-python-boilerplate
• Blog post: http://fouryears.eu/2014/03/19/structure-of-a-python-project/

• Useful reading

  • http://www.jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/

• Related projects: [1], [2], [3].

版权和许可证

版权所有（C）2014，Konstantin Tretyakov。麻省理工学院执照。