Remove vega v5 wrappers

NOTES_FOR_MAINTAINERS.md

@@ -5,10 +5,7 @@
 
 The core Python API for Altair can be found in the following locations:
 
-- ``altair/vegalite/v2/schema/``
-- ``altair/vegalite/v1/schema/``
-- ``altair/vega/v3/schema/``
-- ``altair/vega/v2/schema/``
+- ``altair/vegalite/v5/schema/``
 
 All the files within these directories are created automatically by running
 the following script from the root of the repository:
@@ -19,19 +16,19 @@ $ python tools/generate_schema_wrapper.py
 
 This script does a couple things:
 
-- downloads the appropriate schema files from the specified vega and vega-lite
+- downloads the appropriate schema files from the specified vega-lite
   release versions & copies the JSON file to the appropriate ``schema``
   directory
 - generates basic low-level schemapi wrappers from the definitions within
   the schema: this is put in the ``schema/core.py`` file
 - generates a second layer of higher level wrappers for some vega-lite
   functionality; this is put in ``schema/channels.py`` and ``schema/mixins.py``
 
-The script output is designed to be deterministic; if vega/vega-lite versions
-are not changed, then running the script should overwrite the schema wrappers
+The script output is designed to be deterministic; if the vega-lite version
+is not changed, then running the script should overwrite the schema wrappers
 with identical copies.
 
-## Updating the Vega & Vega-Lite versions
+## Updating the Vega-Lite version
 
 The vega & vega-lite versions for the Python code can be updated by manually
 changing the ``SCHEMA_VERSION`` definition within
@@ -40,7 +37,7 @@ changing the ``SCHEMA_VERSION`` definition within
 This will update all of the automatically-generated files in the ``schema``
 directory for each version, but please note that it will *not* update other
 pieces (for example, the core of the Altair API, including methods and
-doc strings within ``altair/vegalite/v2/api.py``.
+doc strings within ``altair/vegalite/v5/api.py``.
 These additional methods have fairly good test coverage, so running the test
 suite should identify any inconsistencies:
 ```

altair/__init__.py

@@ -5,7 +5,6 @@
 
 
 def load_ipython_extension(ipython):
-    from ._magics import vega, vegalite
+    from ._magics import vegalite
 
-    ipython.register_magic_function(vega, "cell")
     ipython.register_magic_function(vegalite, "cell")

altair/_magics.py

@@ -1,7 +1,7 @@
 """
-Magic functions for rendering vega/vega-lite specifications
+Magic functions for rendering vega-lite specifications
 """
-__all__ = ["vega", "vegalite"]
+__all__ = ["vegalite"]
 
 import json
 import warnings
@@ -14,7 +14,6 @@
 from altair.vegalite import v3 as vegalite_v3
 from altair.vegalite import v4 as vegalite_v4
 from altair.vegalite import v5 as vegalite_v5
-from altair.vega import v5 as vega_v5
 
 try:
     import yaml
@@ -25,7 +24,6 @@
 
 
 RENDERERS = {
-    "vega": {"5": vega_v5.Vega},
     "vega-lite": {
         "3": vegalite_v3.VegaLite,
         "4": vegalite_v4.VegaLite,
@@ -35,10 +33,6 @@
 
 
 TRANSFORMERS = {
-    "vega": {
-        # Vega doesn't yet have specific data transformers; use vegalite
-        "5": vegalite_v5.data_transformers,
-    },
     "vega-lite": {
         "3": vegalite_v3.data_transformers,
         "4": vegalite_v4.data_transformers,
@@ -76,70 +70,6 @@ def _get_variable(name):
     return ip.user_ns[name]
 
 
-@magic_arguments.magic_arguments()
-@magic_arguments.argument(
-    "data",
-    nargs="*",
-    help="local variable name of a pandas DataFrame to be used as the dataset",
-)
-@magic_arguments.argument("-v", "--version", dest="version", default="v5")
-@magic_arguments.argument("-j", "--json", dest="json", action="store_true")
-def vega(line, cell):
-    """Cell magic for displaying Vega visualizations in CoLab.
-
-    %%vega [name1:variable1 name2:variable2 ...] [--json] [--version='v5']
-
-    Visualize the contents of the cell using Vega, optionally specifying
-    one or more pandas DataFrame objects to be used as the datasets.
-
-    If --json is passed, then input is parsed as json rather than yaml.
-    """
-    args = magic_arguments.parse_argstring(vega, line)
-
-    existing_versions = {"v5": "5"}
-    version = existing_versions[args.version]
-    assert version in RENDERERS["vega"]
-    Vega = RENDERERS["vega"][version]
-    data_transformers = TRANSFORMERS["vega"][version]
-
-    def namevar(s):
-        s = s.split(":")
-        if len(s) == 1:
-            return s[0], s[0]
-        elif len(s) == 2:
-            return s[0], s[1]
-        else:
-            raise ValueError("invalid identifier: '{}'".format(s))
-
-    try:
-        data = list(map(namevar, args.data))
-    except ValueError:
-        raise ValueError("Could not parse arguments: '{}'".format(line))
-
-    if args.json:
-        spec = json.loads(cell)
-    elif not YAML_AVAILABLE:
-        try:
-            spec = json.loads(cell)
-        except json.JSONDecodeError:
-            raise ValueError(
-                "%%vega: spec is not valid JSON. "
-                "Install pyyaml to parse spec as yaml"
-            )
-    else:
-        spec = yaml.load(cell, Loader=yaml.SafeLoader)
-
-    if data:
-        spec["data"] = []
-        for name, val in data:
-            val = _get_variable(val)
-            prepped = _prepare_data(val, data_transformers)
-            prepped["name"] = name
-            spec["data"].append(prepped)
-
-    return Vega(spec)
-
-
 @magic_arguments.magic_arguments()
 @magic_arguments.argument(
     "data",

altair/utils/mimebundle.py

@@ -1,4 +1,6 @@
 from .html import spec_to_html
+import warnings
+from .deprecation import AltairDeprecationWarning
 from ..vegalite.v5.data import data_transformers
 
 
@@ -12,18 +14,18 @@ def spec_to_mimebundle(
     engine=None,
     **kwargs,
 ):
-    """Convert a vega/vega-lite specification to a mimebundle
+    """Convert a vega-lite specification to a mimebundle
 
     The mimebundle type is controlled by the ``format`` argument, which can be
-    one of the following ['html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite']
+    one of the following ['html', 'json', 'png', 'svg', 'pdf',  'vega', 'vega-lite']
 
     Parameters
     ----------
     spec : dict
         a dictionary representing a vega-lite plot spec
-    format : string {'html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite'}
+    format : string {'html', 'json', 'png', 'svg', 'pdf',  'vega', 'vega-lite'}
         the file format to be saved.
-    mode : string {'vega', 'vega-lite'}
+    mode : string {'vega-lite'}
         The rendering mode.
     vega_version : string
         The version of vega.js to use
@@ -43,16 +45,16 @@ def spec_to_mimebundle(
 
     Note
     ----
-    The png, svg, pdf, and vega outputs require the altair_saver package
+    The png, svg, vega and pdf outputs require the vl-convert or altair_saver package
     to be installed.
     """
-    if mode not in ["vega", "vega-lite"]:
-        raise ValueError("mode must be either 'vega' or 'vega-lite'")
+    if mode != "vega-lite":
+        if mode == "vega":
+            warnings.warn(
+                "mode 'vega' is deprecated, use 'vega-lite'", AltairDeprecationWarning
+            )
+        raise ValueError("mode must be 'vega-lite'")
 
-    if mode == "vega" and format == "vega":
-        if vega_version is None:
-            raise ValueError("Must specify vega_version")
-        return {"application/vnd.vega.v{}+json".format(vega_version[0]): spec}
     if format in ["png", "svg", "pdf", "vega"]:
         return _spec_to_mimebundle_with_engine(
             spec, format, mode, engine=engine, **kwargs
@@ -68,17 +70,13 @@ def spec_to_mimebundle(
         )
         return {"text/html": html}
     if format == "vega-lite":
-        assert mode == "vega-lite"  # sanity check: should never be False
-        if mode == "vega":
-            raise ValueError("Cannot convert a vega spec to vegalite")
         if vegalite_version is None:
             raise ValueError("Must specify vegalite_version")
         return {"application/vnd.vegalite.v{}+json".format(vegalite_version[0]): spec}
     if format == "json":
         return {"application/json": spec}
     raise ValueError(
-        "format must be one of "
-        "['html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite']"
+        "format must be one of ['html', 'json', 'png', 'svg', 'pdf', 'vega', 'vega-lite']"
     )
 
 
@@ -91,7 +89,7 @@ def _spec_to_mimebundle_with_engine(spec, format, mode, **kwargs):
         a dictionary representing a vega-lite plot spec
     format : string {'png', 'svg', 'pdf', 'vega'}
         the format of the mimebundle to be returned
-    mode : string {'vega', 'vega-lite'}
+    mode : string {'vega-lite'}
         The rendering mode.
     engine: string {'vl-convert', 'altair_saver'}
         the conversion engine to use
@@ -147,7 +145,7 @@ def _validate_normalize_engine(engine, format):
 
     engine : {None, 'vl-convert', 'altair_saver'}
         the user-provided engine string
-    format : string {'png', 'svg', 'pdf', 'vega'}
+    format : string {'png', 'svg', 'pdf'}
         the format of the mimebundle to be returned
     """
     # Try to import vl_convert

altair/utils/save.py

@@ -1,6 +1,7 @@
 import json
 import pathlib
 import warnings
+from .deprecation import AltairDeprecationWarning
 
 from .mimebundle import spec_to_mimebundle
 
@@ -15,6 +16,48 @@ def write_file_or_filename(fp, content, mode="w"):
         fp.write(content)
 
 
+def set_inspect_format_argument(format, fp, inline):
+    """Inspect the format argument in the save function"""
+    if format is None:
+        if isinstance(fp, str):
+            format = fp.split(".")[-1]
+        elif isinstance(fp, pathlib.PurePath):
+            format = fp.suffix.lstrip(".")
+        else:
+            raise ValueError(
+                "must specify file format: "
+                "['png', 'svg', 'pdf', 'html', 'json', 'vega']"
+            )
+
+    if format != "html" and inline:
+        warnings.warn("inline argument ignored for non HTML formats.")
+
+    return format
+
+
+def set_inspect_mode_argument(mode, embed_options, spec, vegalite_version):
+    """Inspect the mode argument in the save function"""
+    if mode is None:
+        if "mode" in embed_options:
+            mode = embed_options["mode"]
+        elif "$schema" in spec:
+            mode = spec["$schema"].split("/")[-2]
+        else:
+            mode = "vega-lite"
+
+    if mode != "vega-lite":
+        if mode == "vega":
+            warnings.warn(
+                "mode 'vega' is deprecated, use 'vega-lite'", AltairDeprecationWarning
+            )
+        raise ValueError("mode must be 'vega-lite', " "not '{}'".format(mode))
+
+    if mode == "vega-lite" and vegalite_version is None:
+        raise ValueError("must specify vega-lite version")
+
+    return mode
+
+
 def save(
     chart,
     fp,
@@ -45,7 +88,7 @@ def save(
         the format to write: one of ['json', 'html', 'png', 'svg', 'pdf'].
         If not specified, the format will be determined from the filename.
     mode : string (optional)
-        Either 'vega' or 'vegalite'. If not specified, then infer the mode from
+        Must be 'vegalite'. If not specified, then infer the mode from
         the '$schema' property of the spec, or the ``opt`` dictionary.
         If it's not specified in either of those places, then use 'vegalite'.
     vega_version : string (optional)
@@ -81,34 +124,11 @@ def save(
     if embed_options is None:
         embed_options = {}
 
-    if format is None:
-        if isinstance(fp, str):
-            format = fp.split(".")[-1]
-        elif isinstance(fp, pathlib.PurePath):
-            format = fp.suffix.lstrip(".")
-        else:
-            raise ValueError(
-                "must specify file format: " "['png', 'svg', 'pdf', 'html', 'json']"
-            )
+    format = set_inspect_format_argument(format, fp, inline)
 
     spec = chart.to_dict()
 
-    if mode is None:
-        if "mode" in embed_options:
-            mode = embed_options["mode"]
-        elif "$schema" in spec:
-            mode = spec["$schema"].split("/")[-2]
-        else:
-            mode = "vega-lite"
-
-    if mode not in ["vega", "vega-lite"]:
-        raise ValueError("mode must be 'vega' or 'vega-lite', " "not '{}'".format(mode))
-
-    if mode == "vega-lite" and vegalite_version is None:
-        raise ValueError("must specify vega-lite version")
-
-    if format != "html" and inline:
-        warnings.warn("inline argument ignored for non HTML formats.")
+    mode = set_inspect_mode_argument(mode, embed_options, spec, vegalite_version)
 
     if format == "json":
         json_spec = json.dumps(spec, **json_kwds)
@@ -128,7 +148,7 @@ def save(
             **kwargs,
         )
         write_file_or_filename(fp, mimebundle["text/html"], mode="w")
-    elif format in ["png", "svg", "pdf"]:
+    elif format in ["png", "svg", "pdf", "vega"]:
         mimebundle = spec_to_mimebundle(
             spec=spec,
             format=format,