Add ops.lib deprecation notice

ops/lib/__init__.py

@@ -12,12 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Infrastructure for the opslib functionality."""
+"""Infrastructure for the opslib functionality.
+
+DEPRECATED: The ops.lib functionality is deprecated, and is superseded by
+charm libraries (https://juju.is/docs/sdk/library) and regular Python imports.
+We now prefer to do version selection at build (charmcraft pack) time.
+"""
 
 import logging
 import os
 import re
 import sys
+import warnings
 from ast import literal_eval
 from importlib.machinery import ModuleSpec
 from importlib.util import module_from_spec
@@ -41,6 +47,9 @@
 def use(name: str, api: int, author: str) -> ModuleType:
     """Use a library from the ops libraries.
 
+    DEPRECATED: This function is deprecated. Prefer charm libraries instead
+    (https://juju.is/docs/sdk/library).
+
     Args:
         name: the name of the library requested.
         api: the API version of the library.
@@ -52,6 +61,8 @@ def use(name: str, api: int, author: str) -> ModuleType:
         TypeError: if the name, api, or author are the wrong type.
         ValueError: if the name, api, or author are invalid.
     """
+    warnings.warn("ops.lib is deprecated, prefer charm libraries instead",
+                  category=DeprecationWarning)
     if not isinstance(name, str):
         raise TypeError(f"invalid library name: {name!r} (must be a str)")
     if not isinstance(author, str):
@@ -88,7 +99,12 @@ def autoimport():
     You only need to call this if you've installed a package or
     otherwise changed sys.path in the current run, and need to see the
     changes. Otherwise libraries are found on first call of `use`.
+
+    DEPRECATED: This function is deprecated. Prefer charm libraries instead
+    (https://juju.is/docs/sdk/library).
     """
+    warnings.warn("ops.lib is deprecated, prefer charm libraries instead",
+                  category=DeprecationWarning)
     global _libraries
     _libraries = {}
     for spec in _find_all_specs(sys.path):

test/test_lib.py

@@ -24,9 +24,13 @@
 from unittest.mock import patch
 
 import logassert
+import pytest
 
 import ops.lib
 
+# Ignore deprecation warnings for this module.
+pytestmark = pytest.mark.filterwarnings('ignore::DeprecationWarning')
+
 
 def _mklib(topdir: str, pkgname: str, libname: str) -> Path:
     """Make a for-testing library.
@@ -609,3 +613,14 @@ def test_others_found(self):
 
         with self.assertRaises(ImportError):
             ops.lib.use('baz', 2, 'bob@example.com')
+
+
+class TestDeprecationWarning(TestCase):
+    def test_autoimport_deprecated(self):
+        with self.assertWarns(DeprecationWarning):
+            ops.lib.autoimport()
+
+    def test_use_deprecated(self):
+        with self.assertWarns(DeprecationWarning):
+            with self.assertRaises(ImportError):
+                ops.lib.use('foo', 1, 'bob@example.com')