feat(ml): deprecate Machine Learning APIs

firebase_admin/ml.py

@@ -14,16 +14,25 @@
 
 """Firebase ML module.
 
+.. deprecated::
+    Firebase ML is deprecated and will be shut down on June 15, 2027.
+    To host custom models, you must migrate to another solution. You can use Cloud Storage for
+    Firebase as an alternative for hosting custom models. For more info, see
+    https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
 This module contains functions for creating, updating, getting, listing,
 deleting, publishing and unpublishing Firebase ML models.
 """
 
+# pylint: disable=too-many-lines
 
 import datetime
+import os
 import re
+import sys
 import time
-import os
 from urllib import parse
+import warnings
 
 import requests
 
@@ -46,6 +55,30 @@
 except ImportError:
     _TF_ENABLED = False
 
+_DEPRECATION_WARNING = (
+    'Firebase ML is deprecated and will be shut down on June 15, 2027. '
+    'To host custom models, you must migrate to another solution. You can use Cloud Storage for '
+    'Firebase as an alternative for hosting custom models. For more info, see '
+    'https://firebase.google.com/docs/ml/migrate-to-cloud-storage'
+)
+
+
+def _is_internal_call():
+    """Checks if the current call originated from within the ML module."""
+    try:
+        # pylint: disable=protected-access
+        frame = sys._getframe(2)
+        while frame:
+            if frame.f_code.co_name in (
+                'from_dict', '_update_from_dict', 'handle_operation', 'list_models'
+            ):
+                return True
+            frame = frame.f_back
+    except (AttributeError, ValueError):
+        pass
+    return False
+
+
 _ML_ATTRIBUTE = '_ml'
 _MAX_PAGE_SIZE = 100
 _MODEL_ID_PATTERN = re.compile(r'^[A-Za-z0-9_-]{1,60}$')
@@ -77,34 +110,56 @@ def _get_ml_service(app):
 def create_model(model, app=None):
     """Creates a model in the current Firebase project.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         model: An ml.Model to create.
         app: A Firebase app instance (or None to use the default app).
 
     Returns:
         Model: The model that was created in Firebase ML.
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     return Model.from_dict(ml_service.create_model(model), app=app)
 
 
 def update_model(model, app=None):
     """Updates a model's metadata or model file.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         model: The ml.Model to update.
         app: A Firebase app instance (or None to use the default app).
 
     Returns:
         Model: The updated model.
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     return Model.from_dict(ml_service.update_model(model), app=app)
 
 
 def publish_model(model_id, app=None):
     """Publishes a Firebase ML model.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     A published model can be downloaded to client apps.
 
     Args:
@@ -114,41 +169,65 @@ def publish_model(model_id, app=None):
     Returns:
         Model: The published model.
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     return Model.from_dict(ml_service.set_published(model_id, publish=True), app=app)
 
 
 def unpublish_model(model_id, app=None):
     """Unpublishes a Firebase ML model.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         model_id: The id of the model to unpublish.
         app: A Firebase app instance (or None to use the default app).
 
     Returns:
         Model: The unpublished model.
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     return Model.from_dict(ml_service.set_published(model_id, publish=False), app=app)
 
 
 def get_model(model_id, app=None):
     """Gets the model specified by the given ID.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         model_id: The id of the model to get.
         app: A Firebase app instance (or None to use the default app).
 
     Returns:
      Model: The requested model.
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     return Model.from_dict(ml_service.get_model(model_id), app=app)
 
 
 def list_models(list_filter=None, page_size=None, page_token=None, app=None):
     """Lists the current project's models.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         list_filter: a list filter string such as ``tags:'tag_1'``. None will return all models.
         page_size: A number between 1 and 100 inclusive that specifies the maximum
@@ -160,6 +239,8 @@ def list_models(list_filter=None, page_size=None, page_token=None, app=None):
     Returns:
         ListModelsPage: A (filtered) list of models.
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     return ListModelsPage(
         ml_service.list_models, list_filter, page_size, page_token, app=app)
@@ -168,23 +249,39 @@ def list_models(list_filter=None, page_size=None, page_token=None, app=None):
 def delete_model(model_id, app=None):
     """Deletes a model from the current project.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         model_id: The id of the model you wish to delete.
         app: A Firebase app instance (or None to use the default app).
     """
+    if not _is_internal_call():
+        warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
     ml_service = _get_ml_service(app)
     ml_service.delete_model(model_id)
 
 
 class Model:
     """A Firebase ML Model object.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         display_name: The display name of your model - used to identify your model in code.
         tags: Optional list of strings associated with your model. Can be used in list queries.
         model_format: A subclass of ModelFormat. (e.g. TFLiteFormat) Specifies the model details.
     """
     def __init__(self, display_name=None, tags=None, model_format=None):
+        if not _is_internal_call():
+            warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
         self._app = None  # Only needed for wait_for_unlo
         self._data = {}
         self._model_format = None
@@ -342,7 +439,14 @@ def as_dict(self, for_upload=False):
 
 
 class ModelFormat:
-    """Abstract base class representing a Model Format such as TFLite."""
+    """Abstract base class representing a Model Format such as TFLite.
+
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+    """
     def as_dict(self, for_upload=False):
         """Returns a serializable representation of the object."""
         raise NotImplementedError
@@ -351,10 +455,18 @@ def as_dict(self, for_upload=False):
 class TFLiteFormat(ModelFormat):
     """Model format representing a TFLite model.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Args:
         model_source: A TFLiteModelSource sub class. Specifies the details of the model source.
     """
     def __init__(self, model_source=None):
+        if not _is_internal_call():
+            warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
         self._data = {}
         self._model_source = None
 
@@ -412,7 +524,14 @@ def as_dict(self, for_upload=False):
 
 
 class TFLiteModelSource:
-    """Abstract base class representing a model source for TFLite format models."""
+    """Abstract base class representing a model source for TFLite format models.
+
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+    """
     def as_dict(self, for_upload=False):
         """Returns a serializable representation of the object."""
         raise NotImplementedError
@@ -466,11 +585,20 @@ def sign_uri(gcs_tflite_uri, app):
 
 
 class TFLiteGCSModelSource(TFLiteModelSource):
-    """TFLite model source representing a tflite model file stored in GCS."""
+    """TFLite model source representing a tflite model file stored in GCS.
+
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+    """
 
     _STORAGE_CLIENT = _CloudStorageClient()
 
     def __init__(self, gcs_tflite_uri, app=None):
+        if not _is_internal_call():
+            warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
         self._app = app
         self._gcs_tflite_uri = _validate_gcs_tflite_uri(gcs_tflite_uri)
 
@@ -600,12 +728,20 @@ def as_dict(self, for_upload=False):
 class ListModelsPage:
     """Represents a page of models in a Firebase project.
 
+    .. deprecated::
+        Firebase ML is deprecated and will be shut down on June 15, 2027.
+        To host custom models, you must migrate to another solution. You can use Cloud Storage for
+        Firebase as an alternative for hosting custom models. For more info, see
+        https://firebase.google.com/docs/ml/migrate-to-cloud-storage
+
     Provides methods for traversing the models included in this page, as well as
     retrieving subsequent pages of models. The iterator returned by
     ``iterate_all()`` can be used to iterate through all the models in the
     Firebase project starting from this page.
     """
     def __init__(self, list_models_func, list_filter, page_size, page_token, app):
+        if not _is_internal_call():
+            warnings.warn(_DEPRECATION_WARNING, DeprecationWarning, stacklevel=2)
         self._list_models_func = list_models_func
         self._list_filter = list_filter
         self._page_size = page_size