[WIP] Module reorganization

.github/workflows/build.yml

@@ -29,15 +29,15 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install flit
+          python -m pip install build
 
       - name: Build the package
         run: |
-          python -m flit build
+          python -m build
 
       - name: Try installing the package
         run: |
-          python -m pip install dist/fabrictestbed_extensions-*.whl
+          python -m pip install dist/fabrictestbed_fablib-*.whl
 
       # See https://github.com/actions/upload-artifact
       - name: Upload build artifacts

CHANGELOG.md

@@ -22,6 +22,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Methods added to retrieve SSH keys for bastion and sliver (PR
   [#207](https://github.com/fabric-testbed/fabrictestbed-extensions/pull/207))
 
+### Changed
+
+- Renamed the package to fabrictestbed-fablib.  Modules are also renamed, such
+  that we will have the shorter `import fabrictestbed_fablib.fablib` instead
+  of the longer `import fabrictestbed_extensions.fablib.fablib` (PR
+  [#172](https://github.com/fabric-testbed/fabrictestbed-extensions/pull/172),
+  issue [#164](https://github.com/fabric-testbed/fabrictestbed-extensions/issue/164)). 
+  A comatibility shim module is added so that we do not break existing code and
+  notebooks in the interim.  The existence of two top-level modules also
+  necessitates a switch to setuptools as the build backend.
+
 
 ## [1.4.4] - 2023-05-21
 

README.md

@@ -1,4 +1,4 @@
-# fabrictestbed-extensions
+# fabrictestbed-fablib
 
 [![pypi-badge]][pypy] [![api-docs-badge]][api-docs]
 
@@ -11,7 +11,7 @@ known as "FABlib", for intereacting with [FABRIC][fabric] testbed.
 You can install released versions of FABlib from PyPI:
 
 ```console
-$ pip install fabrictestbed-extensions
+$ pip install fabrictestbed-fablib
 ```
 
 If you need the current development version of FABlib, install it from
@@ -33,10 +33,10 @@ work. FABRIC team tends to favor virtualenvwrapper.
 Once installed, you can use FABlib in your Python projects:
 
 ```python
-from fabrictestbed_extensions.fablib.fablib import FablibManager as fablib_manager
+from fabrictestbed_fablib import FablibManager
 
 try:
-    fablib = fablib_manager()
+    fablib = FablibManager()
     fablib.show_config()
 except Exception as e:
     print(f"Exception: {e}")
@@ -93,47 +93,39 @@ $ pytest -s tests/integration/test_hello_fabric.py
 
 ## Packaging FABlib
 
-FABlib uses [flit] as the build backend.  To build source and wheel
-packages, do this:
+To build source and wheel packages, do this:
 
 ```console
-$ pip install flit
-$ flit build
-```
-
-While using flit as the build backend, continuing to use [build] as
-the build frontend should work too:
-
-```
 $ pip install build
 $ python -m build
 ```
 
 
 ## Releasing FABlib
 
-When it is time to release a new version of FABlib, remember to: (1)
-update the package version in top-level `__init__.py`, (2) build the
-source and wheel packages, and (3) upload packages to PyPI:
+When it is time to release a new version of FABlib, remember to:
+
+1. Update `version` in `pyproject.toml`.
+2. Tag the release tag and push the tag to GitHub:
 
 ```console
-$ flit publish
+$ git tag --sign --message "Great new features" rel<x.y.z> <commit>
+$ git push origin --tags rel<x.y.z>
 ```
 
-Continuing to use twine to publish packages is an option too:
+2. Build the source and wheel packages.
+3. Upload packages to PyPI using [twine]:
 
 ```console
+$ pip install twine
 $ twine upload dist/*
 ```
 
-For details about publishing to PyPI, see flit documentation about
-[package uploads].
-
 
 <!-- URLs -->
 
-[pypy]: https://pypi.org/project/fabrictestbed-extensions/
-[pypi-badge]: https://img.shields.io/pypi/v/fabrictestbed-extensions?style=plastic (PyPI)
+[pypy]: https://pypi.org/project/fabrictestbed-fablib/
+[pypi-badge]: https://img.shields.io/pypi/v/fabrictestbed-fablib?style=plain (PyPI)
 
 [api-docs]: https://fabric-fablib.readthedocs.io/en/latest/?badge=latest
 [api-docs-badge]: https://readthedocs.org/projects/fabric-fablib/badge/?version=latest (Documentation Status)
@@ -151,11 +143,9 @@ For details about publishing to PyPI, see flit documentation about
 [fablib-api-rtd]: https://fabric-fablib.readthedocs.io/en/latest/
 [fablib-api-old]: https://learn.fabric-testbed.net/docs/fablib/fablib.html
 
-[flit]: https://flit.pypa.io/en/stable/
-[package uploads]: https://flit.pypa.io/en/latest/upload.html
-
 [build]: https://pypi.org/project/build/
 [tox]: https://pypi.org/project/tox/
 [pytest]: https://pypi.org/project/pytest/
 [black]: https://pypi.org/project/black/
+[twine]: https://pypi.org/project/twine/
 [isort]: https://pypi.org/project/isort/

pyproject.toml

@@ -1,11 +1,10 @@
 [build-system]
-requires = ["flit_core >=3.2,<4"]
-build-backend = "flit_core.buildapi"
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
 
 [project]
-name = "fabrictestbed-extensions"
-# Bump version up in top-level __init.py__.
-dynamic = ["version"]
+name = "fabrictestbed-fablib"
+version = "1.5.1"
 description = "FABRIC Python Client Library and CLI Extensions"
 authors = [
     {name="Paul Ruth", email="[email protected]"},
@@ -56,11 +55,11 @@ branch = true
 omit = [ "fabrictestbed_extensions/tests/*" ]
 
 [tool.black]
-src_paths = ["fabrictestbed_extensions", "docs/source/conf.py", "tests"]
+src_paths = ["src", "docs/source/conf.py", "tests"]
 
 [tool.isort]
 profile = "black"
-src_paths = ["fabrictestbed_extensions", "docs/source/conf.py", "tests"]
+src_paths = ["src", "docs/source/conf.py", "tests"]
 
 [tool.pytest.ini_options]
 minversion = "6.0"

src/fabrictestbed_extensions/__init__.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# MIT License
+#
+# Copyright (c) 2020 FABRIC Testbed
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import warnings
+
+warnings.warn(
+    "fabrictestbed_extensions module is deprecated", DeprecationWarning, stacklevel=2
+)
+
+from importlib.metadata import version
+
+__version__ = version("fabrictestbed_fablib")

src/fabrictestbed_extensions/fablib/component.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# MIT License
+#
+# Copyright (c) 2020 FABRIC Testbed
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import warnings
+
+from fabrictestbed_fablib.component import Component
+
+warnings.warn(
+    "fabrictestbed_extensions.fablib.component module is deprecated;"
+    " please import fabrictestbed_fablib.component instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [Component]

src/fabrictestbed_extensions/fablib/fablib.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# MIT License
+#
+# Copyright (c) 2020 FABRIC Testbed
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import warnings
+
+from fabrictestbed_fablib.fablib import FablibManager
+
+warnings.warn(
+    "fabrictestbed_extensions.fablib.fablib module is deprecated;"
+    " please import fabrictestbed_fablib.fablib instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [FablibManager]

src/fabrictestbed_extensions/fablib/facility_port.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# MIT License
+#
+# Copyright (c) 2020 FABRIC Testbed
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import warnings
+
+from fabrictestbed_fablib.facility_port import FacilityPort
+
+warnings.warn(
+    "fabrictestbed_extensions.fablib.facility_port module is deprecated;"
+    " please import fabrictestbed_fablib.facility_port instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [FacilityPort]

src/fabrictestbed_extensions/fablib/interface.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# MIT License
+#
+# Copyright (c) 2020 FABRIC Testbed
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import warnings
+
+from fabrictestbed_fablib.interface import Interface
+
+warnings.warn(
+    "fabrictestbed_extensions.fablib.interface module is deprecated;"
+    " please import fabrictestbed_fablib.interface instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [Interface]

src/fabrictestbed_extensions/fablib/network_service.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# MIT License
+#
+# Copyright (c) 2020 FABRIC Testbed
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import warnings
+
+from fabrictestbed_fablib.network_service import NetworkService
+
+warnings.warn(
+    "fabrictestbed_extensions.fablib.network_service module is deprecated;"
+    " please import fabrictestbed_fablib.network_service instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [NetworkService]