From ec5c57afa4d887ccc4578e379ad3e316e24cdaf3 Mon Sep 17 00:00:00 2001 From: Murilo Marinho Date: Tue, 15 Sep 2026 00:21:50 +0100 Subject: [PATCH] Remove venv from the Python preamble and adjust pip usage The tutorial no longer uses a Python venv. User-level pip installs now run against the system Python with --break-system-packages, which is consistent with the dqrobotics example already used in the same section and works on the target Ubuntu 24.04 (PEP 668). - installing_python.rst: drop the 'Isolate your environment with a venv' section (create/activate/deactivate) and the python3-venv apt install; adjust the dqrobotics install to drop the activate step. - python_best_practices / python_asyncio / python_packaging: remove the 'Use a venv' sections and the ros2tutorial_venv activate commands. - python_packaging: add --break-system-packages to the pip install/ uninstall commands that previously relied on the venv, and update the sample output paths to the user site-packages location. - the_canonical_build_command.rst: remove the 'active venv breaks colcon' warning (this snippet is included by many pages). - source_after_build.rst: rewrite the 'dirty state' fix to drop the venv framing while keeping the build/install/log cleanup advice. Verified: full Sphinx build still succeeds with no new warnings, and no venv/virtual-environment references remain in the rendered docs. --- .../preamble/python/installing_python.rst | 68 ++----------------- .../source/preamble/python/python_asyncio.rst | 11 --- .../preamble/python/python_best_practices.rst | 11 --- .../preamble/python/python_packaging.rst | 31 +++------ docs/source/source_after_build.rst | 9 +-- docs/source/the_canonical_build_command.rst | 4 -- 6 files changed, 17 insertions(+), 117 deletions(-) diff --git a/docs/source/preamble/python/installing_python.rst b/docs/source/preamble/python/installing_python.rst index 955668c..e9a9646 100644 --- a/docs/source/preamble/python/installing_python.rst +++ b/docs/source/preamble/python/installing_python.rst @@ -60,70 +60,17 @@ Some Python packages must be installed through :program:`apt` ------------------------------------------------------------- .. warning:: - Aside from these packages that you **MUST** install from :program:`apt`, it is best to use :program:`venv` and :program:`pip` to install packages only for your user + Aside from these packages that you **MUST** install from :program:`apt`, it is best to use :program:`pip` to install packages only for your user without using :code:`sudo`. For some Python packages to work well with the default Python in Ubuntu, they must be installed through :program:`apt`. If you deviate from this, you can cause issues that might not be easy to recover from. -For the purposes of this tutorial, let us install :code:`pip` and :code:`venv` +For the purposes of this tutorial, let us install :code:`pip` .. code-block:: console sudo apt update - sudo apt install -y python3-pip python3-venv - -.. _Isolate your environment with a venv: - -When you want to isolate your environment, use :program:`venv` --------------------------------------------------------------- - -.. warning:: - At the time of this writing, there was no support for :program:`venv` on ROS2 `(More info) `_. - Until that is handled, we are not going to use :program:`venv` for the ROS2 tutorials. - However, we will use :program:`venv` to protect our ROS2 environment from these Python preamble tutorials. - -Using :program:`venv` (`More info `_) is quite straightforward. - -Create a :file:`venv` -+++++++++++++++++++++ - -.. code-block:: console - - cd ~ - python3 -m venv ros2tutorial_venv - -where the only argument, :code:`ros2tutorial_venv`, is the name of the folder in which the :code:`venv` will be created. - -Activate a :file:`venv` -+++++++++++++++++++++++ - -Whenever we want to use a :file:`venv`, it must be explicitly activated. - -.. code-block:: console - - cd ~ - source ros2tutorial_venv/bin/activate - -The terminal will change to have the prefix :code:`(ros2tutorial_venv)` to let us know that we are using a :file:`venv`, as follows - -.. code-block:: console - - (ros2tutorial_venv) murilo@murilos-toaster:~$ - -Deactivate a :file:`venv` -+++++++++++++++++++++++++ - -To deactivate, run - -.. code-block:: console - - deactivate - -We'll know that we're no longer using the :code:`ros2tutorial_venv` because the prefix will disappear back to - -.. code-block:: console - - murilo@murilos-toaster:~$ + sudo apt install -y python3-pip Installing libraries -------------------- @@ -139,14 +86,7 @@ Installing libraries As an example, let us install the best robot modeling and control library ever conceived, `DQ Robotics `_. -First, we activate the virtual environment - -.. code-block:: console - - cd ~ - source ros2tutorial_venv/bin/activate - -then, we install +We install it with .. code-block:: console diff --git a/docs/source/preamble/python/python_asyncio.rst b/docs/source/preamble/python/python_asyncio.rst index 94cfa01..6dea602 100644 --- a/docs/source/preamble/python/python_asyncio.rst +++ b/docs/source/preamble/python/python_asyncio.rst @@ -12,17 +12,6 @@ Python's :code:`asyncio` There are two main ways to interact with :code:`async` code, the first being by :code:`await`\ ing the results or by handling those results through :code:`callbacks`. Let's go through both of them with examples. -Use a :code:`venv` ------------------- - -We already know that it is a good practice to :ref:`Isolate your environment with a venv`. So, let's turn that into a reflex -and do so for this whole section. - -.. code-block:: console - - cd ~ - source ros2tutorial_venv/bin/activate - Create the :file:`minimalist_async` package ------------------------------------------- diff --git a/docs/source/preamble/python/python_best_practices.rst b/docs/source/preamble/python/python_best_practices.rst index cbb63fb..c8b22ed 100644 --- a/docs/source/preamble/python/python_best_practices.rst +++ b/docs/source/preamble/python/python_best_practices.rst @@ -33,17 +33,6 @@ sources/tutorials you might find elsewhere. It is based on my interpretation of - A collection of modules. - A folder with an :file:`__init__.py`, even if it doesn't have more than one module. When people say `Python Packaging `_ it refers instead to making your package installable (e.g. with a :file:`setup.py` or :file:`pyproject.toml`), so be ready for that ambiguity. -Use a :code:`venv` ------------------- - -We already know that it is a good practice to :ref:`Isolate your environment with a venv`. So, let's turn that into a reflex -and do so for this whole section. - -.. code-block:: console - - cd ~ - source ros2tutorial_venv/bin/activate - .. _Python package: Minimalist package: something to start with diff --git a/docs/source/preamble/python/python_packaging.rst b/docs/source/preamble/python/python_packaging.rst index 3cc51ce..73a1d69 100644 --- a/docs/source/preamble/python/python_packaging.rst +++ b/docs/source/preamble/python/python_packaging.rst @@ -9,17 +9,6 @@ Making your Python package installable In :program:`ROS2`, currently we fully rely on :file:`setup.py` approach using setuptools therefore that's what I discuss herein. -Use a :code:`venv` ------------------- - -We already know that it is a good practice to :ref:`Isolate your environment with a venv`. So, let's turn that into a reflex -and do so for this whole section. - -.. code-block:: console - - cd ~ - source ros2tutorial_venv/bin/activate - The :file:`setup.py` -------------------- @@ -77,11 +66,11 @@ Installing :file:`wheel` and the 'wheel' package is not installed. pip 23.1 will enforce this behaviour change. A possible replacement is to enable the '--use-pep517' option. Discussion can be found at https://github.com/pypa/pip/issues/8559 -To install the package in the recommended way in this tutorial, we need :file:`wheel`. While using the :code:`venv`, we install it +To install the package in the recommended way in this tutorial, we need :file:`wheel`. We install it with .. code-block:: console - python3 -m pip install wheel + python3 -m pip install wheel --break-system-packages Installing the Python package ----------------------------- @@ -91,7 +80,7 @@ We first go to the folder containing our *project* folder and we build and insta .. code-block:: console cd ~/ros2_tutorials_preamble/python - python3 -m pip install ./minimalist_package + python3 -m pip install ./minimalist_package --break-system-packages which results in @@ -99,7 +88,7 @@ which results in Processing ./minimalist_package Preparing metadata (setup.py) ... done - Requirement already satisfied: setuptools in ~ros2tutorial_venv/lib/python3.10/site-packages (from minimalist-package==23.6.0) (65.6.3) + Requirement already satisfied: setuptools in /home/murilo/.local/lib/python3.12/site-packages (from minimalist-package==23.6.0) (65.6.3) Building wheels for collected packages: minimalist-package Building wheel for minimalist-package (setup.py) ... done Created wheel for minimalist-package: filename=minimalist_package-23.6.0-py3-none-any.whl size=8608 sha256=929446a2fa81fc99fc5dec239a9f3e4439bc8fa8fe49cc4deb987d6f31b3d8b9 @@ -178,7 +167,7 @@ Given that we installed it using :program:`pip`, removing it is also a breeze. W .. code-block:: console - python3 -m pip uninstall minimalist_package + python3 -m pip uninstall minimalist_package --break-system-packages which will return something similar to @@ -187,11 +176,11 @@ which will return something similar to Found existing installation: minimalist-package 23.6.0 Uninstalling minimalist-package-23.6.0: Would remove: - /home/murilo/ros2tutorial_venv/bin/async_await_example - /home/murilo/ros2tutorial_venv/bin/async_callback_example - /home/murilo/ros2tutorial_venv/bin/minimalist_script - /home/murilo/ros2tutorial_venv/lib/python3.10/site-packages/minimalist_package-23.6.0.dist-info/* - /home/murilo/ros2tutorial_venv/lib/python3.10/site-packages/minimalist_package/* + /home/murilo/.local/bin/async_await_example + /home/murilo/.local/bin/async_callback_example + /home/murilo/.local/bin/minimalist_script + /home/murilo/.local/lib/python3.12/site-packages/minimalist_package-23.6.0.dist-info/* + /home/murilo/.local/lib/python3.12/site-packages/minimalist_package/* Proceed (Y/n)? and just press :kbd:`ENTER`, resulting in the package being uninstalled diff --git a/docs/source/source_after_build.rst b/docs/source/source_after_build.rst index d4e100a..c477cbd 100644 --- a/docs/source/source_after_build.rst +++ b/docs/source/source_after_build.rst @@ -106,8 +106,7 @@ Fixing a dirty state in your :program:`colcon build` Sometimes, a problematic build might not go away even with repeated calls to :program:`colcon build`. -The most common cause of this is when, by mistake, a terminal with an active :program:`venv` was used when calling -:program:`colcon build`. The usual error message will look like so. +A common error message will look like so. .. code-block:: console @@ -118,9 +117,8 @@ The most common cause of this is when, by mistake, a terminal with an active :pr To fix this, you must -#. Deactivate the :program:`venv`. #. Remove the :file:`build`, :file:`install`, and :file:`log` folders. -#. Rebuild and re-source in a clean terminal, without a :program:`venv`. +#. Rebuild and re-source in a clean terminal. In this tutorial, this would be equivalent to doing @@ -131,13 +129,12 @@ In this tutorial, this would be equivalent to doing .. code-block:: console - deactivate cd ~/ros2_tutorial_workspace rm -rf build/ install/ log/ colcon build source install/setup.bash -In rare cases, even without using a :program:`venv`, the workspace can be left in an unclean state in which older build +In rare cases, the workspace can be left in an unclean state in which older build artifacts cause build and runtime issues, such as failed builds and programs that do not seem to match their intended source code. These artifacts might include old files that should have been removed, issues with dependencies, and so on. In this case, removing the :file:`build`, :file:`install`, and :file:`log` folders can be useful. diff --git a/docs/source/the_canonical_build_command.rst b/docs/source/the_canonical_build_command.rst index e828f15..12583c2 100644 --- a/docs/source/the_canonical_build_command.rst +++ b/docs/source/the_canonical_build_command.rst @@ -7,7 +7,3 @@ .. note:: For additional explanation and troubleshooting tips, see :ref:`Always source after you build`. - -.. warning:: - - :program:`colcon` will *not* work properly if your terminal has an active :program:`venv`.