Ramp up deprecation of retworkx package and remove tests (#1004)

Since it's been > 1 year since we renamed retworkx to rustworkx, this
commit starts actively emitting `DeprecationWarning`s for importing
retworkx. Previously we had only documented the name as being
deprecated, however we still ~54k downloads per month. The warning should
hopefully encourage more people to move to the new name.

While we prepare to drop support for the retworkx name in the lead up to
rustworkx 1.0 eventually (see #1000) this commit also prepares us to
stop publishing updates in the future. Besides removing the warning it
decreases the prominence of the rename warning from the rustworkx
package documentation. This commit also remove the retworkx legacy tests
from the test suite as we've been running them for > 1 year now and have
not enountered any issues with the import redirect. The benefits of
keeping around a duplicated test suite for validating the redirects has
outlived it's usefulness, and is just wasted CPU resources (both locally
and more importantly in CI).

As for the final step of the retworkx name, to eventually drop support
for the legacy name, a comment is added to the setup.py about how we
make that migration. For the final 0.X release of rustworkx we should
change the `rustworkx==` pin in retworkx's setup.py to `rustworkx<1`.
We do have the option to do this at anytime because the retworkx package
source code is basically frozen and just redirecting imports from
retworkx to rustworkx. However, if the retworkx package wasn't pinned to
a fixed version then current users would potentially get a different
experience when installing the same version of the retworkx package
(i.e. if a user installed retworkx 0.14.0 tomorrow and then again 6
months later they could be using different rustworkx versions and
encounter different API bugs or deprecation warnings).

.github/workflows/main.yml

@@ -110,47 +110,6 @@ jobs:
         run: python -m pip install --upgrade tox
       - name: 'Run rustworkx stub tests'
         run: tox -estubs
-  tests_retworkx_compat:
-    if: github.repository_owner == 'Qiskit'
-    needs: [build_lint]
-    name: python${{ matrix.python-version }}-${{ matrix.platform.python-architecture }} ${{ matrix.platform.os }} ${{ matrix.msrv }}
-    runs-on: ${{ matrix.platform.os }}
-    strategy:
-      matrix:
-        rust: [stable]
-        python-version: ["3.10"]
-        platform: [
-          { os: "macOS-latest", python-architecture: "x64", rust-target: "x86_64-apple-darwin" },
-          { os: "ubuntu-latest", python-architecture: "x64", rust-target: "x86_64-unknown-linux-gnu" },
-          { os: "windows-latest", python-architecture: "x64", rust-target: "x86_64-pc-windows-msvc" },
-        ]
-    steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-          architecture: ${{ matrix.platform.python-architecture }}
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@master
-        with:
-          toolchain: ${{ matrix.rust }}
-          targets: ${{ matrix.platform.rust-target }}
-      - name: 'Install binary dependencies'
-        run: sudo apt-get install -y graphviz
-        if: runner.os == 'Linux'
-      - name: 'Build rustworkx and test dependencies'
-        run: |
-          pip install -c constraints.txt -U '.[mpl,graphviz]' fixtures testtools>=2.5.0 networkx>=2.5 stestr>=4.1
-      - name: 'Build retworkx'
-        env:
-          RUSTWORKX_PKG_NAME: "retworkx"
-        run: |
-          pip install -c constraints.txt -U .
-      - name: 'Run retworkx tests'
-        run: |
-          cd tests
-          stestr run -t ./retworkx_backwards_compat
   coverage:
     if: github.repository_owner == 'Qiskit'
     needs: [tests]

README.md

@@ -12,11 +12,7 @@
 [![Zenodo](https://img.shields.io/badge/Zenodo-10.5281%2Fzenodo.5879859-blue)](https://doi.org/10.5281/zenodo.5879859)
 
   - You can see the full rendered docs at:
-    <https://qiskit.org/ecosystem/rustworkx/dev>
-
-|:warning:| The retworkx project has been renamed to **rustworkx**. The use of the
-retworkx package will still work for the time being but starting in the 1.0.0
-release retworkx will no longer be supported
+    <https://qiskit.org/ecosystem/rustworkx/>
 
 rustworkx is a general purpose graph library for Python written in Rust to
 take advantage of the performance and safety that Rust provides. It is
@@ -27,7 +23,7 @@ any Python application.
 
 Rustworkx was originally called retworkx and was created initially to be
 a replacement for [qiskit](https://qiskit.org/)'s previous (and current)
-networkx usage (hence the original name).  The project was originally started
+NetworkX usage (hence the original name).  The project was originally started
 to build a faster directed graph to use as the underlying data structure for
 the DAG at the center of
 [qiskit-terra](https://github.com/Qiskit/qiskit-terra/)'s transpiler. However,

docs/source/index.rst

@@ -2,12 +2,6 @@
 rustworkx Documentation
 #######################
 
-.. note::
-
-    The project has been renamed to **rustworkx**. You can still use the legacy
-    retworkx name for now but starting in the 1.0.0 release the retworkx name
-    will no longer be supported.
-
 rustworkx is a Python package for working with graphs and complex networks. It
 enables the creation, interaction with, and study of graphs and networks.
 
@@ -57,6 +51,12 @@ https://docs.rs/rustworkx-core/0.13.0/rustworkx_core/
 Project history
 ---------------
 
+.. note::
+
+    The project has been renamed to **rustworkx**. You can still use the legacy
+    retworkx name for now but starting in the 1.0.0 release the retworkx name
+    will no longer be supported.
+
 rustworkx was originally called retworkx and was created to be a high
 performance replacement for the Qiskit project's internal usage of the
 `NetworkX <https://networkx.org/>`__ library (which is where the name came

docs/source/install.rst

@@ -59,7 +59,7 @@ limitations in available testing resources and platform availability, not all
 platforms can be supported. Platform support for rustworkx is broken into 4
 tiers with different levels of support for each tier. For platforms outside
 these, rustworkx is probably still installable, but it’s not tested and you will
-need a Rust compiler and have to build retworkx (and likely Numpy too) from
+need a Rust compiler and have to build rustworkx (and likely Numpy too) from
 source.
 
 .. list-table:: Platform Support

releasenotes/notes/retworkx-deprecation-848bc6b41f2368cf.yaml

@@ -0,0 +1,7 @@
+---
+deprecations:
+  - |
+    The legacy ``retworkx`` package that operates as a backwards compatibility
+    alias for ``rustworkx`` has been marked as deprecated. If you're using
+    the ``retworkx`` package it will now emit a ``DeprecationWarning`` on
+    import.

retworkx/__init__.py

@@ -10,11 +10,18 @@
 
 
 import sys
+import warnings
 
 from rustworkx import *  # noqa
 
 from . import namespace
 
+warnings.warn(
+    "The retworkx package is deprecated and has been renamed to rustworkx. Rustworkx is a "
+    "drop-in replacement and can be used by replacing `import retworkx` with import `rustworkx`. ",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
 sys.modules["retworkx.generators"] = generators  # noqa
 new_meta_path_finder = namespace.RetworkxImport("retworkx", "rustworkx")

setup.py

@@ -46,6 +46,7 @@ def readme():
 if PKG_NAME == "retworkx":
     README = retworkx_readme_compat + README
     PKG_PACKAGES = ["retworkx"]
+    # TODO: For final retworkx release change this to < 1.
     PKG_INSTALL_REQUIRES.append(f"rustworkx=={PKG_VERSION}")
     RUST_EXTENSIONS = []