Moved global network settings into the network module (#695)

Author: snowman2

.isort.cfg

@@ -1,6 +1,6 @@
 [settings]
 line_length=88
 multi_line_output=3
-known_third_party=mock,numpy,pkg_resources,pytest,setuptools,xarray,pandas
+known_third_party=mock,numpy,pkg_resources,pytest,setuptools,xarray,pandas,certifi
 known_first_party=pyproj,test
 include_trailing_comma=true

docs/api/global_context.rst

@@ -21,15 +21,3 @@ pyproj.set_use_global_context
 -----------------------------
 
 .. autofunction:: pyproj.set_use_global_context
-
-
-pyproj.set_global_context_network
------------------------------------
-
-.. autofunction:: pyproj.set_global_context_network
-
-
-pyproj.is_global_context_network_enabled
-------------------------------------------
-
-.. autofunction:: pyproj.is_global_context_network_enabled

docs/api/network.rst

@@ -4,6 +4,18 @@ PROJ Network Settings
 ======================
 
 
+pyproj.network.set_network_enabled
+-----------------------------------
+
+.. autofunction:: pyproj.network.set_network_enabled
+
+
+pyproj.network.is_network_enabled
+----------------------------------
+
+.. autofunction:: pyproj.network.is_network_enabled
+
+
 pyproj.network.set_ca_bundle_path
 ----------------------------------
 

docs/history.rst

@@ -22,7 +22,7 @@ Change Log
 * ENH: Added ability to use global context (issue #661)
 * ENH: Add support for temporal CRS CF coordinate system (issue #672)
 * BUG: Fix handling of polygon holes when calculating area in Geod (pull #686)
-* ENH: Added :func:`pyproj.network.set_ca_bundle_path` (pull #691)
+* ENH: Added :ref:`network` (#675, #691, #695)
 
 2.6.1
 ~~~~~

pyproj/__init__.py

@@ -49,8 +49,6 @@
 import pyproj.network
 from pyproj._datadir import (  # noqa: F401
     _pyproj_global_context_initialize,
-    is_global_context_network_enabled,
-    set_global_context_network,
     set_use_global_context,
 )
 from pyproj._list import (  # noqa: F401

pyproj/_datadir.pyi

@@ -4,5 +4,3 @@ def _pyproj_global_context_initialize() -> None: ...
 def get_user_data_dir(create: bool = False) -> str: ...
 def _global_context_set_data_dir() -> None: ...
 def set_use_global_context(active: Optional[bool] = None) -> None: ...
-def set_global_context_network(active: Optional[bool] = None) -> None: ...
-def is_global_context_network_enabled() -> bool: ...

pyproj/_datadir.pyx

@@ -28,8 +28,7 @@ def set_use_global_context(active=None):
                  through the duration of each python session and is closed
                  once the program terminates.
 
-    .. note:: You can change the network settings with
-              :func:`pyproj.set_global_context_network`.
+    .. note:: To modify network settings see: :ref:`network`.
 
     Parameters
     ----------
@@ -46,46 +45,6 @@ def set_use_global_context(active=None):
     proj_context_set_autoclose_database(NULL, not _USE_GLOBAL_CONTEXT)
 
 
-def set_global_context_network(active=None):
-    """
-    .. versionadded:: 3.0.0
-
-    Manages whether PROJ network is enabled on the global context.
-
-    .. note:: You can activate the global context with
-              :func:`pyproj.set_use_global_context` or with
-              the PYPROJ_GLOBAL_CONTEXT environment variable.
-
-    Parameters
-    ----------
-    active: bool, optional
-        Default is None, which uses the system defaults for networking.
-        If True, it will force the use of network for grids regardless of
-        any other network setting. If False, it will force disable use of
-        network for grids regardless of any other network setting.
-    """
-    if active is None:
-        # in the case of the global context, need to reset network
-        # setting based on the environment variable every time if None
-        # because it could have been changed by the user previously
-        active = strtobool(os.environ.get("PROJ_NETWORK", "OFF"))
-    pyproj_context_set_enable_network(NULL, bool(active))
-
-
-def is_global_context_network_enabled():
-    """
-    .. versionadded:: 3.0.0
-
-    .. note:: You can activate the global context with
-              :func:`pyproj.set_use_global_context` or with
-              the PYPROJ_GLOBAL_CONTEXT environment variable.
-
-    bool:
-        If the network is enabled on the global context.
-    """
-    return proj_context_is_network_enabled(NULL) == 1
-
-
 def get_user_data_dir(create=False):
     """
     .. versionadded:: 3.0.0

pyproj/_network.pyi

@@ -1 +1,5 @@
+from typing import Optional
+
+def set_network_enabled(active: Optional[bool] = None) -> None: ...
+def is_network_enabled() -> bool: ...
 def _set_ca_bundle_path(ca_bundle_path: str) -> None: ...

pyproj/_network.pyx

@@ -1,5 +1,8 @@
 include "proj.pxi"
 
+import os
+from distutils.util import strtobool
+
 from pyproj.compat import cstrencode
 
 
@@ -14,3 +17,36 @@ def _set_ca_bundle_path(ca_bundle_path):
         The path to the CA Bundle.
     """
     proj_context_set_ca_bundle_path(NULL, cstrencode(ca_bundle_path))
+
+
+def set_network_enabled(active=None):
+    """
+    .. versionadded:: 3.0.0
+
+    Set whether PROJ network is enabled by default. This has the same
+    behavior as the `PROJ_NETWORK` environment variable.
+
+    Parameters
+    ----------
+    active: bool, optional
+        Default is None, which uses the system defaults for networking.
+        If True, it will force the use of network for grids regardless of
+        any other network setting. If False, it will force disable use of
+        network for grids regardless of any other network setting.
+    """
+    if active is None:
+        # in the case of the global context, need to reset network
+        # setting based on the environment variable every time if None
+        # because it could have been changed by the user previously
+        active = strtobool(os.environ.get("PROJ_NETWORK", "OFF"))
+    proj_context_set_enable_network(NULL, bool(active))
+
+
+def is_network_enabled():
+    """
+    .. versionadded:: 3.0.0
+
+    bool:
+        If PROJ network is enabled by default.
+    """
+    return proj_context_is_network_enabled(NULL) == 1

pyproj/network.py

@@ -7,15 +7,19 @@
 
 import certifi
 
-from pyproj._network import _set_ca_bundle_path
+from pyproj._network import (  # noqa: F401
+    _set_ca_bundle_path,
+    is_network_enabled,
+    set_network_enabled,
+)
 
 
 def set_ca_bundle_path(ca_bundle_path: Union[Path, str, bool, None] = None) -> None:
     """
     .. versionadded:: 3.0.0
 
     Sets the path to the CA Bundle used by the `curl`
-    built into PROJ.
+    built into PROJ when PROJ network is enabled..
 
     Environment variables that can be used with PROJ 7.2+:
 

test/conftest.py

@@ -19,11 +19,11 @@ def proj_network_env():
     if not pyproj._datadir._USE_GLOBAL_CONTEXT:
         yield
     else:
-        network = pyproj.is_global_context_network_enabled()
+        network = pyproj.network.is_network_enabled()
         try:
             yield
         finally:
-            pyproj.set_global_context_network(network)
+            pyproj.network.set_network_enabled(network)
 
 
 @contextmanager

test/test_doctest_wrapper.py

@@ -17,7 +17,7 @@ def test_doctests():
 
     with warnings.catch_warnings(), proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=True)
+            pyproj.network.set_network_enabled(active=True)
         warnings.filterwarnings(
             "ignore",
             "You will likely lose important projection information when",

test/test_proj.py

@@ -537,7 +537,7 @@ def test_numpy_bool_kwarg_true():
 def test_network__disable():
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=False)
+            pyproj.network.set_network_enabled(active=False)
         transformer = Proj(3857, network=False)
         assert transformer.is_network_enabled is False
 
@@ -546,15 +546,15 @@ def test_network__disable():
 def test_network__enable():
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=True)
+            pyproj.network.set_network_enabled(active=True)
         transformer = Proj(3857, network=True)
         assert transformer.is_network_enabled is True
 
 
 def test_network__default():
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network()
+            pyproj.network.set_network_enabled()
         transformer = Proj(3857)
         assert transformer.is_network_enabled == (
             os.environ.get("PROJ_NETWORK") == "ON"

test/test_transformer.py

@@ -793,7 +793,7 @@ def test_pipeline_itransform(pipeline_str):
 def test_network__disable(transformer):
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=False)
+            pyproj.network.set_network_enabled(active=False)
         trans = transformer(network=False)
         assert trans.is_network_enabled is False
 
@@ -812,7 +812,7 @@ def test_network__disable(transformer):
 def test_network__enable(transformer):
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=True)
+            pyproj.network.set_network_enabled(active=True)
         trans = transformer(network=True)
         assert trans.is_network_enabled is True
 
@@ -830,7 +830,7 @@ def test_network__enable(transformer):
 def test_network__default(transformer):
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network()
+            pyproj.network.set_network_enabled()
         trans = transformer()
         assert trans.is_network_enabled == (os.environ.get("PROJ_NETWORK") == "ON")
 
@@ -839,7 +839,7 @@ def test_network__default(transformer):
 def test_transformer_group__network_enabled():
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=True)
+            pyproj.network.set_network_enabled(active=True)
         trans_group = TransformerGroup(4326, 2964, network=True)
         assert len(trans_group.unavailable_operations) == 0
         assert len(trans_group.transformers) == 10
@@ -855,7 +855,7 @@ def test_transformer_group__network_enabled():
 def test_transformer_group__network_disabled():
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=False)
+            pyproj.network.set_network_enabled(active=False)
         trans_group = TransformerGroup(4326, 2964, network=False)
         for transformer in trans_group.transformers:
             assert transformer.is_network_enabled is False
@@ -957,7 +957,7 @@ def test_transformer_group__download_grids(get_user_data_dir_mock, tmp_path, cap
     get_user_data_dir_mock.return_value = str(tmp_path)
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=False)
+            pyproj.network.set_network_enabled(active=False)
         trans_group = TransformerGroup(4326, 2964, network=False)
         trans_group.download_grids(verbose=True)
         captured = capsys.readouterr()
@@ -1005,7 +1005,7 @@ def test_transformer_group__download_grids__directory(
 ):
     with proj_network_env():
         if pyproj._datadir._USE_GLOBAL_CONTEXT:
-            pyproj.set_global_context_network(active=False)
+            pyproj.network.set_network_enabled(active=False)
         trans_group = TransformerGroup(4326, 2964, network=False)
         trans_group.download_grids(directory=tmp_path)
         get_user_data_dir_mock.assert_not_called()