Re: [Distutils] tests location: Use case: new comers and docs.

[Erik Bray]

On Wed, Oct 7, 2015 at 2:11 AM, Chris Barker  wrote:
> On Tue, Oct 6, 2015 at 10:38 PM, Thomas Güttler
>  wrote:
>>
>> Yes, there is not generic "one right way here".
>>
>> Yes, let's consider individual use cases.
>>
>> My use case are the docs for new comers:
>>
>>  - https://github.com/pypa/sampleproject
>>  - https://packaging.python.org/en/latest/distributing/
>>
>> That's why started the thread.
>
>
> unfortunately, that isn't  a use-case -- every newcomer has a different use
> case.

Indeed--I've helped newcomers whose very first attempt at packaging
Python code includes Cython code for simulations.  I think even for
newcomers what we should be providing is not a "this is the way to do
it" because then they get confused when that way doesn't work for
them.

Better, in the long term (and I'm happy to contribute to such an
effort if it will help) is to provide a sort of Choose Your Own
Adventure story.  It can't all go on one page because that would be a
mess, but a sort of "If you need to do this, read this.  If you need
to do this, read this.  Now if you need to include some data files
that are installed in your package read on, because there's really
only one right way to do that.  But now you have some options if you
want to include tests: ..."

> I was happy to see this thread, because I thought maybe I"d learn what i
> should teach my students - new to python.
>
> But alas - there clearly really is no consensus.
>
> What i've told newbies in the past is somethig like:
>
> """
> if you want your user to be able to install you package, and then run
> something like:
>
> import my_package
> my_package.test()
>
> then put your tests inside the package.
>
> If you are fine with only being able to run the tests from the source tree
> -- then put your tests outside the package.
> """
>
> but really, newbies have no idea how to make this decsion.
>
> Maybe we could come up with a decision tree for this -- some guidance for
> knowing what to do, when?

Exactly.  I think it could even be fun :)

How could we get started to add something like this to the packaging docs?

Erik
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] tests location: Use case: new comers and docs.

[Chris Barker]

On Tue, Oct 6, 2015 at 10:38 PM, Thomas Güttler <
guettl...@thomas-guettler.de> wrote:

> Yes, there is not generic "one right way here".
>
> Yes, let's consider individual use cases.
>
> My use case are the docs for new comers:
>
>  - https://github.com/pypa/sampleproject
>  - https://packaging.python.org/en/latest/distributing/
>
> That's why started the thread.
>

unfortunately, that isn't  a use-case -- every newcomer has a different use
case.

I was happy to see this thread, because I thought maybe I"d learn what i
should teach my students - new to python.

But alas - there clearly really is no consensus.

What i've told newbies in the past is somethig like:

"""
if you want your user to be able to install you package, and then run
something like:

import my_package
my_package.test()

then put your tests inside the package.

If you are fine with only being able to run the tests from the source tree
-- then put your tests outside the package.
"""

but really, newbies have no idea how to make this decsion.

Maybe we could come up with a decision tree for this -- some guidance for
knowing what to do, when?

-Chris

-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR(206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115   (206) 526-6317   main reception

chris.bar...@noaa.gov
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] tests location: Use case: new comers and docs.

[Thomas Güttler]

Am 06.10.2015 um 17:33 schrieb Erik Bray:
> On Tue, Oct 6, 2015 at 8:34 AM, Ionel Cristian Mărieș
>  wrote:
>> On Tue, Oct 6, 2015 at 3:13 PM, Antoine Pitrou  wrote:
>>>
>>> On Tue, 6 Oct 2015 07:07:31 -0400
>>> Donald Stufft  wrote:

 I've never, in my entire life [...]
>>>
>>> Can I suggest your entire life is an anecdotal data point here?
>>
>>
>> Make that two anecdotal data points :-)
>>
>>> Any number of things can be described as trivial depending on the
>>> skillset and patience of the user.  When users report a bug, they are
>>> not expecting to be asked to download and "untar" stuff.  Not every
>>> user is a programmer.
>>
>> But seriously now, your arguments are also anecdotal. Lets not pretend we're
>> objective here. That sort of attitude is disingenuous and will quickly
>> devolve this discussion to mere ad hominems.
> 
> Okay, though, so maybe if there is nothing to offer here but anecdata
> then maybe we should stop acting like there's "one right way here".  I
> have projects that install their test suite and test dependencies
> because it is frequently useful to ask users to run a self-test (and
> users themselves want to be able to do it for a variety of reasons).
> 
> There are other projects where it doesn't make sense, and those don't
> have to install the tests (I still think in those cases that the tests
> should live in the package instead of outside it, but simply not
> installed).
> 
> In any case, let's not get trapped into endless circular discussions
> about what is correct, period, and instead consider individual use
> cases--not dismissing individual projects' or peoples' experiences and
> needs--and discuss what the most appropriate action is for those uses
> cases.  Python projects are not monolithic in their audiences (and
> that includes developer audiences and user audiences).


Yes, there is not generic "one right way here".

Yes, let's consider individual use cases.

My use case are the docs for new comers:

 - https://github.com/pypa/sampleproject
 - https://packaging.python.org/en/latest/distributing/

That's why started the thread.

New comers don't have the experience you have. New comers
want to get their coding done. They need a simple
advice: "If unsure, then do X"

And for this question, I want a "one right way here".

Up to now it looks like there is no consensus. 

Regards,
  Thomas Güttler

-- 
http://www.thomas-guettler.de/
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig