Skip to content

Home

Jump to bottom
Jason C. McDonald edited this page Feb 5, 2017 · 7 revisions

Article setup and discussion

Style

  • Discussion style where multiple options are discussed? Or rather uniform article explaining how to do things?

    Jason: Leaning towards the uniform article at the moment.

  • Who is the audience? Approachable introductory level?

    Jason: I agree with "Approachable introductory level," adding "but still approachable to experienced Pythonistas who want input on project structure.

  • Topic

    • Jason: I think the main topic I'm thinking of is "how to set up a Python project where everything just works?" Focus mainly on directory/file structure, and how to get everything seeing everything else, and then briefly cover how to "snap in" each piece.

  • Important is to decide about the content to cover before we decide on style.

    • Folder structure.

    • Touch on docs (README/LICENSE/Sphinx documentation).

    • Setting up for TDD (big part of the article).

    • Packaging (cxfreeze/py2exe/Debian packaging) - we should at least cover the most obvious case(s) in the demo, and touch on where to put the files in the article, since "packaging in Python is like beating yourself to death with a wet trout."

    • Other stuff???

      • Scripts

      • Native source code (where to put it?)

      • Makefile?

Topics

  • Pytest and/or Nose2?

    Dolf: I would prefer both, especially because people may wonder which way to go between them. We could help them decide which way they like best.

  • setup.py and packaging?

    Dolf: I would say yes. I don't know CXfreeze so would be interested to read about it.

  • CI?

    Dolf: One step too many IMHO. Definitely important but would take too much space I think

    Jason: I think anyone with any CI experience should be able to take the TDD setup and figure it out from there.

  • Library or application?

    Dolf: I would again say both because often the two are even combined. Both very common use cases

    Jason: Agreed, both.

  • Native code?

    Dolf: I usually don't use native code, so have no strong opinion either way. Definitely more complex, but probably also enlightening and something many people will struggle with.

    Jason: Probably just list where to put the native code, and how to get the Python project to find it. (Getting the native code to find the Python project is highly language-specific.)

    Will: I guess it's one thing to have a few C extensions, another thing to have a client and server in different languages (yet integration tested), and another to have a few subprojects be in different languages. The first one is easy enough to deal with, the second is glossed over in the tutorials for web frameworks but is easy enough to figure out, but the third is related to the 'how many packages' question, and tends to be poorly done.

  • How many packages from the project?

    Dolf: I usually keep my packages separate even if they're the same project. So different repos/packages/test/etc. A library I write on which my application for the same project depends, I still separate. I treat my library the same way I would treat any other library, so separate packaging, separate installation, etc. I list my library as a dependency/requirement in my application setup.py and make sure I install the library first (or host it online where pip can find it).

Jason: I agree, Dolf, although sometimes it helps to have two closely related packages in the same repo. Whatever system we come up with should work well enough that each package (and its tests, packaging data, etc.) can occupy one folder and just work. Probably good to touch on the pros/cons of separating each package into its own repo, though.

Will: You might want to release several packages out of one repo that you test as a whole, for example, a client/server with some common network code. If you notice a bug when running the client, you're not going to want to re-install the server and networking code (into your virtualenv) every time you make a change there before testing the client. In fact, you're probably not even going to commit a lot of those experiments. In that case, you'll either set PYTHONPATH (as I currently do...), or set up your project in a layout where this will work naturally. The consequence of the second part is you have to be a bit smarter with your setup.py. Anyway, we might get away with a footnote, or a follow-up article.

Jason: I think you just hit the nail on the head, Will. "Follow up article" may be our best bet on a couple of points. Perhaps we should approach this as a multi-part article.

  • Scripts/entrypoints?

    Dolf: I would include it as it is an often needed part in the setup.py for db setup/interaction, startup/shutdown, etc. And I am kind of messy with this at the moment so it would benefit me too if we write it down the way it shóuld be done, and then I start practising what we preach :)

    Jason: I feel like setup.py is one of those areas that STILL confuses me.

Other Notes

  • We should mention "good practice" regarding __init__.py being empty when possible, and set this up to work that way.

  • Jason: I'd like to avoid the phrase "best practice" when possible. I believe strongly in "good practice", but "best" suggests sole, all-purpose superiority, which really dosen't exist in coding, IME. 😛

    Will: 100% concur. I'm so far from the pypa party line on some things (especially virtualenv) but I realise that some of my practices are working around issues that don't really exist anymore and/or don't work outside my specific use case. I will avoid discussing those things, as I suspect it's more valuable to work on python packaging than it is to complain about it.

Clone this wiki locally