From d4775be7686fa7eabc2f177d7762a205518f021b Mon Sep 17 00:00:00 2001
From: Ben Steadman <steadmanben1@gmail.com>
Date: Thu, 7 Mar 2019 08:12:39 +0000
Subject: [PATCH 1/3] implement dot_escape kwarg for allowing dot notation in
 non-nested fields

---
 flask_restplus/fields.py      | 22 +++++++++++++++----
 flask_restplus/marshalling.py |  2 ++
 tests/test_fields.py          | 12 +++++++++++
 tests/test_marshalling.py     | 40 +++++++++++++++++++++++++++++++++++
 4 files changed, 72 insertions(+), 4 deletions(-)

diff --git a/flask_restplus/fields.py b/flask_restplus/fields.py
index 7e75700a..83c2a79c 100644
--- a/flask_restplus/fields.py
+++ b/flask_restplus/fields.py
@@ -42,14 +42,22 @@ def is_indexable_but_not_string(obj):
     return not hasattr(obj, "strip") and hasattr(obj, "__iter__")
 
 
-def get_value(key, obj, default=None):
+def get_value(key, obj, default=None, dot_escape=False):
     '''Helper for pulling a keyed value off various types of objects'''
     if isinstance(key, int):
         return _get_value_for_key(key, obj, default)
     elif callable(key):
         return key(obj)
     else:
-        return _get_value_for_keys(key.split('.'), obj, default)
+        keys = (
+            [
+                k.replace("\.", ".")
+                for k in re.split(r"(?<!\\)\.", key)
+            ]
+            if dot_escape
+            else key.split(".")
+        )
+        return _get_value_for_keys(keys, obj, default)
 
 
 def _get_value_for_keys(keys, obj, default):
@@ -113,7 +121,8 @@ class Raw(object):
     __schema_example__ = None
 
     def __init__(self, default=None, attribute=None, title=None, description=None,
-                 required=None, readonly=None, example=None, mask=None, **kwargs):
+                 required=None, readonly=None, example=None, mask=None,
+                 dot_escape=False, **kwargs):
         self.attribute = attribute
         self.default = default
         self.title = title
@@ -122,6 +131,7 @@ def __init__(self, default=None, attribute=None, title=None, description=None,
         self.readonly = readonly
         self.example = example or self.__schema_example__
         self.mask = mask
+        self.dot_escape = dot_escape
 
     def format(self, value):
         '''
@@ -151,7 +161,11 @@ def output(self, key, obj, **kwargs):
         :raises MarshallingError: In case of formatting problem
         '''
 
-        value = get_value(key if self.attribute is None else self.attribute, obj)
+        value = get_value(
+            key if self.attribute is None else self.attribute,
+            obj,
+            dot_escape=self.dot_escape
+        )
 
         if value is None:
             default = self._v('default')
diff --git a/flask_restplus/marshalling.py b/flask_restplus/marshalling.py
index 5284fb14..e0fe277e 100644
--- a/flask_restplus/marshalling.py
+++ b/flask_restplus/marshalling.py
@@ -171,6 +171,8 @@ def __format_field(key, val):
         if isinstance(field, Wildcard):
             has_wildcards['present'] = True
         value = field.output(key, data, ordered=ordered)
+        if field.dot_escape:
+            key = key.replace("\.", ".")
         return (key, value)
 
     items = (
diff --git a/tests/test_fields.py b/tests/test_fields.py
index d0117353..c1646b79 100644
--- a/tests/test_fields.py
+++ b/tests/test_fields.py
@@ -179,6 +179,18 @@ def test_nested_object(self, mocker):
         field = fields.Raw()
         assert field.output('bar.value', foo) == 42
 
+    @pytest.mark.parametrize(
+        "foo,key,val",
+        [
+            ({'not.nested.value': 42}, 'not\.nested\.value', 42),
+            ({'semi': {'nested.value': 42}}, 'semi.nested\.value', 42),
+            ({'completely': {'nested': {'value': 42}}}, 'completely.nested.value', 42),
+        ]
+    )
+    def test_dot_escape(self, foo, key, val):
+        field = fields.Raw(dot_escape=True)
+        assert field.output(key, foo) == val
+
 
 class StringFieldTest(StringTestMixin, BaseFieldTestMixin, FieldTestCase):
     field_class = fields.String
diff --git a/tests/test_marshalling.py b/tests/test_marshalling.py
index 6e971267..53a44225 100644
--- a/tests/test_marshalling.py
+++ b/tests/test_marshalling.py
@@ -166,6 +166,46 @@ def test_marshal_nested(self):
 
         assert output == expected
 
+    def test_marshal_dot_escape(self):
+        model = {
+            'foo\.bar': fields.Raw(dot_escape=True),
+            'baz': fields.Raw,
+        }
+
+        marshal_fields = {
+            'foo.bar': 'bar',
+            'baz': 'foobar',
+        }
+        expected = {
+            'foo.bar': 'bar',
+            'baz': 'foobar',
+        }
+
+        output = marshal(marshal_fields, model)
+
+        assert output == expected
+
+    def test_marshal_dot_escape_partial(self):
+        model = {
+            'foo\.bar.baz': fields.Raw(dot_escape=True),
+            'bat': fields.Raw,
+        }
+
+        marshal_fields = {
+            'foo.bar': {
+                'baz': 'fee'
+            },
+            'bat': 'fye',
+        }
+        expected = {
+            'foo.bar.baz': 'fee',
+            'bat': 'fye',
+        }
+
+        output = marshal(marshal_fields, model)
+
+        assert output == expected
+
     def test_marshal_nested_ordered(self):
         model = OrderedDict([
             ('foo', fields.Raw),

From 8fe73002bc925c769f64c69f641b8c9f583f2fbc Mon Sep 17 00:00:00 2001
From: Ben Steadman <steadmanben1@gmail.com>
Date: Fri, 8 Mar 2019 07:28:12 +0000
Subject: [PATCH 2/3] dot_escape documentation

---
 doc/marshalling.rst           | 52 +++++++++++++++++++++++++++++++++++
 flask_restplus/fields.py      | 21 +++++++++++++-
 flask_restplus/marshalling.py |  9 ++++++
 3 files changed, 81 insertions(+), 1 deletion(-)

diff --git a/doc/marshalling.rst b/doc/marshalling.rst
index 098c9369..0ecc66dc 100644
--- a/doc/marshalling.rst
+++ b/doc/marshalling.rst
@@ -107,6 +107,58 @@ you can specify a default value to return instead of :obj:`None`.
     }
 
 
+Nested Field Names
+------------------
+
+By default, '.' is used as a separator to indicate nested properties when values 
+are fetched from objects:
+
+.. code-block:: python
+
+    data = {
+        'address': {
+            'country': 'UK',
+            'postcode': 'CO1'
+        }
+    }
+
+    model = {
+        'address.country': fields.String,
+        'address.postcode': fields.String,
+    }
+
+    marshal(data, model)
+    {'address.country': 'UK', 'address.postcode': 'CO1'}
+
+If the object to be marshalled has '.' characters within a single field name, 
+nested property access can be prevented by passing `dot_escape=True` and escaping
+the '.' with a backslash:
+
+.. code-block:: python
+
+    data = {
+        'address.country': 'UK',
+        'address.postcode': 'CO1',
+        'user.name': {
+            'first': 'John',
+            'last': 'Smith',
+        }
+    }
+
+    model = {
+        'address\.country': fields.String(dot_escape=True),
+        'address\.postcode': fields.String(dot_escape=True),
+        'user\.name.first': fields.String(dot_escape=True),
+        'user\.name.last': fields.String(dot_escape=True),
+    }
+
+    marshal(data, model)
+    {'address.country': 'UK',
+     'address.postcode': 'CO1',
+     'user.name.first': 'John',
+     'user.name.last': 'Smith'}
+
+
 Custom Fields & Multiple Values
 -------------------------------
 
diff --git a/flask_restplus/fields.py b/flask_restplus/fields.py
index 83c2a79c..622a5fc1 100644
--- a/flask_restplus/fields.py
+++ b/flask_restplus/fields.py
@@ -43,7 +43,24 @@ def is_indexable_but_not_string(obj):
 
 
 def get_value(key, obj, default=None, dot_escape=False):
-    '''Helper for pulling a keyed value off various types of objects'''
+    '''Helper for pulling a keyed value off various types of objects
+
+    :param bool dot_escape: Allow escaping of '.' character in field names to
+        indicate non-nested property access
+
+    >>> data = {'a': 'foo', b: {'c': 'bar', 'd.e': 'baz'}}}
+    >>> get_value('a', data)
+    'foo'
+
+    >>> get_value('b.c', data)
+    'bar'
+
+    >>> get_value('x', data, default='foobar')
+    'foobar'
+
+    >>> get_value('b.d\.e', data, dot_escape=True)
+    'baz'
+    '''
     if isinstance(key, int):
         return _get_value_for_key(key, obj, default)
     elif callable(key):
@@ -112,6 +129,8 @@ class Raw(object):
     :param bool readonly: Is the field read only ? (for documentation purpose)
     :param example: An optional data example (for documentation purpose)
     :param callable mask: An optional mask function to be applied to output
+    :param bool dot_escape: Allow escaping of '.' character in field names to
+        indicate non-nested property access
     '''
     #: The JSON/Swagger schema type
     __schema_type__ = 'object'
diff --git a/flask_restplus/marshalling.py b/flask_restplus/marshalling.py
index e0fe277e..007c00d5 100644
--- a/flask_restplus/marshalling.py
+++ b/flask_restplus/marshalling.py
@@ -149,6 +149,15 @@ def _marshal(data, fields, envelope=None, skip_none=False, mask=None, ordered=Fa
     >>> marshal(data, mfields, skip_none=True, ordered=True)
     OrderedDict([('a', 100)])
 
+    >>> data = { 'a': 100, 'b.c': 'foo', 'd': None }
+    >>> mfields = {
+        'a': fields.Raw,
+        'b\.c': fields.Raw(dot_escape=True),
+        'd': fields.Raw
+    }
+
+    >>> marshal(data, mfields)
+    {'a': 100, 'b.c': 'foo', 'd': None}
     """
     # ugly local import to avoid dependency loop
     from .fields import Wildcard

From b30acdc1f89a14bfd82647031b04440c0e5d089f Mon Sep 17 00:00:00 2001
From: Ben Steadman <steadmanben1@gmail.com>
Date: Fri, 8 Mar 2019 07:46:15 +0000
Subject: [PATCH 3/3] dot_escape CHANGELOG

---
 CHANGELOG.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 7bd08370..3df808cd 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -7,6 +7,7 @@ Current
 -------
 
 - Ensure `basePath` is always a path
+- Add `dot_escape` kwarg to `fields.Raw` to prevent nested property access
 
 0.12.1 (2018-09-28)
 -------------------