xml_reflection: First step to enable deprecation of public access

Author: EricCousineau-TRI

src/urdf_parser_py/__init__.py

@@ -0,0 +1,68 @@
+"""
+Python implementation of the URDF parser.
+"""
+
+import functools
+import warnings
+
+
+class _DeprecatedDescriptor(object):
+    def __init__(self, attr):
+        self._attr = attr
+
+    def _warn(self):
+        raise NotImplemented
+
+    def __get__(self, obj, objtype):
+        self._warn()
+        if obj is None:
+            return getattr(objtype, self._attr)
+        else:
+            return getattr(obj, self._attr)
+
+    def __set__(self, obj, value):
+        self._warn()
+        setattr(obj, self._attr, value)
+
+    def __del__(self, obj):
+        self._warn()
+        delattr(obj, self._attr)
+
+
+class _NowPrivateDescriptor(_DeprecatedDescriptor):
+    # Implements the descriptor interface to warn about deprecated access.
+    def __init__(self, private):
+        _DeprecatedDescriptor.__init__(self, private)
+        self._private = private
+        self._old_public = self._private.lstrip('_')
+        self.__doc__ = "Deprecated propery '{}'".format(self._old_public)
+
+    def _warn(self):
+        warnings.warn(
+            "'{}' is deprecated, and will be removed in future releases."
+                .format(self._old_public),
+            category=DeprecationWarning, stacklevel=1)
+
+
+def _now_private_property(private):
+    # Indicates that a property (or method) is now private.
+    return _NowPrivateDescriptor(private)
+
+
+class _RenamedDescriptor(_DeprecatedDescriptor):
+    # Implements the descriptor interface to warn about deprecated access.
+    def __init__(self, old, new):
+        _DeprecatedDescriptor.__init__(self, new)
+        self._old = old
+        self._new = new
+        self.__doc__ = "Deprecated propery '{}'".format(self._old)
+
+    def _warn(self):
+        warnings.warn(
+            "'{}' is deprecated, please use '{}' instead.".format(
+                self._old, self._new),
+            category=DeprecationWarning, stacklevel=1)
+
+
+def _renamed_property(old, new):
+    return _RenamedDescriptor(old, new)

src/urdf_parser_py/_xml_reflection.py

@@ -0,0 +1,5 @@
+# TODO(eacousineau): Move all symbols from `.xml_reflection` into here.
+from urdf_parser_py.xml_reflection.basics import *
+# Import full module so that tests can easily monkey patch `on_error`.
+from urdf_parser_py.xml_reflection import core
+from urdf_parser_py.xml_reflection.core import *

src/urdf_parser_py/xml_reflection/__init__.py

@@ -1 +1,2 @@
+# TODO(eacousineau): Deprecate public access.
 from urdf_parser_py.xml_reflection.core import *

src/urdf_parser_py/xml_reflection/basics.py

@@ -1,7 +1,28 @@
-import string
-import yaml
 import collections
+import string
+# TODO(eacousineau): Leverage tfoote's PR.
+from xml.etree.ElementTree import ElementTree
+
 from lxml import etree
+import yaml
+
+# TODO(eacousineau): Deprecate public access.
+from urdf_parser_py import _now_private_property
+
+__all__ = [
+    "xml_string",
+    "dict_sub",
+    "node_add",
+    "pfloat",
+    "xml_children",
+    "isstring",
+    "to_yaml",
+    "SelectiveReflection",
+    "YamlReflection",
+    # Backwards compatibility.
+    "etree",
+]
+
 
 def xml_string(rootXml, addHeader=True):
     # Meh
@@ -74,13 +95,15 @@ def to_yaml(obj):
 
 
 class SelectiveReflection(object):
-    def get_refl_vars(self):
+    def _get_refl_vars(self):
         return list(vars(self).keys())
 
+    get_refl_vars = _now_private_property('_get_refl_vars')
+
 
 class YamlReflection(SelectiveReflection):
     def to_yaml(self):
-        raw = dict((var, getattr(self, var)) for var in self.get_refl_vars())
+        raw = dict((var, getattr(self, var)) for var in self._get_refl_vars())
         return to_yaml(raw)
 
     def __str__(self):