fix: rename tutorial and update to use template #527

lwasser · 2025-07-01T19:07:28Z

I am making 1 bigg-ish change here and then updating the tutorial to use our packaging template.
the big change is a file rename which impacted links throughout.

lwasser · 2025-07-01T19:08:35Z

tutorials/create-python-package.md

@@ -1,63 +1,32 @@
 ---


This is where the actual lesson content is updated.

lwasser · 2025-07-01T19:09:16Z

tutorials/create-python-package.md

-A basic installable package needs a few things: code, a [specific package file structure](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html) and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer. You will learn how to create a basic installable package in this lesson.
-
-:::
+(create-pure-python-package)=


I moved all of the intro content to the end as People have limited attention spans. So they can create the package and learn more if they continue to read. I'm testing this as a new approach, given most people don't get to the end of a tutorial.

makes sense to me! let us know if this works better :).

one thing that might be helpful here is one sentence that says what a python package is, unless this is explained beforehand. i like the change in title/url and think it is good. maybe add back in that one bit of context: why are we making a package again? oh yeah so we can install and distribute it". this is explained in passing in line 18 (or what is now line 18), but if you didn't already know that's what a package did or that a pyproject.toml is ~synonymous with creating a package, the connection may not be clear.

maybe even a minor rewording of the opening sentences would do this. "your package will be installable ... into a python environment" -> something like "a python package is a 'unit' of code that can be installed and used just like other packages you may have seen imported at the top of a file like import numpy." idk not exactly that, just giving some concreteness to what the idea of "package" is before the rest of the lesson walks them through it

lwasser · 2025-07-01T19:10:29Z

tutorials/create-python-package.md

+    create  .github/workflows/test.yml
+    create  .github/PULL_REQUEST_TEMPLATE.md
+    create  .github/ISSUE_TEMPLATE
+    create  .github/ISSUE_TEMPLATE/config.yml


I'm wondering if we want to remove github templates for the basic package or not?

that makes intuitive sense to me for what minimal default means!

so then we would have some option for "create CI workflows and templates" or smth? because if i were to use this template i would definitely want to be able to flip this on and off bc i have my own stuff i like to use here, but definitely see the benefit of having it here if you want it!!!!

sneakers-the-rat · 2025-07-02T07:48:01Z

tutorials/create-python-package.md

+   pyopensci
+
+Copying from template version 0.6.2
+    create  CODE_OF_CONDUCT.md


(this could probably be omitted or abbreviated because it might look forbidding to someone glancing at the page who is not used to seeing text scroll by all day, and the directory structure is printed more readably below)

sneakers-the-rat · 2025-07-02T07:50:29Z

tutorials/create-python-package.md

+│   └── pyospackage_pyopensci
+        └── example.py


Suggested change

│ └── pyospackage_pyopensci

└── example.py

│ └── pyospackage_pyopensci/

| ├── __init__.py

| └── example.py

maybe init is not shown here on purpose to just show bare essentials? i think in this case it would probably be good to show it because e.g. if the students refer back to this page later when trying to make their own package without a template, since this is the last time directory structure is printed before the supplementary section at the end, it could be tempting to read this as the "final form" of the package. not a strong feeling, up to you

sneakers-the-rat · 2025-07-02T07:51:41Z

tutorials/create-python-package.md

+**Full customization**
+If you want to customize any elements of your package setup, choose `No, I want to fully customize the template.`.  This will allow you to select:
+
+* sphinx vs makedocs vs no documentation


Suggested change

* sphinx vs makedocs vs no documentation

* sphinx vs [mkdocs](https://www.mkdocs.org/) vs no documentation

sneakers-the-rat · 2025-07-02T07:52:16Z

tutorials/create-python-package.md


-If you are following along and making a Python package from scratch then you can add the code below to your `add_numbers.py` module. The function below adds two integers together and returns the result. Notice that the code below has a few features that we will review in future tutorials:
+Notice that the code in the example.py modulf, has a few features:


Suggested change

Notice that the code in the example.py modulf, has a few features:

Notice that the code in the example.py module, has a few features:

sneakers-the-rat · 2025-07-02T07:55:08Z

tutorials/create-python-package.md

@@ -547,15 +390,17 @@ mode) you can use:
 Above, you use`python -m` to call the version of pip installed into your
 current active environment. `python -m` is important to ensure that you are
 calling the version of pip installed in your current environment.
+
+IMPORTANT: pip can also be used to install packages from PyPI. However, in this case, you are telling pip to install your package from a local folder by using the `.`. You could also specify a path to the project directory on your computer instead of the `.` which tells pip to use the current working directory.


Suggested change

IMPORTANT: pip can also be used to install packages from PyPI. However, in this case, you are telling pip to install your package from a local folder by using the `.`. You could also specify a path to the project directory on your computer instead of the `.` which tells pip to use the current working directory.

IMPORTANT: pip can also be used to install packages from PyPI. However, in this case, you are telling pip to install your package from a local folder by using the `.`, which is a shorthand for the current directory. You could also specify a path to a package in a different directory on your computer like `python -m pip install /home/me/another_package`.

sneakers-the-rat · 2025-07-02T07:56:27Z

tutorials/create-python-package.md

+>>> from pyospackage.example import add_numbers
+>>> add_numbers(1, 2)


fix: rename tutorial and update to use template

93218c6

lwasser commented Jul 1, 2025

View reviewed changes

tutorials/create-python-package.md

@@ -1,63 +1,32 @@

---

Copy link

Member Author

lwasser Jul 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is where the actual lesson content is updated.

lwasser commented Jul 1, 2025

View reviewed changes

typos

e6b59c0

sneakers-the-rat reviewed Jul 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: rename tutorial and update to use template #527

fix: rename tutorial and update to use template #527

Uh oh!

lwasser commented Jul 1, 2025

Uh oh!

lwasser Jul 1, 2025

Uh oh!

lwasser Jul 1, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025 •

edited

Loading

Uh oh!

lwasser Jul 1, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

sneakers-the-rat Jul 2, 2025 •

edited

Loading

Uh oh!

sneakers-the-rat Jul 2, 2025

Uh oh!

Uh oh!

-│   └── pyospackage_pyopensci
-        └── example.py
+│   └── pyospackage_pyopensci/
+|       ├── __init__.py
+|       └── example.py

	* sphinx vs makedocs vs no documentation
	* sphinx vs [mkdocs](https://www.mkdocs.org/) vs no documentation


		If you are following along and making a Python package from scratch then you can add the code below to your `add_numbers.py` module. The function below adds two integers together and returns the result. Notice that the code below has a few features that we will review in future tutorials:
		Notice that the code in the example.py modulf, has a few features:

	IMPORTANT: pip can also be used to install packages from PyPI. However, in this case, you are telling pip to install your package from a local folder by using the `.`. You could also specify a path to the project directory on your computer instead of the `.` which tells pip to use the current working directory.
	IMPORTANT: pip can also be used to install packages from PyPI. However, in this case, you are telling pip to install your package from a local folder by using the `.`, which is a shorthand for the current directory. You could also specify a path to a package in a different directory on your computer like `python -m pip install /home/me/another_package`.

		>>> from pyospackage.example import add_numbers
		>>> add_numbers(1, 2)

fix: rename tutorial and update to use template #527

Are you sure you want to change the base?

fix: rename tutorial and update to use template #527

Uh oh!

Conversation

lwasser commented Jul 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sneakers-the-rat Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sneakers-the-rat Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sneakers-the-rat Jul 2, 2025 •

edited

Loading

sneakers-the-rat Jul 2, 2025 •

edited

Loading