-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document contributors convention to respect skeleton and distutils #4609
Conversation
I have two questions. If these are implementation details, should the module be named |
Yes, I think they could be moved to Probably |
Thanks for doing this!
I find the Presumably to address this concern, I've seen other projects put everything under a separate, top-level package (e.g. pytest [although even there, they have private packages below]) or move everything private into an underscore-prefixed private package (e.g. pip). I've resisted these approaches because they add extra indirection and top-level names. I'd much rather be able to name modules with a clean, natural form and flag visibility using some orthogonal signal. Since the language doesn't provide a good orthogonal signal, I'm fine with documenting the expectation. I do think downstream consumers should have an instinct to avoid using functionality from a package that's not part of the advertised interface. That is, I don't think users would be particularly tempted to use these modules. In cases where the functionality might be valuable across more than a couple of projects, I've worked to expose those under jaraco.compat.
In my opinion, yes. In fact, it might be worthwhile refactoring those imports into py39 and py310 modules, but it'd be fine to call it I also use this namespace for things unrelated to the Python version, such as keyring.compat.properties or zipp.compat.overlay. In the case of
Yes, it would be okay, but then it will deviate from the convention I've followed in most other projects. IMO, it'd be better to keep it consistent across projects.
Thinking about this concept in general, I apply it across many projects, so it feels a little weird to document it here. It will be a little unsustainable to copy this documentation to each and every project that employs this approach. Better would be to have a blog entry or (even better) have documentation in a shared system (like skeleton or coherent) that can possibly be linked from Setuptools if needed. What do you think about contributing this guidance instead to a "conventions" section in https://github.com/jaraco/skeleton/blob/gh-pages/index.md? |
The only reason I haven't added shims for |
Thank you very much for the feedback @jaraco, I have extracted the "compat" docs into jaraco/skeleton#145. I have also repurposed this PR to talk about how setuptools uses skeleton and that |
Summary of changes
I created these paragraphs based on the comment in #4212. The idea is to document to setuptools developers how the
compat/pyXX
convention works.Closes
Pull Request Checklist
newsfragments/
.(See documentation for details)