Stance (or discussion) on src/ directory

[ctheune]

Is there an official stance on the "src/" directory thing? I'm all for it (and @hynek seems to agree) but I haven't found any discussion or explanation about it from the PyPA. The guide doesn't mention it and the sample project doesn't use it. Even if the stance is "don't use it" (which I would disagree with) then I'd love to see this discussed in the official guide so we can refer to it when people need to make up their mind or argue it.

[ctheune]

Some references on the discussion that support the "pro" argument:

• https://hynek.me/articles/testing-packaging/
• https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure

[pfmoore]

I don't think there's a consensus on the best practice, and the packaging guide isn't really intended to cover general development practices, which this is. There's no discussion on testing or documentation, for similar reasons.

[theacodes]

Based on the doc plan in #317, this is actually a good candidate for a discussion topic. I would be willing to accept a PR to add this topic.

[pfmoore]

Nice, @jonparrott - I hadn't seen that doc plan. Agreed this would make a good discussion topic. Another one I've seen come up in the past is whether to put tests in the package or in a separate test directory.

[theacodes]

@pfmoore for sure, I'd be happy to have that topic as well.

[theacodes]

@ctheune if you or @hynek are interested in contributing this topic, I would love to review and merge it. :)

[pfmoore]

I'd also be interested in reviewing this. I tried a layout using src just recently and found there were some things that were fiddly to get right (coverage was one), so I have a test case I could use to see how the recommendations work in practice :-)

[hynek]

Have you seen https://hynek.me/articles/testing-packaging/ Paul? I hoped to de-fiddle the process there...

[pfmoore]

@hynek Yes I have. The problem I had was not with combining coverage, but with the basic coverage output from a single tox environment. It's possible it was just lack of familiarity with running coverage under tox, but from what I recall the output had some rather badly nested directories, when I was after filenames relative to src (so mypkg/__init__.py). I backed out the implementation of coverage, so I don't have it to hand at the moment, but could reimplement it if needed.

[ctheune]

Thanks for picking up that topic - happy to contribute although I can't promise to be very responsive at times (busy company and small child make my FLOSS contributions a bit spotty at the moment).

I haven't run into the coverage issue before - I usually have both a tox and non-tox pytest setup and ensure my coverage is right in the basic setup. I see the need for checking coverage of Python--version-specific code paths, though.

What's the next step for contributing here?

[theacodes]

Distill the source content into a discussion topic and send a pull request. Or, if you prefer you can author it in Google docs and I can review and place it here once it's finalized. Happy to help give you guidance on any step.

…

On Tue, Jun 27, 2017, 11:07 PM Christian Theune ***@***.***> wrote: Thanks for picking up that topic - happy to contribute although I can't promise to be very responsive at times (busy company and small child make my FLOSS contributions a bit spotty at the moment). I haven't run into the coverage issue before - I usually have both a tox and non-tox pytest setup and ensure my coverage is right in the basic setup. I see the need for checking coverage of Python--version-specific code paths, though. What's the next step for contributing here? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#320 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc6Er5_1ZDv6GnMBokdAjWC5M7Ed9ks5sIe2igaJpZM4Nyan8> .

[pradyunsg]

Is anyone working on this right now?

[theacodes]

Nope.

…

On Fri, Aug 25, 2017, 12:11 AM Pradyun Gedam ***@***.***> wrote: Is anyone working on this right now? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#320 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc439KkMZ5j43eujlOvsPxjWR3LNHks5sbnOogaJpZM4Nyan8> .

[ofek]

I really, really dislike this structure. It makes things a bit more complicated than necessary imo. Newcomers should be considered here.

[hynek]

Beginners who are more likely to make mistakes in their packaging and that would hugely benefit from a more explicit setup that protects them against broken PyPI uploads and deployments? Yes I agree, they should be very much considered over personal preferences. :)

[ofek]

@hynek More explicit is worse for beginners when they could rather have a simple packages=find_packages() 🙂

[hynek]

I feel like we're moving into "explicit self is bad because you have to type more" territory. Passing a path to find_packages takes away a lot of mystery and perceived magic how it works and I'd argue you should pass it even if it's "." . And realistically people just copy paste it anyway so I'm having a hard time to see it as a problem at all. OTOH *reading* it later is helpful to understand what's going on without guessing.

[theacodes]

For beginners we'll likely have a new tutorial using flit as a starting point. Setuptools-style packaging would likely fall under guides, and a separate guide/discussion can be created around this topic.

[hynek]

I'm not sure whether pushing for flit is the right way as long as it precludes the usage of tox.

[theacodes]

I'm not sure whether pushing for flit is the right way as long as it precludes the usage of tox.

tox does a lot of weird stuff, but how does flit preclude using tox?

[hynek]

It may have changed (sadly I'm on a very bad Botswanan campsite wifi so I can't double check) but last time I checked tox needed a setup.py to work?

[theacodes]

I think you can turn that off or use a different install command (though the later affects deps as well).

I definitely plan to try out flit significantly before writing the experimental tutorial and gathering feedback before considering making the experimental tutorial official. So this is really useful.

Also, shameless plug that tox isn't the only option.

[obestwalter]

but last time I checked tox needed a setup.py to work

No.

[tox]
skipsdist = True

[...]

... and you're golden.

[obestwalter]

@jonparrott interesting - quite new project also - how come you thought nox is needed? What's missing from tox? I am always interested in seeing how we can improve tox and maybe join forces, if you like open an issue or write on the list.

[theacodes]

@obestwalter mostly just frustrated with using ini files. :)

[obestwalter]

That's what I thought :D - also see tox-dev/tox#600 - sorry for hijacking this - I am quiete now ...

[theacodes]

@obestwalter cool. :) I think there's room for both. If you ever want to chat about it feel free to reach out. :)

[pradyunsg]

This had fallen pretty low on my TODO list, but I finally got to filing the PR today: #1150