Describe workaround to packaging 23.2 breaking pipx local detection (#…

…35092)

The latest packaging - 23.2 breaks `pipx` detection of local path
installation and renders breeze installation impossible. The
workaround to it until pypa/pipx#1092
is solved is to downgrade packaging to < 23.2 - this is mostly
applicable to fresh installations of `pipx` that pull the latest
packaging.

This PR adds appropriate description to breeze installation process
- what to do when it fails, it also updates the advice printed
when the fallback to non-editable installation and provide an
advice to downgrade packaging.

BREEZE.rst

@@ -258,6 +258,20 @@ Run this command to install Breeze (make sure to use ``-e`` flag):
 
     pipx install -e ./dev/breeze
 
+.. warning::
+
+  If you see below warning - it means that you hit `known issue <https://github.com/pypa/pipx/issues/1092>`_
+  with ``packaging`` version 23.2:
+  ⚠️ Ignoring --editable install option. pipx disallows it for anything but a local path,
+  to avoid having to create a new src/ directory.
+
+  The workaround is to downgrade packaging to 23.1 and re-running the ``pipx install`` command.
+
+  .. code-block::bash
+
+     pip install "packaging<23.2"
+     pipx install -e ./dev/breeze --force
+
 
 .. note:: Note for Windows users
 
@@ -1659,8 +1673,8 @@ These are all available flags of ``version`` command:
   :alt: Breeze version
 
 
-Breeze self-upgrade
-...................
+Breeze setup self-upgrade
+.........................
 
 You can self-upgrade breeze automatically. These are all available flags of ``self-upgrade`` command:
 

CONTRIBUTORS_QUICK_START.rst

@@ -271,11 +271,26 @@ Setting up Breeze
 
 1. Install ``pipx`` - follow the instructions in   `Install pipx <https://pypa.github.io/pipx/>`_
 
-
 2. Run ``pipx install -e ./dev/breeze`` in your checked-out repository. Make sure to follow any instructions
    printed by ``pipx`` during the installation - this is needed to make sure that ``breeze`` command is
    available in your PATH.
 
+.. warning::
+
+  If you see below warning - it means that you hit `known issue <https://github.com/pypa/pipx/issues/1092>`_
+  with ``packaging`` version 23.2:
+  ⚠️ Ignoring --editable install option. pipx disallows it for anything but a local path,
+  to avoid having to create a new src/ directory.
+
+  The workaround is to downgrade packaging to 23.1 and re-running the ``pipx install`` command, for example
+  by running ``pip install "packaging<23.2"``.
+
+  .. code-block::bash
+
+     pip install "packaging==23.1"
+     pipx install -e ./dev/breeze --force
+
+
 3. Initialize breeze autocomplete
 
 .. code-block:: bash

CONTRIBUTORS_QUICK_START_GITPOD.rst

@@ -58,6 +58,21 @@ Gitpod default image have all the required packages installed.
 
 1. Run ``pipx install -e ./dev/breeze`` to install Breeze
 
+.. warning::
+
+  If you see below warning - it means that you hit `known issue <https://github.com/pypa/pipx/issues/1092>`_
+  with ``packaging`` version 23.2:
+  ⚠️ Ignoring --editable install option. pipx disallows it for anything but a local path,
+  to avoid having to create a new src/ directory.
+
+  The workaround is to downgrade packaging to 23.1 and re-running the ``pipx install`` command. for example
+  by running ``pip install "packaging<23.2"``.
+
+  .. code-block::bash
+
+     pip install "packaging==23.1"
+     pipx install -e ./dev/breeze --force
+
 2. Run ``breeze`` to enter breeze in Gitpod.
 
 Setting up database in Breeze

dev/README_RELEASE_AIRFLOW.md

@@ -240,6 +240,8 @@ The Release Candidate artifacts we vote upon should be the exact ones we vote ag
     pipx install -e ./dev/breeze
     ```
 
+
+
 - For major/minor version release, run the following commands to create the 'test' and 'stable' branches.
 
     ```shell script

dev/breeze/README.md

@@ -41,6 +41,20 @@ that might often be needed if dependencies change during development.
 pipx install -e ./dev/breeze --force
 ```
 
+NOTE! If you see below warning - it means that you hit [known issue](https://github.com/pypa/pipx/issues/1092)
+with `packaging` version 23.2
+⚠️ Ignoring --editable install option. pipx disallows it for anything but a local path,
+to avoid having to create a new src/ directory.
+
+The workaround is to downgrade packaging to 23.1 and re-running the `pipx install` command, for example
+by running `pip install "packaging<23.2"`.
+
+```shell
+pip install "packaging<23.2"
+pipx install -e ./dev/breeze --force
+```
+
+
 You can read more about Breeze in the [documentation](https://github.com/apache/airflow/blob/main/BREEZE.rst)
 
 This README file contains automatically generated hash of the `setup.py` and `setup.cfg` files that were

dev/breeze/src/airflow_breeze/params/doc_build_params.py

@@ -24,7 +24,7 @@
 providers_prefix = "apache-airflow-providers-"
 
 
-def get_provider_name_from_short_hand(short_form_providers: tuple[str]):
+def get_provider_name_from_short_hand(short_form_providers: tuple[str, ...]):
     return tuple(
         providers_prefix + short_form_provider.replace(".", "-")
         for short_form_provider in short_form_providers

dev/breeze/src/airflow_breeze/utils/path_utils.py

@@ -249,7 +249,10 @@ def find_airflow_sources_root_to_operate_on() -> Path:
         get_console().print(
             "\n[error]Breeze should only be installed with -e flag[/]\n\n"
             "[warning]Please go to Airflow sources and run[/]\n\n"
-            f"     {NAME} self-upgrade --force\n"
+            f"     {NAME} setup self-upgrade --use-current-airflow-sources\n"
+            '[warning]If during installation you see warning starting "Ignoring --editable install",[/]\n'
+            '[warning]make sure you first downgrade "packaging" package to <23.2, for example by:[/]\n\n'
+            f'     pip install "packaging<23.2"\n\n'
         )
         sys.exit(1)
     airflow_sources = get_used_airflow_sources()

dev/breeze/src/airflow_breeze/utils/reinstall.py

@@ -51,6 +51,9 @@ def warn_non_editable():
         "\n[error]It should only be installed in editable mode[/]\n\n"
         "[info]Please go to Airflow sources and run[/]\n\n"
         f"     {NAME} setup self-upgrade --use-current-airflow-sources\n"
+        '[warning]If during installation, you see warning with "Ignoring --editable install",[/]\n'
+        '[warning]make sure you first downgrade "packaging" package to <23.2, for example by:[/]\n\n'
+        f'     pip install "packaging<23.2"\n\n'
     )