I would like some advice on packaging this as an egg and uploading it to pypi
I wrote some code that I would like to package like an egg. This is my directory structure:
src / src / tests src / tests / test.py # this has several tests for the movie name parser src / torrent src / torrent / __ init__.py src / torrent / movienameparser src / torrent / movienameparser / __ init__.py # this contains the code
I would like to package this directory structure as an egg and include a test file as well. What should I include in the file setup.py
so that I can have any number of namespaces and any number of tests?
This is the first open source I would like to share. While I will probably be the only one who finds this module useful, I would like to upload it to pypi
. What license can I use that will allow users to do what they want with the code, no restrictions on redistribution, modifications?
Even though I am planning on updating this egg, I would like to not be in charge of anything (like providing support to users). I know this may sound selfish, but this is my first open source, so please bear with me. Do I need to provide a copy of the license? Where can I find a copy?
Thank you for reading all of this.
source to share
I will not discuss the license here, but it is typical to include the LICENSE file in the root of your package source, as well as other common things like READMEs, etc.
I usually organize packages the same way they will be installed on the target system. The standard packaging convention is explained here.
For example, if my package is "torrent" and it has a couple of subpackages like "tests" and "utility", here the source tree would look like this:
workspace / torrent / setup.py workspace / torrent / torrent / __ init__.py workspace / torrent / torrent / foo.py workspace / torrent / torrent / bar.py workspace / torrent / torrent / ... workspace / torrent / torrent / tests / __ init__.py workspace / torrent / torrent / tests / test.py workspace / torrent / torrent / tests / ... workspace / torrent / torrent / util / __ init__.py workspace / torrent / torrent / util / helper1.py workspace / torrent / torrent / util / ...
This "torrent / torrent" bit seems like overkill, but it's a side effect of this standard convention and how Python imports work.
Here's a very minimalist one setup.py
(more on how to write a custom script ):
#!/usr/bin/env python
from distutils.core import setup
setup(name='torrent',
version='0.1',
description='would be nice',
packages=['torrent', 'torrent.tests', 'torrent.util']
)
To get the source distribution, I would do:
$ cd workspace / torrent $ ./setup.py sdist
This distribution ( dist/torrent-0.1.tar.gz
) will be useful on its own by simply unpacking it and running it setup.py install
or using it easy_install
from the setuptools
toolbox. And you don't have to make a few eggs for every supported Python version.
If you really want an egg, you need to add a dependency setuptools
to yours setup.py
, which will add an extra subcommand bdist_egg
that generates eggs.
But there is another benefit setuptools
beyond its egg-making quality, it removes the need to list the packages in yours setup.py
with a helper function find_packages
:
#!/usr/bin/env python
from setuptools import setup, find_packages
setup(name='torrent',
version='0.1',
description='would be nice',
packages=find_packages()
)
Then, to get the "egg", I'll do:
$ cd workspace $ ./setup.py bdist_egg
... and it will give me the egg file: dist/torrent-0.1-py2.6.egg
Note the suffix py2.6
, this is because I have Python 2.6 on my machine. If you want to please a lot of people, you will need to post an egg for every major Python version. You don't need hordes of Python 2.5 with axes and spears at your doorstep, do you?
But you don't need to build the egg, you can still use the subcommand sdist
.
Updated: Here's another helpful page in the Python documentation that introduces Distutils
from a user perspective.
source to share
It would be better to distribute it as a tarball ( .tar.gz
) rather than an egg. Eggs are mostly intended for binary distribution, such as when using compiled C extensions. On source-only distributions, this is just unnecessary complexity.
If you just want to throw your code out into the world, the most popular option is the MIT BSD or 3-clause licenses. Both include disclaimers. All you have to do is include the base license in the tarball; usually as "License.txt" or similar. Optionally, you can add a small copyright notice to each source file; I recommend this, so the status of each file is obvious even without the entire archive, but some people find it too verbose. This is a matter of personal preference.
BSD license is available on Wikipdia copied below:
Copyright (c) <year>, <copyright holder>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the <organization> nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY <copyright holder> ''AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <copyright holder> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
source to share
Include the ez_setup file from the setuptools site and include at the top of the setup.py page:
from ez_setup import use_setuptools
use_setuptools()
This script is a helper for people who don't have setuptools. It downloads and installs the latest setuptools on a system that does not have setuptools installed.
source to share