From baebc9db2e11cd8a24906511b239934756139c5d Mon Sep 17 00:00:00 2001 From: Harshit Sharma <66710144+harshitethic@users.noreply.github.com> Date: Sat, 26 Sep 2026 10:56:41 +0530 Subject: [PATCH] docs: clarify packaging tutorial import and CLI scope --- source/tutorials/packaging-projects.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 4f69de20b..8bc5cfb5e 100644 --- a/source/tutorials/packaging-projects.rst +++ b/source/tutorials/packaging-projects.rst @@ -5,6 +5,12 @@ This tutorial walks you through how to package a simple Python project. It will show you how to add the necessary files and structure to create the package, how to build the package, and how to upload it to the Python Package Index (PyPI). +The example is an **importable Python package**. If your main goal is to turn a +Python program into an installed command such as ``my-tool``, start with the +:doc:`command-line tools guide `. That +guide covers executable entry points; you can then use the build and publishing +steps from this tutorial for the resulting project. + .. tip:: If you have trouble running the commands in this tutorial, please copy the command @@ -68,6 +74,19 @@ Open that file and enter the following content: def add_one(number): return number + 1 +Because this tutorial leaves :file:`__init__.py` empty, ``add_one`` belongs +to the ``example`` module rather than being exposed directly on the package. +After installation, use it through that module, for example: + +.. code-block:: pycon + + >>> from example_package_YOUR_USERNAME_HERE import example + >>> example.add_one(2) + 3 + +A package can choose to re-export selected names from :file:`__init__.py`, +but doing so is an API-design choice and is not required for packaging. + If you are unfamiliar with Python's :term:`modules ` and :term:`import packages `, take a few minutes to read over the `Python documentation for packages and modules`_.