FAQ
I'm writing an introduction to releasing open-source Python projects.
Having recently gone through it for the first time myself, I was
amazed at how far and wide I had to range to pull together all the
information that goes into making a good Python package.? So I thought
I'd write it up and share:

http://infinitemonkeycorps.net/docs/pph/

It's tentatively called the "Python Project Howto," and it's aimed at
people who, though not necessarily new to Python, may be new to
packaging and possibly open source. It tries to be succinct and
practical, demonstrating by example.? It covers choosing project
hosting, setting up version control (Subversion basics), code quality
(Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx),
unit testing (doctest and unittest), licensing, packaging (distutils),
and release (PyPI).

One thing I don't want it to be is an exhaustive list of all the
possibilities for each of those areas.? For instance, I cover
reStructuredText and Sphinx, but not epydoc; distutils but not
setuptools. I've tried to pick the simplest, most common among
several options, and sometimes provided a link to others (pip, nose).
I'm trying to Keep It Simple for people just dipping their toes into
the Python ecosystem.? I'd really like to know what people think; it
would be great to get some feedback on it. Thanks!

-John

Search Discussions

  • Michael Foord at Sep 30, 2009 at 1:43 pm

    John Kleint wrote:
    I'm writing an introduction to releasing open-source Python projects.
    Having recently gone through it for the first time myself, I was
    amazed at how far and wide I had to range to pull together all the
    information that goes into making a good Python package. So I thought
    I'd write it up and share:

    http://infinitemonkeycorps.net/docs/pph/
    Just skimmed it so far (up to choosing a version control system). *Very*
    nice. Once it is complete you should talk to Andrew Kuchling about
    making it an official Python-HOWTO.

    You say you don't cover setuptools, but you do use easy_install...

    Once the work Tarek Ziade is doing is more complete, both on distutils
    and Distribute (setuptools replacement), it would be great to see the
    HOWTO updated to cover them.

    Anyway, I'll keep reading and come back with any more comments if I have
    any.

    All the best,

    Michael
    It's tentatively called the "Python Project Howto," and it's aimed at
    people who, though not necessarily new to Python, may be new to
    packaging and possibly open source. It tries to be succinct and
    practical, demonstrating by example. It covers choosing project
    hosting, setting up version control (Subversion basics), code quality
    (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx),
    unit testing (doctest and unittest), licensing, packaging (distutils),
    and release (PyPI).

    One thing I don't want it to be is an exhaustive list of all the
    possibilities for each of those areas. For instance, I cover
    reStructuredText and Sphinx, but not epydoc; distutils but not
    setuptools. I've tried to pick the simplest, most common among
    several options, and sometimes provided a link to others (pip, nose).
    I'm trying to Keep It Simple for people just dipping their toes into
    the Python ecosystem. I'd really like to know what people think; it
    would be great to get some feedback on it. Thanks!

    -John
    _______________________________________________
    Doc-SIG maillist - Doc-SIG at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/
  • Michael Foord at Sep 30, 2009 at 1:49 pm

    John Kleint wrote:
    I'm writing an introduction to releasing open-source Python projects.
    Having recently gone through it for the first time myself, I was
    amazed at how far and wide I had to range to pull together all the
    information that goes into making a good Python package. So I thought
    I'd write it up and share:

    http://infinitemonkeycorps.net/docs/pph/
    Maybe move licensing to be nearer choosing a project host. You often
    have to have already chosen a license when you choose a host, so putting
    them together makes sense.

    Mention Pyflakes and Pychecker when you mention Pylint? Pylint is very
    powerful, but a real pain to configure.

    In testing resources you should link to the Python Testing Tools
    Taxonomy: http://pycheesecake.org/wiki/PythonTestingToolsTaxonomy

    Nothing more so far. :-)

    All the best,

    Michael


    It's tentatively called the "Python Project Howto," and it's aimed at
    people who, though not necessarily new to Python, may be new to
    packaging and possibly open source. It tries to be succinct and
    practical, demonstrating by example. It covers choosing project
    hosting, setting up version control (Subversion basics), code quality
    (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx),
    unit testing (doctest and unittest), licensing, packaging (distutils),
    and release (PyPI).

    One thing I don't want it to be is an exhaustive list of all the
    possibilities for each of those areas. For instance, I cover
    reStructuredText and Sphinx, but not epydoc; distutils but not
    setuptools. I've tried to pick the simplest, most common among
    several options, and sometimes provided a link to others (pip, nose).
    I'm trying to Keep It Simple for people just dipping their toes into
    the Python ecosystem. I'd really like to know what people think; it
    would be great to get some feedback on it. Thanks!

    -John
    _______________________________________________
    Doc-SIG maillist - Doc-SIG at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

    --
    http://www.ironpythoninaction.com/
  • Paul Moore at Sep 30, 2009 at 3:42 pm

    2009/9/25 John Kleint <jkleint at gmail.com>:
    I'm writing an introduction to releasing open-source Python projects.
    Having recently gone through it for the first time myself, I was
    amazed at how far and wide I had to range to pull together all the
    information that goes into making a good Python package.? So I thought
    I'd write it up and share:

    http://infinitemonkeycorps.net/docs/pph/

    It's tentatively called the "Python Project Howto," and it's aimed at
    people who, though not necessarily new to Python, may be new to
    packaging and possibly open source. ?It tries to be succinct and
    practical, demonstrating by example.? It covers choosing project
    hosting, setting up version control (Subversion basics), code quality
    (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx),
    unit testing (doctest and unittest), licensing, packaging (distutils),
    and release (PyPI).

    One thing I don't want it to be is an exhaustive list of all the
    possibilities for each of those areas.? For instance, I cover
    reStructuredText and Sphinx, but not epydoc; distutils but not
    setuptools. ?I've tried to pick the simplest, most common among
    several options, and sometimes provided a link to others (pip, nose).
    I'm trying to Keep It Simple for people just dipping their toes into
    the Python ecosystem.? I'd really like to know what people think; it
    would be great to get some feedback on it. ?Thanks!
    Please, when describing how to build the uploadable packages, as well
    as setup.py sdist, add in a recommendation to build and upload
    setup.py bdist_wininst.

    Not all users (want to) use easy_install, and for those on Windows who
    don't, the provision of a Windows installer is a very useful
    convenience. It's not difficult, for pure Python packages (AFAIK,
    bdist_wininst is platform independent). If you're packaging up a C
    extension, you want to make sure it builds on Windows in any case, of
    course (:-)) so building an installer is no extra burden, and hugely
    helps your Windows users.

    I've fairly often not bothered trying out packages just because they
    don't provide a windows installer. Call me lazy, but even so... :-)

    Paul.
  • John Kleint at Oct 1, 2009 at 4:19 am
    Thanks for the feedback. I've incorporated your suggestions.
    You say you don't cover setuptools, but you do use easy_install...
    Once the work Tarek Ziade is doing is more complete, both on distutils
    and Distribute (setuptools replacement), it would be great to see the
    HOWTO updated to cover them.
    Yeah; at the moment, easy_install seems to be the most common way to
    get Python packages, and distutils seems to be the simplest, most
    common way to create them. From what I gather the Python packaging
    landscape is in flux, but when there's a good replacement for
    distutils and easy_install, I'll be happy to include it.
    Maybe move licensing to be nearer choosing a project host.
    You often have to have already chosen a license when you choose
    a host, so putting them together makes sense.
    I added a pointer to the license section at the beginning, but
    licensing can be a bit daunting and I don't want to scare anybody off
    too soon. :)
    Mention Pyflakes and Pychecker when you mention Pylint? Check.
    In testing resources you should link to the Python Testing Tools Taxonomy:
    http://pycheesecake.org/wiki/PythonTestingToolsTaxonomy
    Wow - I had no idea there were so many testing tools for Python.
    Please, when describing how to build the uploadable packages, as well
    as setup.py sdist, add in a recommendation to build and upload
    setup.py bdist_wininst.
    Thanks, I didn't know it was a pain for Windows users. I'm going to
    go make Windows installers for my own packages.

    -John

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedSep 24, '09 at 11:15p
activeOct 1, '09 at 4:19a
posts5
users3
websitepython.org

People

Translate

site design / logo © 2019 Grokbase