[query] Deprecate default_reference parameter to hl.init (#13987)

CHANGELOG: Deprecate default_reference parameter to hl.init, users
should use `default_reference` with an argument to set new default
references usually shortly after init.

Resolves #13856

---------

Co-authored-by: Dan King <daniel.zidan.king@gmail.com>

hail/python/hail/context.py

@@ -11,7 +11,7 @@
 from pyspark import SparkContext
 
 import hail
-from hail.genetics.reference_genome import ReferenceGenome
+from hail.genetics.reference_genome import ReferenceGenome, reference_genome_type
 from hail.typecheck import (nullable, typecheck, typecheck_method, enumeration, dictof, oneof,
                             sized_tupleof, sequenceof)
 from hail.utils import get_env_or_default
@@ -142,7 +142,7 @@ def default_reference(self) -> ReferenceGenome:
         return self._default_ref
 
     @default_reference.setter
-    def set_default_reference(self, value):
+    def default_reference(self, value):
         if not isinstance(value, ReferenceGenome):
             raise TypeError(f'{value} is {type(value)} not a ReferenceGenome')
         self._default_ref = value
@@ -167,7 +167,7 @@ def stop(self):
            min_block_size=int,
            branching_factor=int,
            tmp_dir=nullable(str),
-           default_reference=enumeration(*BUILTIN_REFERENCES),
+           default_reference=nullable(enumeration(*BUILTIN_REFERENCES)),
            idempotent=bool,
            global_seed=nullable(int),
            spark_conf=nullable(dictof(str, str)),
@@ -192,7 +192,7 @@ def init(sc=None,
          min_block_size=0,
          branching_factor=50,
          tmp_dir=None,
-         default_reference='GRCh37',
+         default_reference=None,
          idempotent=False,
          global_seed=None,
          spark_conf=None,
@@ -212,11 +212,11 @@ def init(sc=None,
 
     This function will be called with default arguments if any Hail functionality is used. If you
     need custom configuration, you must explicitly call this function before using Hail. For
-    example, to set the default reference genome to GRCh38, import Hail and immediately call
+    example, to set the global random seed to 0, import Hail and immediately call
     :func:`.init`:
 
     >>> import hail as hl
-    >>> hl.init(default_reference='GRCh38')  # doctest: +SKIP
+    >>> hl.init(global_seed=0)  # doctest: +SKIP
 
     Hail has two backends, ``spark`` and ``batch``. Hail selects a backend by consulting, in order,
     these configuration locations:
@@ -289,6 +289,8 @@ def init(sc=None,
         Networked temporary directory.  Must be a network-visible file
         path.  Defaults to /tmp in the default scheme.
     default_reference : :class:`str`
+        *Deprecated*. Please use :func:`.default_reference` to set the default reference genome
+
         Default reference genome. Either ``'GRCh37'``, ``'GRCh38'``,
         ``'GRCm38'``, or ``'CanFam3'``.
     idempotent : :obj:`bool`
@@ -334,6 +336,14 @@ def init(sc=None,
             warning('Hail has already been initialized. If this call was intended to change configuration,'
                     ' close the session with hl.stop() first.')
 
+    if default_reference is not None:
+        warnings.warn('Using hl.init with a default_reference argument is deprecated. '
+                      'To set a default reference genome after initializing hail, '
+                      'call `hl.default_reference` with an argument to set the '
+                      'default reference genome.')
+    else:
+        default_reference = 'GRCh37'
+
     backend = choose_backend(backend)
 
     if backend == 'service':
@@ -826,7 +836,8 @@ async def _async_current_backend() -> Backend:
     return (await Env._async_hc())._backend
 
 
-def default_reference(new_default_reference: Optional[ReferenceGenome] = None) -> Optional[ReferenceGenome]:
+@typecheck(new_default_reference=nullable(reference_genome_type))
+def default_reference(new_default_reference=None) -> Optional[ReferenceGenome]:
     """With no argument, returns the default reference genome (``'GRCh37'`` by default).
     With an argument, sets the default reference genome to the argument.