search

pyOpenSci / python-package-guide

scientific Python package recommendations & guidance curated by pyOpenSci
https://www.pyopensci.org/python-package-guide/
Other
70 stars 43 forks source link

[UX] Decision step on distributing package: Separate "should my code be a package" from "should my code be on PyPI and conda-forge" #273

Open zackw opened 1 month ago

zackw commented 1 month ago

Closely related to #272: the “When should you turn your code into a Python package?” section of https://www.pyopensci.org/python-package-guide/tutorials/intro.html should be much more prominent, should clearly explain that this is a separate decision from whether you want to upload your package to PyPI and/or conda-forge, and should clarify the reasons to do each of these things.

willingc commented 1 month ago

A possible next action @lwasser would be to update the title of the subsection or first paragraph: "Do I want to distribute my package on pypi/conda-forge: https://www.pyopensci.org/python-package-guide/tutorials/intro.html#making-your-package-installable-publishing-to-pypi-conda-forge

lwasser commented 3 weeks ago

oh yes... there are a few potential tasks here

  1. we could definitely start by fixing that heading!! that could be an issue that a someone could tackle in a sprint!
  2. I feel like after reading zack's other issues - we want something at a higher level . this section talks about reasons to create a package. But i think at the top of this page (and of the guide to be honest) we probably want a decision tree type of section that has something like

Different ways to share code - is a package for you?

...then something like

  1. You want to create a software package that people can easily install using pip or conda. You want people to be able to find you package in a public repository. Ideally: you plan to maintain your package for public use - it has docs, tests etc..... --> this user wants to publsih to pypi / conda forge
  2. You are working locally and you have a lot of code that needs to be organized. It would be helpful if you could install and use that code in different python environments. so you want to be able to easily reuse the code. you don't necesarily need the code to be avaialble to the public - yet (or ever). It may or may not be on github. You could use a package to organize and install your code. your future self will thank you for making it. more maintainable.
  3. you have a workflow that is a single script that you want to share. maybe it's associated with a paper. Maybe it uses dependencies that are outside of what comes with the basic python installation (some will confuse anacond that has a lot of dependencies with basic core python). IN that case \scripts might be useful for you? (or possibly myst-md but it doesnt (yet) support \scripts

thoughts? i think this would be a fantastic addition. and gosh writing like a google summer of docs or some sort of proposal to support a more robust set of tutorials and workshops would be awesome and perfectly in line with our mission! i have some ideas...