一个简单的Hello World setuptools软件包，并使用pip进行安装 [英] A simple Hello World setuptools package and installing it with pip

问题描述

我在弄清楚如何使用setuptools安装软件包时遇到了麻烦，并且我尝试阅读有关它和SO帖子的文档，但是我无法使其正常工作.我正在尝试使用一个简单的helloworld应用程序.这是我走了多远:

I'm having trouble figuring out how to install my package using setuptools, and I've tried reading the documentation on it and SO posts, but I can't get it to work properly. I'm trying to get a simple helloworld application to work. This is how far I got:

helloworld.py:

helloworld.py:

print("Hello, World!")

README.txt:

README.txt:

Hello, World! readme

MANIFEST.in:

MANIFEST.in:

recursive-include images *.gif

setup.py:

from setuptools import setup, find_packages

setup(
    name='helloworld',
    version='0.1',
    license='BSD',
    author='gyeh',
    author_email='[e-mail]',
    url='http://www.hello.com',
    long_description="README.txt",
    packages=find_packages(),
    scripts = ['helloworld.py'],
    package_data={
        "" : ["images/*.gif"]
    },
    data_files=[('images', ['images/hello.gif'])],
    description="Hello World testing setuptools",
)

我有一个名为images/hello.gif的空白文件，希望将其作为附加数据包含在包装中.文件夹结构如下:

And I have a blank file called images/hello.gif that I want to include in my package as additional data. The folder structure looks like this:

testsetup/  
|-- helloworld.py  
|-- images/  
|-- --- hello.gif  
|-- MANIFEST.in  
|-- README.txt  
|-- setup.py  

当我运行python setup.py sdist时，它将成功生成dist和helloworld.egg-info.当我查看egg-info下的SOURCES.txt时，它包含脚本和图像文件夹下的图像，而dist下的tarball也包含它们.

When I run python setup.py sdist, it generates the dist and helloworld.egg-info successfully. When I look at SOURCES.txt under egg-info, it contains the script and the image under the images folder, and the tarball under dist contains them as well.

但是，当我尝试在tarball上运行pip install --user helloworld-0.1.tar.gz时，它成功安装了它，但是找不到程序文件helloworld.py和images/hello.gif.

However, when I try to run pip install --user helloworld-0.1.tar.gz on the tarball, it successfully installs it, but I can't find the program files helloworld.py and images/hello.gif.

当我在$HOME/.local/lib/python3.3/site-packages/下查看时，我看到egg-info文件夹及其所有内容都安装在该文件夹中.但是$HOME/.local/bin文件夹甚至不存在.程序文件是否存储在其他位置?我在这里做错了什么?我正在运行Arch Linux.

When I look under $HOME/.local/lib/python3.3/site-packages/, I see the egg-info folder and all of it's contents installed there. But the $HOME/.local/bin folder doesn't even exist. Are the program files stores elsewhere? What am I doing wrong here? I'm running Arch Linux.

推荐答案

好的，因此，经过一番努力，我终于设法得到一个简单的"hello world" 示例，该示例适用于setuptools. Python文档通常是很棒的，但是我希望该文档在这方面能做得更好.

Okay, so after some effort, I finally managed to get a simple "hello world" example working for setuptools. The Python documentation is usually amazing, but I wish the documentation was better on this in particular.

我将撰写有关如何实现此目标的相当详细的指南，并且我不会假设读者之前对该主题有任何背景知识.我希望这对其他人有帮助...

I'm going to write a fairly detailed guide on how I achieved this, and I'll assume no prior background on the reader on this topic. I hope this comes in handy for others...

为了设置此示例，我们将创建一个包(实际上是两个，其中一个用于数据文件).这是我们最终要使用的目录结构:

In order to get this example set up, we'll be creating a package (actually two of them, one for the data files). This is the directory structure we'll end up with:

test-setuptools/
|-- helloworld/
|-- --- hello.py
|-- --- images/
|-- --- --- hello.gif
|-- --- --- __init__.py
|-- --- __init__.py
|-- MANIFEST.in
|-- README.txt
|-- setup.py

以下是步骤:

1. 创建helloworld包.
   1.1如上面的目录结构所示，创建helloworld/文件夹.

1. Create the helloworld package.
   1.1 Create the helloworld/ folder as shown in the directory structure above.

1.2在helloworld/文件夹中添加一个名为__init__.py的空白文件.
如果不添加它，则该包将不会被识别(运行touch __init__.py在linux/mac机器上创建文件).如果您希望每次导入软件包时都执行一些代码，请将其包含在__init__.py文件中.

1.2 Add a blank file called __init__.py in the helloworld/ folder.
If you don't add it, the package won't be recognized (run touch __init__.py to create the file on linux/mac machines). If you want some code to be executed every time the package is imported, include it in the __init__.py file.

1.3创建hello.py脚本文件以演示程序包的功能.

1.3 Create the the hello.py script file to demonstrate the package functionality.

这是hello.py的代码:

import os

"""
Open additional data files using the absolute path,
otherwise it doesn't always find the file.
"""
# The absolute path of the directoy for this file:
_ROOT = os.path.abspath(os.path.dirname(__file__))

class Hello(object):
    def say_hello(self):
        return "Hello, World!"
    def open_image(self):
        print("Reading image.gif contents:")

        # Get the absolute path of the image's relative path:
        absolute_image_path = os.path.join(_ROOT, 'images/hello.gif')

        with open(absolute_image_path, "r") as f:
            for line in f:
                print(line)

1. 1.4在helloworld/文件夹内创建images/文件夹.
   制作另一个空白的__init__.py文件，因为该文件夹也将是一个程序包.

1. 1.4 Create the images/ folder inside the helloworld/ folder.
   Make another blank __init__.py file, because this folder will also be a package.

1.5在images/文件夹中创建hello.gif文件.
该文件将不是实际的gif文件.而是添加纯文本，只是为了演示可以添加和读取非脚本文件.

1.5 Create the hello.gif file inside the images/ folder.
This file won't be an actual gif file. Instead, add plain text just to demonstrate that non-script files can be added and read.

我在hello.gif中添加了以下代码:

I added the following code in hello.gif:

This should be the data inside hello.gif...
...but this is just to demonstrate setuptools,
so it's a dummy gif containing plain text

1. 1.6测试您的包裹
   从test-setuptools文件夹运行python，这将打开python解释器.
   键入import helloworld.hello以将hello.py脚本导入helloworld包中.导入应该成功，表明您已经成功创建了一个程序包.通过键入import helloworld.images
   ，确保images/文件夹中的程序包也能正常工作 尝试实例化在hello.py中编写的对象.键入以下命令以确保一切正常:
   hey = helloworld.hello.Hello()
hey.say_hello()
hey.open_image()

1. 1.6 Test your package
   Run python from the test-setuptools folder, which will open the python interpreter.
   Type import helloworld.hello to import the hello.py script in the helloworld package. The import should be successful, indicating that you successfully created a package. Make sure that the package in the images/ folder also works, by typing import helloworld.images
   Try instantiating the object that we wrote in hello.py. Type the following commands to make sure everything works as expected:
   hey = helloworld.hello.Hello()
hey.say_hello()
hey.open_image()

创建setup.py文件和其余文件.
2.1创建一个简单的README.txt文件.我的只是里面有文字:Hello, World! Readme.

Create the setup.py file and the remaining files.
2.1 Create a simple README.txt file. Mine just has the text: Hello, World! Readme inside.

2.2创建具有以下内容的MANIFEST.in文件:
include helloworld/images/hello.gif
.
这非常重要，因为它告诉setuptools将其他数据包括在源分发中(我们将在后续步骤中生成).否则，您将无法在软件包中安装其他非.py数据.有关其他详细信息和命令，请参见此.

2.2 Create a MANIFEST.in file with the following contents:
include helloworld/images/hello.gif
.
This is very important because it tells setuptools to include the additional data in the source distribution (which we'll generate in a later step). Without this, you won't be able to install additional, non .py data to your package. See this for additional details and commands.

2.3创建setup.py文件(请参见下面的代码).
最重要的属性是packages，include_package_data和package_data.
.
packages属性包含要包含在setuptools中的软件包的列表.我们要同时包含helloworld软件包和helloworld.images软件包，其中包含我们的其他数据hello.gif.
您可以通过添加from setuptools import find_packages导入并运行导入的find_packages()函数，使setuptools自动找到它们.从test-setuptools文件夹运行解释器，并测试此命令以查看找到了哪些软件包.
.
package_data属性告诉setuptools包含其他数据.这是命令，helloworld.images程序包和MANIFEST.in文件，它们允许您安装其他数据.
'helloworld.images' : ['hello.gif']键/值对告诉setuptools将hello.gif包含在helloworld.images程序包中(如果存在).您还可以说'' : ['*.gif']在任何包含的软件包中包括任何.gif文件.
设置为True的include_package_data属性对于此功能也是必需的.
您可以像我一样为该程序包添加其他元数据(我认为必须author).添加分类器是一个好主意.可以在此处找到其他信息.

2.3 Create the setup.py file (see the code below).
The most important attributes are packages, include_package_data, and package_data.
.
The packages attribute contains a list of the packages you want to include for setuptools. We want to include both the helloworld package and the helloworld.images package that contains our additional data hello.gif.
You can make setuptools automatically find these by adding the from setuptools import find_packages import and running the imported find_packages() function. Run the interpreter from the test-setuptools folder and test this command to see which packages are found.
.
The package_data attribute tells setuptools to include additional data. It's this command, the helloworld.images package, and the MANIFEST.in file which allow you to install additional data.
The 'helloworld.images' : ['hello.gif'] key/value pair tells setuptools to include hello.gif inside the helloworld.images package if it exists. You can also say '' : ['*.gif'] to include any .gif file in any of the included packages.
The include_package_data attribute set to True is also necessary for this to work.
You can include additional metadata for the package like I have (I think an author is necessary). It's a good idea to add classifiers. Additional info can be found here.

这是完整的setup.py代码:

from setuptools import setup

setup(
    name='helloworld',
    version='0.1',
    license='BSD',
    author='gyeh',
    author_email='[e-mail]',
    url='http://www.hello.com',
    long_description="README.txt",
    packages=['helloworld', 'helloworld.images'],
    include_package_data=True,
    package_data={'helloworld.images' : ['hello.gif']},
    description="Hello World testing setuptools",
)

.
3.使用setuptools安装并测试您的软件包.

.
3. Install and test your package with setuptools.

3.1 Create the source distribution  

从test-setuptools/文件夹运行python setup.py sdist以生成源分发.
这将创建一个包含您的软件包的dist/文件夹，以及一个包含诸如SOURCE.txt之类的元数据的helloworld.egg-info/文件夹. 检查SOURCE.txt以查看是否包含hello.gif图像文件.
打开dist/文件夹下的.tar.gz文件.您应该看到我们之前制作的目录结构中描述的所有文件，包括hello.gif和hello.py.

Run python setup.py sdist from the test-setuptools/ folder to generate the source distribution.
This will create a dist/ folder containing your package, and a helloworld.egg-info/ folder containing metadata such as SOURCE.txt.
Check SOURCE.txt to see if your the hello.gif image file is included there.
Open the .tar.gz file under the dist/ folder. You should see all of the files described in the directory structure we made earlier, including hello.gif and hello.py.

3.2 Install the distribution  

通过运行dist/文件夹中的pip install --user helloworld-0.1.tar.gz安装.tar.gz分发文件.
通过运行pip list检查软件包是否已成功安装.软件包helloworld应该在这里.

Install the .tar.gz distribution file by running pip install --user helloworld-0.1.tar.gz from the dist/ folder.
Check that the package was successfully installed by running pip list. The package helloworld should be there.

就是这样！现在，您应该可以在任何文件夹下测试软件包了.在test-setuptools以外的任何文件夹中打开解释器，然后尝试使用import helloworld.hello导入软件包.它应该工作.然后尝试使用命令实例化对象，并再次使用hey.open_image()命令打开图像文件.它仍然应该工作！

That's it! now you should be able to test your package under any folder. Open up the interpreter in any folder except test-setuptools, and try importing the package using import helloworld.hello. It should work. Then try the commands to instantiate the object and open the image file using the hey.open_image() command again. It should still work!

通过卸载软件包，您可以准确查看pip安装了哪些文件，以及安装的位置. 我的样子是这样的:

You can view exactly which files were installed by pip, and where they are, by uninstalling the package. Mine looked like this:

[gyeh@gyeh package]$ pip uninstall helloworld
Uninstalling helloworld:
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld-0.1-py3.3.egg-info
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/__init__.py
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/__pycache__/__init__.cpython-33.pyc
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/__pycache__/hello.cpython-33.pyc
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/hello.py
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/images/__init__.py
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/images/__pycache__/__init__.cpython-33.pyc
  /home/gyeh/.local/lib/python3.3/site-packages/helloworld/images/hello.gif
Proceed (y/n)? y
  Successfully uninstalled helloworld

如您所见，它成功安装了附加数据文件hello.gif，并且由于我们将相对路径转换为hello.py中的绝对路径，因此它可以很好地读取文件.
然后，您可以在PyPI上共享此软件包，以供世界其他地方使用！有关上传到PyPI的说明非常简单，可以在此处和

As you can see, it successfully installed the additional data file hello.gif, and because we converted the relative path to an absolute path in hello.py, it can read the file just fine.
You can then share this package on PyPI for the rest of the world to use! The instructions on uploading to PyPI are fairly straightforward and can be found here and here.

一旦它在PyPI中在线，人们就可以使用pip search搜索您的软件包.或者，运行pip install --user [package-name]将告诉pip在在线PyPI目录中搜索该软件包名称.如果存在，它将安装它.

Once it's online in PyPI, people can search for your package using pip search. Or alternatively, running pip install --user [package-name] will tell pip to search the online PyPI directory for that package name. If it exists, it will install it.

您可以为PyPI中的任何python软件包运行该命令，以方便安装，因此您不会在构建文件中乱码.

You can run that command for any python package that in PyPI for an easy install so you aren't mucking around with build files.

我希望这可以使人们免于头疼.

I hope this saves people a bunch of headaches.

这篇关于一个简单的Hello World setuptools软件包，并使用pip进行安装的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！