🐞 Bug Bash wk 2🐞 Add: second lesson and images

[lwasser]

This is the second PR associated with the tutorial lesson development. it is ready for review. in this lesson a beginners learns how to make code pip installable. 🐞

[kierisi]

added my notes! I went through and provided comments as I went, rather than reading through a couple times and then giving feedback. so some of my comments are answered later in the tutorial, but I left the comments at the place in the tutorial where the question arose for me, and where it would be helpful to have some signposting.

[kierisi]

I know this seems basic, but beginners don't always know that a folder and directory are the same thing. it might be worth clarifying the first time directory is used, and then repeating throughout the tutorial.

[kierisi]

it would be beneficial to provide a quick Create a src/ directory by... and giving a 1-2 sentence bit of instruction on this.

[willingc]

You probably want this to be a src directory and drop the slash.

[lwasser]

ok got it.

can you please test this in shell for me? it works in my zsh shell so far

# Create a project directory in shell and a src directory within
mkdir -R pyospackage/src/pyospackage
# Change directory into pyospackage project dir 
cd pyospackage 
# View the current file structure 
ls

# Create a pyproject.toml file in your project directory 
touch pyproject.toml
# Create an empty init file within your src/pyospackage directory 
touch src/pyospackage/__init__.py

Your final project directory structure should look like this:

pyospackage/  # This is your project directory
     └─ pyproject.toml
     └─ src/ # This is your package directory where your code lives
             └── pyospackage_yourname/
              	     ├── __init__.py

[ucodery]

I've never used a mkdir with a -R option. I think you might have meant mkdir -p

[lwasser]

🙈 and i think i just made up a flag didn't i? thank you for the catch!! you are right. i am not sure where i got R from TBH. recursive? 🤷‍♀️

[willingc]

Overall, this is taking shape nicely.

[willingc]

Let's remove the comment and create a checklist of questions in a github issue.

[willingc]

Suggested change

	you are a scientist, we suggest that you use `conda`.
	you are a scientist, we suggest that you begin with `conda` because conda offers flexibility to extend to other programming languages, such as C, C++.

[willingc]

You probably want this to be a src directory and drop the slash.

[ucodery]

This is a really great tutorial!

[ucodery]

Not sure that we need to have "pip installable" everywhere. True, it's the most common installer, and I'm good if we sometimes say pip-installable, or use pip for real examples. But "install(able)" seems to convey as much relevant information and won't cause confusion if/when we introduce other tools (like conda).
(edit) after going through the whole file I see it's not all pip-install and this point has already been raised. But I still find it odd that the h1 heading mentions pip.

[lwasser]

ok i have a question @ucodery is there a way to install this type of package with conda? it never occurred to me that one could conda install a package locally if it wasn't a "conda packaged package" if that makes sense.

i'm fine with backing off the language pip. as i suppose you could do a hatch install or pdm install or poetry install too!

but your comment made me wonder about the range of tools that could actually install a package beyond pip and whether conda was actually in the mix.

for now i'll leave this comment open and will reread the lesson with that lense given at a minimum hatch, poetry and pdm (and flit??) could all potentially install this package we are teaching them to create here.

[ucodery]

I don't use conda, so I don't know if it can do a local install. As for the other packaging tools, those that are package managers can install as you noted (so not flit). There is also the low-level installer tool as well as older, deprecated installers such as easy_install.

[lwasser]

got it - thank you!

The reason why i've been careful about pip vs conda here is that a lot of scientists use conda (me included). And installing a conda version of python is so so easy - you can easily then create envts using various python versions with a single command, and it's friendlier if you are using tools that process spatial data.

so many will come from a conda background and need to understand how pip vs conda works. if we rely ONLY on python.org python and pip some scientists will have to relearn envt management. and it will get confusing i think.

either way i think this will be a bit of a thorn that we need to polish down in our lessons - which is why i thought about suggesting conda but having instructions for a non conda envt manager as well such as venv given it's native to python installs. then we can have a lesson (i have one started already) on venv vs conda installs.

[lwasser]

leaving this open for now. as it might warrant more discussion in slack / here to get it right!

[lwasser]

closing this via #120