Request for Eyeballs: Python Project Howto

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Request for Eyeballs: Python Project Howto

John Kleint
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Request for Eyeballs: Python Project Howto

Michael Foord-5
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  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>  


--
http://www.ironpythoninaction.com/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Request for Eyeballs: Python Project Howto

Michael Foord-5
In reply to this post by John Kleint
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  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>  


--
http://www.ironpythoninaction.com/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Request for Eyeballs: Python Project Howto

Paul Moore
In reply to this post by John Kleint
2009/9/25 John Kleint <[hidden email]>:

> 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.
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Request for Eyeballs: Python Project Howto

John Kleint
In reply to this post by John Kleint
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig