Narrow v1 deprecation warnings to workspace creation

README.md

@@ -197,8 +197,9 @@ c = manager.create_cluster(
 
 The API is versioned, and version 2 — the flat `Cluster` resource shown above —
 is the default. Version 1, which called a deployment a `Workspace` inside a
-`WorkspaceGroup` and is reached through `s2.manage_workspaces()`, still works
-but is deprecated in its entirety. Select a version with the
+`WorkspaceGroup` and is reached through `s2.manage_workspaces()`, still works.
+`manage_workspaces()` is deprecated, because new deployments should be
+clusters. Select a version with the
 `management.version` option (`SINGLESTOREDB_MANAGEMENT_VERSION`) or by passing
 `version=` to any `manage_*` function.
 
@@ -258,8 +259,8 @@ conn.execute("""
 ```
 
 The `WORKSPACE` and `WORKSPACE GROUP` commands, and the version-less
-`SHOW REGIONS`, still work but are deprecated along with the rest of management
-API v1.
+`SHOW REGIONS`, still work. `CREATE WORKSPACE GROUP` and `CREATE WORKSPACE` are
+deprecated, because new deployments should be clusters: use `CREATE CLUSTER`.
 
 See [singlestoredb/fusion/README.md](singlestoredb/fusion/README.md)
 for details on writing custom Fusion SQL handlers.

docs/src/api.rst

@@ -340,18 +340,19 @@ with exactly one project does not need to name it.
 Workspaces (v1)
 ...............
 
-.. deprecated:: Management API v1 as a whole is deprecated, not just the
-   workspace vocabulary below. ``management.version`` now defaults to ``'v2'``,
-   and every entry point that resolves to v1 raises a
-   :class:`DeprecationWarning` -- whether v1 was named with ``version='v1'`` or
+.. deprecated:: :func:`manage_workspaces` is deprecated, because new
+   deployments should be clusters, and raises a :class:`DeprecationWarning`.
+   So do the Fusion SQL ``CREATE WORKSPACE GROUP`` and ``CREATE WORKSPACE``
+   commands, which point at ``CREATE CLUSTER``. ``management.version`` now
+   defaults to ``'v2'``.
+
+   **v1 still works.** Every function and class below still operates against
+   the live v1 endpoints, and :func:`manage_workspaces` still returns a working
+   :class:`WorkspaceManager` without being asked for a version. Other entry
+   points that resolve to v1 -- whether v1 was named with ``version='v1'`` or
    inherited from the ``management.version`` option
-   (``SINGLESTOREDB_MANAGEMENT_VERSION``).
-
-   **v1 still works.** Deprecated here means warned about, not removed: every
-   function and class below still operates against the live v1 endpoints, and
-   :func:`manage_workspaces` still returns a working
-   :class:`WorkspaceManager` without being asked for a version. Nothing raises
-   because the default moved. When you are ready to move off v1:
+   (``SINGLESTOREDB_MANAGEMENT_VERSION``) -- do not warn. When you are ready to
+   move to clusters:
 
    ==============================  ==============================
    v1                              v2
@@ -369,8 +370,7 @@ Workspaces (v1)
    organizational unit rather than a deployment parent.
 
    :func:`manage_files` and :func:`manage_regions` need no migration -- their
-   routes are identical at both versions, so simply stop passing
-   ``version='v1'``.
+   routes are identical at both versions.
 
 The :func:`manage_workspaces` function will return a :class:`WorkspaceManager`
 object that can be used to interact with version 1 of the Management API.

singlestoredb/_management_version.py

@@ -14,8 +14,3 @@
 #: class. Classes that implement one specific version name it literally
 #: instead, and do not follow this.
 DEFAULT_MANAGEMENT_VERSION = 'v2'
-
-#: Management API version being wound down. Public entry points that resolve
-#: to it raise a :class:`DeprecationWarning`, and everything under
-#: ``singlestoredb.management.v1`` goes away with it.
-DEPRECATED_MANAGEMENT_VERSION = 'v1'

singlestoredb/fusion/README.md

@@ -208,7 +208,7 @@ ShowMonthHandler.register()
 
 Here is a more complete example demonstrating optional values, selection groups,
 and repeated values. It is abridged from `handlers/workspace.py`, which speaks
-the deprecated management API v1 vocabulary; see `handlers/cluster.py` for the
+the management API v1 vocabulary; see `handlers/cluster.py` for the
 current `CLUSTER` commands.
 
 ```python

singlestoredb/fusion/handler.py

@@ -585,10 +585,11 @@ class SQLHandler(NodeVisitor):
     _enabled: bool = True
     _preview: bool = False
 
-    #: Command that replaces this one, e.g. ``'SHOW CLUSTERS'``. When set, the
-    #: command still runs but warns on every execution. Used for the management
-    #: API v1 vocabulary (``handlers/workspace.py``), which v2 replaced with the
-    #: flat ``CLUSTER`` commands. Empty means not deprecated.
+    #: Command that replaces this one, e.g. ``'CREATE CLUSTER'``. When set,
+    #: the command still runs but warns on every execution. Used for the
+    #: management API v1 commands that create workspace groups and workspaces
+    #: (``handlers/workspace.py``), since new deployments should be clusters.
+    #: Empty means not deprecated.
     _deprecated_by: str = ''
 
     def __init__(self, connection: Connection):
@@ -677,8 +678,8 @@ def execute(self, sql: str) -> result.FusionSQLResult:
             # After compile(), so that command_key is populated -- naming the
             # command the user actually typed is the point of the message.
             warnings.warn(
-                f'{" ".join(type(self).command_key).upper()} is a management '
-                'API v1 command and is deprecated. Use '
+                f'{" ".join(type(self).command_key).upper()} is deprecated: '
+                'new deployments should be clusters. Use '
                 f'{type(self)._deprecated_by} instead.',
                 DeprecatedFeatureWarning, stacklevel=2,
             )

singlestoredb/fusion/handlers/stage.py

@@ -11,10 +11,9 @@
 of Stage owner before v2 -- and which kind a given name belongs to is a fact
 about the org rather than about the statement.
 
-``IN GROUP`` names a workspace group explicitly, and is the one deprecated
-spelling here: it goes away with ``management/v1/``, and dropping the keyword
-is an edit that works today either way. :func:`.utils.get_deployment` resolves
-all of this, and everything it can return exposes ``.stage``.
+``IN GROUP`` names a workspace group explicitly.
+:func:`.utils.get_deployment` resolves all of this, and everything it can
+return exposes ``.stage``.
 """
 from typing import Any
 from typing import Dict
@@ -94,9 +93,7 @@ class ShowStageFilesHandler(SQLHandler):
     * The ``IN`` clause specifies the ID or the name of the deployment --
       or, for a Stage that has not moved off one, the workspace group --
       in which the Stage is attached.
-    * The ``IN GROUP`` clause names a workspace group explicitly. It is
-      deprecated and goes away with management API v1, which is the version
-      workspace groups belong to: drop the ``GROUP`` keyword, since a bare
+    * The ``IN GROUP`` clause names a workspace group explicitly. A bare
       ``IN`` resolves a workspace group too.
     * Use the ``RECURSIVE`` clause to list the files recursively.
     * To return more information about the files, use the ``EXTENDED``
@@ -221,9 +218,7 @@ class UploadStageFileHandler(SQLHandler):
     * The ``IN`` clause specifies the ID or the name of the deployment --
       or, for a Stage that has not moved off one, the workspace group --
       in which the Stage is attached.
-    * The ``IN GROUP`` clause names a workspace group explicitly. It is
-      deprecated and goes away with management API v1, which is the version
-      workspace groups belong to: drop the ``GROUP`` keyword, since a bare
+    * The ``IN GROUP`` clause names a workspace group explicitly. A bare
       ``IN`` resolves a workspace group too.
     * If the ``OVERWRITE`` clause is specified, any existing file at the
       specified path in the Stage is overwritten.
@@ -322,9 +317,7 @@ class DownloadStageFileHandler(SQLHandler):
     * The ``IN`` clause specifies the ID or the name of the deployment --
       or, for a Stage that has not moved off one, the workspace group --
       in which the Stage is attached.
-    * The ``IN GROUP`` clause names a workspace group explicitly. It is
-      deprecated and goes away with management API v1, which is the version
-      workspace groups belong to: drop the ``GROUP`` keyword, since a bare
+    * The ``IN GROUP`` clause names a workspace group explicitly. A bare
       ``IN`` resolves a workspace group too.
     * By default, files are downloaded in binary encoding. To view
       the contents of the file on the standard output, use the
@@ -425,9 +418,7 @@ class DropStageFileHandler(SQLHandler):
     * The ``IN`` clause specifies the ID or the name of the deployment --
       or, for a Stage that has not moved off one, the workspace group --
       in which the Stage is attached.
-    * The ``IN GROUP`` clause names a workspace group explicitly. It is
-      deprecated and goes away with management API v1, which is the version
-      workspace groups belong to: drop the ``GROUP`` keyword, since a bare
+    * The ``IN GROUP`` clause names a workspace group explicitly. A bare
       ``IN`` resolves a workspace group too.
 
     Example
@@ -507,9 +498,7 @@ class DropStageFolderHandler(SQLHandler):
     * The ``IN`` clause specifies the ID or the name of the deployment --
       or, for a Stage that has not moved off one, the workspace group --
       in which the Stage is attached.
-    * The ``IN GROUP`` clause names a workspace group explicitly. It is
-      deprecated and goes away with management API v1, which is the version
-      workspace groups belong to: drop the ``GROUP`` keyword, since a bare
+    * The ``IN GROUP`` clause names a workspace group explicitly. A bare
       ``IN`` resolves a workspace group too.
 
     Example
@@ -590,9 +579,7 @@ class CreateStageFolderHandler(SQLHandler):
     * The ``IN`` clause specifies the ID or the name of the deployment --
       or, for a Stage that has not moved off one, the workspace group --
       in which the Stage is attached.
-    * The ``IN GROUP`` clause names a workspace group explicitly. It is
-      deprecated and goes away with management API v1, which is the version
-      workspace groups belong to: drop the ``GROUP`` keyword, since a bare
+    * The ``IN GROUP`` clause names a workspace group explicitly. A bare
       ``IN`` resolves a workspace group too.
 
     Example

singlestoredb/fusion/handlers/utils.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python
 import datetime
 import os
-import warnings
 from typing import Any
 from typing import Dict
 from typing import Optional
@@ -27,7 +26,6 @@
 from ...management.workspace import Workspace
 from ...management.workspace import WorkspaceGroup
 from ...management.workspace import WorkspaceManager
-from ...warnings import DeprecatedFeatureWarning
 
 
 def get_workspace_manager() -> WorkspaceManager:
@@ -513,22 +511,6 @@ def _get_stage_group(
     if not group_name and not group_id:
         return None
 
-    # Warned before the lookup, so a caller who named a group that is gone
-    # still hears that the spelling itself is going. stacklevel reaches the
-    # handler method: user code is an unknown number of execute() frames
-    # further up, so there is no frame count that lands on it.
-    #
-    # The warning is about the clause, not the resource: a bare IN resolves a
-    # workspace group too, so dropping the GROUP keyword is an edit the caller
-    # can make today whether or not their Stage has moved to a cluster.
-    warnings.warn(
-        'IN GROUP is deprecated: it names a workspace group explicitly, and '
-        'workspace groups are a management API v1 resource that goes away '
-        'with v1. Use a bare IN instead, which names a deployment or a '
-        'workspace group.',
-        DeprecatedFeatureWarning, stacklevel=3,
-    )
-
     group = _workspace_group(name=group_name, id=group_id)
     if group is None:
         raise KeyError(
@@ -556,9 +538,7 @@ def _group_fallback(
     a cluster or a group is a fact about their org, not about their SQL. The
     group resource does go away with ``management/v1/``, but a warning here
     would ask for a migration that no edit to the statement can perform --
-    the same reason :func:`.workspace._manage_workspaces_v1` exists. ``IN
-    GROUP`` still warns, because that spelling *is* something the user can
-    change.
+    the same reason :func:`.workspace._manage_workspaces_v1` exists.
 
     The deployment lookup goes first, so a name that is both a cluster's and a
     group's is the cluster's, and nothing that resolves today changes meaning.

singlestoredb/fusion/handlers/workspace.py

@@ -2,12 +2,12 @@
 """
 Fusion SQL handlers for the management API v1 workspace vocabulary.
 
-**Deprecated.** ``handlers/cluster.py`` is the v2 replacement, and v2 is the
-default everywhere else in the SDK. Every command here sets ``_deprecated_by``
-naming its ``CLUSTER`` counterpart, so it still runs but warns once per
-execution. Nothing is removed and no grammar changed -- an existing v1 script
-keeps working, it just says where to go. This module is what gets deleted when
-``management/v1/`` goes.
+``handlers/cluster.py`` holds the v2 ``CLUSTER`` commands, and v2 is the
+default everywhere else in the SDK. Only the two commands that create
+something -- ``CREATE WORKSPACE GROUP`` and ``CREATE WORKSPACE`` -- set
+``_deprecated_by``, because new deployments should be clusters. The rest
+manage workspace groups that already exist and run without warning. This
+module is what gets deleted when ``management/v1/`` goes.
 
 Pinned to v1 through :func:`.utils.get_workspace_manager`: these commands *are*
 the v1 vocabulary, so they must not follow the ``management.version`` option onto
@@ -91,7 +91,6 @@ class UseWorkspaceHandler(SQLHandler):
         USE WORKSPACE 'examplews' IN GROUP 'my-workspace-group';
 
     """
-    _deprecated_by = 'USE CLUSTER'
 
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         from singlestoredb.notebook import portal
@@ -201,14 +200,6 @@ class ShowRegionsHandler(SQLHandler):
 
     """
 
-    # Not a column-for-column replacement, unlike the rest of this module: v2
-    # has no region IDs, so ``SHOW CLUSTER REGIONS`` reports ``Provider`` and
-    # ``RegionName`` where this reports ``ID``. Deprecated anyway, because this
-    # command reads the v1 API and that is what is going away -- a caller
-    # holding a v1 region ID needs to hear that now, not when the route stops
-    # answering.
-    _deprecated_by = 'SHOW CLUSTER REGIONS'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         manager = get_workspace_manager()
 
@@ -267,8 +258,6 @@ class ShowWorkspaceGroupsHandler(SQLHandler):
 
     """
 
-    _deprecated_by = 'SHOW CLUSTERS'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         manager = get_workspace_manager()
 
@@ -360,8 +349,6 @@ class ShowWorkspacesHandler(SQLHandler):
 
     """
 
-    _deprecated_by = 'SHOW CLUSTERS'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         res = FusionSQLResult()
         res.add_field('Name', result.STRING)
@@ -747,8 +734,6 @@ class SuspendWorkspaceHandler(SQLHandler):
 
     """  # noqa: E501
 
-    _deprecated_by = 'SUSPEND CLUSTER'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         ws = get_workspace(params)
         ws.suspend(wait_on_suspended=params['wait_on_suspended'])
@@ -824,8 +809,6 @@ class ResumeWorkspaceHandler(SQLHandler):
 
     """  # noqa: E501
 
-    _deprecated_by = 'RESUME CLUSTER'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         ws = get_workspace(params)
         ws.resume(
@@ -894,8 +877,6 @@ class DropWorkspaceGroupHandler(SQLHandler):
 
     """
 
-    _deprecated_by = 'DROP CLUSTER'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         try:
             workspace_group = get_workspace_group(params)
@@ -984,8 +965,6 @@ class DropWorkspaceHandler(SQLHandler):
 
     """
 
-    _deprecated_by = 'DROP CLUSTER'
-
     def run(self, params: Dict[str, Any]) -> Optional[FusionSQLResult]:
         try:
             ws = get_workspace(params)