Initial outline and some details for python style guide

[stscicrawford]

This is an initial outline for the python section in the style guide. It will need to be further filled out, but it is a first pass for the main sections to be included in the style guide.

Some example material has been added to each section.

My suggestion is let's comment on the outline in this PR, once agreed, merge it, and then proceed to looking at the content and further filling it out, though any comments, PRs, and discussion is welcome here.

[stscicrawford]

cc: @eteq @nden @bourque @arfon

[stscicrawford]

I've stated opening issues for some other guides that have evolved out of this one -- I think something about testing (pytest, artifactory, other platforms) and continuous integration guidelines (jenkins, travis), but if there is other things you see while reading through this, then my suggestion would be to create an issue.

[bourque]

Perhaps it would be worth mentioning PEP 257 Docstring Conventions in the Documentation section? I always think of PEP 257 as something that should be followed as strongly as PEP 8.

[nden]

This looks good to me. One practical question that comes to mind - is this the right place to describe tools and procedures for configuring an environment to comply with these guides? Perhaps have a section at the end that links to existing descriptions of how to configure IDEs or editors to check for PEP8 compliance?

[stscicrawford]

@nden That's a good idea -- that would definitely be helpful to add (or create a new page in here if it is information that needs to be STScI specific).

[eteq]

Hits most of the key points! All of my comments above are specific additions/modifications. There are a few more things I think are useful to highlight, though:

• We should get across here the idea that Python is an ecosystem that is meant to be shared. That is, it's always a good idea to first see if there's another package that does what you need before you start coding. If so, use that.
• We should say something about classes vs functions. There's not an obvious answer of course, but I think something that gets across the idea that "you should learn enough about the general concepts of OOP to know when it might be called for" is warranted. @SaOgaz has some good works in the STAK notebooks about this.
• We should probably mention something about wrapping C code. I don't think we want to be overly-perscriptive, but maybe something like "Try Cython because it's easier for others to read, supports numpy (use the memoryview technique for that) and builds with a python project mostly transparently. If that doesn't work, try other reasonably standard tools like pybind. If that doesn't work, use the C-API directly but use existing build machinery instead of rolling your own if at all possible."?
• Along the lines of @nden's suggestion about setting up environments: it might also be good to have a recommendation for setting up the development environment. E.g. "Use python setup.py develop if it's pure-python, or python setup.py build and run from the build directory if not. Use conda environments to manage dependencies."

[stscicrawford]

Okay, I've updated the comments or opened issues for all comments in here. So, this should be considered a first draft and from here, any one is welcome to make pull requests for more additions or changes.

[arfon]

🤘