Deprecate methods for pickling/unpickling on BuildEnvironment

CHANGES

@@ -62,6 +62,12 @@ Deprecated
 * ``sphinx.writers.latex.LaTeXWriter.restrict_footnote()`` is deprecated
 * ``sphinx.writers.latex.LaTeXWriter.unrestrict_footnote()`` is deprecated
 * ``LaTeXWriter.bibitems`` is deprecated
+* ``BuildEnvironment.load()`` is deprecated
+* ``BuildEnvironment.loads()`` is deprecated
+* ``BuildEnvironment.frompickle()`` is deprecated
+* ``BuildEnvironment.dump()`` is deprecated
+* ``BuildEnvironment.dumps()`` is deprecated
+* ``BuildEnvironment.topickle()`` is deprecated
 
 For more details, see `deprecation APIs list
 <http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_

doc/extdev/index.rst

@@ -192,6 +192,36 @@ The following is a list of deprecated interface.
      - 3.0
      - :meth:`~sphinx.application.Sphinx.add_domain()`
 
+   * - ``BuildEnvironment.load()``
+     - 1.8
+     - 3.0
+     - ``pickle.load()``
+
+   * - ``BuildEnvironment.loads()``
+     - 1.8
+     - 3.0
+     - ``pickle.loads()``
+
+   * - ``BuildEnvironment.frompickle()``
+     - 1.8
+     - 3.0
+     - ``pickle.load()``
+
+   * - ``BuildEnvironment.dump()``
+     - 1.8
+     - 3.0
+     - ``pickle.dump()``
+
+   * - ``BuildEnvironment.dumps()``
+     - 1.8
+     - 3.0
+     - ``pickle.dumps()``
+
+   * - ``BuildEnvironment.topickle()``
+     - 1.8
+     - 3.0
+     - ``pickle.dump()``
+
    * - ``BuildEnvironment._nitpick_ignore``
      - 1.8
      - 3.0

sphinx/application.py

@@ -22,6 +22,7 @@ from os import path
 
 from docutils.parsers.rst import Directive, directives, roles
 from six import itervalues
+from six.moves import cPickle as pickle
 from six.moves import cStringIO
 
 import sphinx
@@ -291,7 +292,10 @@ class Sphinx(object):
         else:
             try:
                 logger.info(bold(__('loading pickled environment... ')), nonl=True)
-                self.env = BuildEnvironment.frompickle(filename, self)
+                with open(filename, 'rb') as f:
+                    self.env = pickle.load(f)
+                    self.env.app = self
+                    self.env.config.values = self.config.values
                 needed, reason = self.env.need_refresh(self)
                 if needed:
                     raise IOError(reason)

sphinx/builders/__init__.py

@@ -17,7 +17,6 @@ from docutils import nodes
 from six.moves import cPickle as pickle
 
 from sphinx.deprecation import RemovedInSphinx20Warning
-from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import SphinxError
 from sphinx.io import read_doc
@@ -372,7 +371,8 @@ class Builder(object):
             # save the environment
             from sphinx.application import ENV_PICKLE_FILENAME
             logger.info(bold(__('pickling environment... ')), nonl=True)
-            self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME))
+            with open(path.join(self.doctreedir, ENV_PICKLE_FILENAME), 'wb') as f:
+                pickle.dump(self.env, f, pickle.HIGHEST_PROTOCOL)
             logger.info(__('done'))
 
             # global actions
@@ -492,16 +492,16 @@ class Builder(object):
             self.env.clear_doc(docname)
 
         def read_process(docs):
-            # type: (List[unicode]) -> unicode
+            # type: (List[unicode]) -> bytes
             self.env.app = self.app
             for docname in docs:
                 self.read_doc(docname)
             # allow pickling self to send it back
-            return BuildEnvironment.dumps(self.env)
+            return pickle.dumps(self.env, pickle.HIGHEST_PROTOCOL)
 
         def merge(docs, otherenv):
-            # type: (List[unicode], unicode) -> None
-            env = BuildEnvironment.loads(otherenv)
+            # type: (List[unicode], bytes) -> None
+            env = pickle.loads(otherenv)
             self.env.merge_info_from(docs, env, self.app)
 
         tasks = ParallelTasks(nproc)

sphinx/environment/__init__.py

@@ -91,51 +91,6 @@ class BuildEnvironment(object):
 
     domains = None  # type: Dict[unicode, Domain]
 
-    # --------- ENVIRONMENT PERSISTENCE ----------------------------------------
-
-    @staticmethod
-    def load(f, app=None):
-        # type: (IO, Sphinx) -> BuildEnvironment
-        try:
-            env = pickle.load(f)
-        except Exception as exc:
-            # This can happen for example when the pickle is from a
-            # different version of Sphinx.
-            raise IOError(exc)
-        if app:
-            env.app = app
-            env.config.values = app.config.values
-        return env
-
-    @classmethod
-    def loads(cls, string, app=None):
-        # type: (unicode, Sphinx) -> BuildEnvironment
-        io = BytesIO(string)
-        return cls.load(io, app)
-
-    @classmethod
-    def frompickle(cls, filename, app):
-        # type: (unicode, Sphinx) -> BuildEnvironment
-        with open(filename, 'rb') as f:
-            return cls.load(f, app)
-
-    @staticmethod
-    def dump(env, f):
-        # type: (BuildEnvironment, IO) -> None
-        pickle.dump(env, f, pickle.HIGHEST_PROTOCOL)
-
-    @classmethod
-    def dumps(cls, env):
-        # type: (BuildEnvironment) -> unicode
-        io = BytesIO()
-        cls.dump(env, io)
-        return io.getvalue()
-
-    def topickle(self, filename):
-        # type: (unicode) -> None
-        with open(filename, 'wb') as f:
-            self.dump(self, f)
-
     # --------- ENVIRONMENT INITIALIZATION -------------------------------------
 
     def __init__(self, app):
@@ -816,3 +771,64 @@ class BuildEnvironment(object):
                       'Please use config.nitpick_ignore instead.',
                       RemovedInSphinx30Warning)
         return self.config.nitpick_ignore
+
+    @staticmethod
+    def load(f, app=None):
+        # type: (IO, Sphinx) -> BuildEnvironment
+        warnings.warn('BuildEnvironment.load() is deprecated. '
+                      'Please use pickle.load() instead.',
+                      RemovedInSphinx30Warning)
+        try:
+            env = pickle.load(f)
+        except Exception as exc:
+            # This can happen for example when the pickle is from a
+            # different version of Sphinx.
+            raise IOError(exc)
+        if app:
+            env.app = app
+            env.config.values = app.config.values
+        return env
+
+    @classmethod
+    def loads(cls, string, app=None):
+        # type: (unicode, Sphinx) -> BuildEnvironment
+        warnings.warn('BuildEnvironment.loads() is deprecated. '
+                      'Please use pickle.loads() instead.',
+                      RemovedInSphinx30Warning)
+        io = BytesIO(string)
+        return cls.load(io, app)
+
+    @classmethod
+    def frompickle(cls, filename, app):
+        # type: (unicode, Sphinx) -> BuildEnvironment
+        warnings.warn('BuildEnvironment.frompickle() is deprecated. '
+                      'Please use pickle.load() instead.',
+                      RemovedInSphinx30Warning)
+        with open(filename, 'rb') as f:
+            return cls.load(f, app)
+
+    @staticmethod
+    def dump(env, f):
+        # type: (BuildEnvironment, IO) -> None
+        warnings.warn('BuildEnvironment.dump() is deprecated. '
+                      'Please use pickle.dump() instead.',
+                      RemovedInSphinx30Warning)
+        pickle.dump(env, f, pickle.HIGHEST_PROTOCOL)
+
+    @classmethod
+    def dumps(cls, env):
+        # type: (BuildEnvironment) -> unicode
+        warnings.warn('BuildEnvironment.dumps() is deprecated. '
+                      'Please use pickle.dumps() instead.',
+                      RemovedInSphinx30Warning)
+        io = BytesIO()
+        cls.dump(env, io)
+        return io.getvalue()
+
+    def topickle(self, filename):
+        # type: (unicode) -> None
+        warnings.warn('env.topickle() is deprecated. '
+                      'Please use pickle.dump() instead.',
+                      RemovedInSphinx30Warning)
+        with open(filename, 'wb') as f:
+            self.dump(self, f)