Repository: marshmallow-code/marshmallow

Issue:
Nested single string 'only' behavior edge case
When using Nested fields, passing a single string field to `only` does not work as expected when applying a transform with `on_bind_field`


```python
from marshmallow import fields, Schema


def test_nested_only_on_bind_field():

    def to_camel_case(snake_str):
        components = snake_str.split('_')
        return components[0] + ''.join(x.title() for x in components[1:])

    class CamelCaseSchema(Schema):
        def on_bind_field(self, field_name, field_obj):
            field_obj.data_key = to_camel_case(field_name)

    class UserRoleSchema(CamelCaseSchema):
        user_id = fields.Number()
        role_name = fields.String()

    class UserSchema(CamelCaseSchema):
        id = fields.Number()
        roles = fields.Nested(UserRoleSchema, many=True, only='role_name')

    user = {
        'id': 1,
        'roles': [
            {'user_id': 1, 'role_name': 'admin'},
            {'user_id': 1, 'role_name': 'test'},
        ]
    }

    serialized_user = UserSchema().dumps(user)

    assert serialized_user == {"id": 1, "roles": ["admin", "test"]}
```

This results in the following error:

```
/env/lib/python3.6/site-packages/marshmallow/schema.py:476: in dumps
    serialized = self.dump(obj, many=many, update_fields=update_fields)
/env/lib/python3.6/site-packages/marshmallow/schema.py:428: in dump
    **kwargs
/env/lib/python3.6/site-packages/marshmallow/marshalling.py:147: in serialize
    index=(index if index_errors else None)
/env/lib/python3.6/site-packages/marshmallow/marshalling.py:68: in call_and_store
    value = getter_func(data)
/env/lib/python3.6/site-packages/marshmallow/marshalling.py:141: in <lambda>
    getter = lambda d: field_obj.serialize(attr_name, d, accessor=accessor)
/env/lib/python3.6/site-packages/marshmallow/fields.py:250: in serialize
    return self._serialize(value, attr, obj)
/env/lib/python3.6/site-packages/marshmallow/fields.py:455: in _serialize
    return utils.pluck(ret, key=self.only)
/env/lib/python3.6/site-packages/marshmallow/utils.py:318: in pluck
    return [d[key] for d in dictlist]
KeyError: 'role_name'
```

This seems to be only affecting the single string case, as passing `only=['role_name']` works as expected.

Discussion:
lafrech: Nothing really mandatory in my comments. This looks pretty good to me.

Thanks @deckar01 for tackling this.
lafrech: When this is merged, we can add a test to raise `StringNotCollectionError` if `only` or `exclude` is passed to `Nested` as string, not list of strings.

See https://github.com/marshmallow-code/marshmallow/pull/896.
sloria: Looks good to me as well. @deckar01 Can you please get this up to date? Once that's done, feel free to merge.

Patch:
diff --git a/docs/nesting.rst b/docs/nesting.rst
index b5afbaf1..06f2f309 100644
--- a/docs/nesting.rst
+++ b/docs/nesting.rst
@@ -99,32 +99,30 @@ You can represent the attributes of deeply nested objects using dot delimiters.
     #     }
     # }
 
-.. note::
+You can replace nested data with a single value (or flat list of values if ``many=True``) using the :class:`Pluck <marshmallow.fields.Pluck>` field.
 
-    If you pass in a string field name to ``only``, only a single value (or flat list of values if ``many=True``) will be (de)serialized.
+.. code-block:: python
+    :emphasize-lines: 4, 11, 18
 
-    .. code-block:: python
-        :emphasize-lines: 4, 11, 18
-
-        class UserSchema(Schema):
-            name = fields.String()
-            email = fields.Email()
-            friends = fields.Nested('self', only='name', many=True)
-        # ... create ``user`` ...
-        serialized_data = UserSchema().dump(user)
-        pprint(serialized_data)
-        # {
-        #     "name": "Steve",
-        #     "email": "steve@example.com",
-        #     "friends": ["Mike", "Joe"]
-        # }
-        deserialized_data = UserSchema().load(result)
-        pprint(deserialized_data)
-        # {
-        #     "name": "Steve",
-        #     "email": "steve@example.com",
-        #     "friends": [{"name": "Mike"}, {"name": "Joe"}]
-        # }
+    class UserSchema(Schema):
+        name = fields.String()
+        email = fields.Email()
+        friends = fields.Pluck('self', 'name', many=True)
+    # ... create ``user`` ...
+    serialized_data = UserSchema().dump(user)
+    pprint(serialized_data)
+    # {
+    #     "name": "Steve",
+    #     "email": "steve@example.com",
+    #     "friends": ["Mike", "Joe"]
+    # }
+    deserialized_data = UserSchema().load(result)
+    pprint(deserialized_data)
+    # {
+    #     "name": "Steve",
+    #     "email": "steve@example.com",
+    #     "friends": [{"name": "Mike"}, {"name": "Joe"}]
+    # }
 
 
 You can also exclude fields by passing in an ``exclude`` list. This argument also allows representing the attributes of deeply nested objects using dot delimiters.
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index ad0bee81..71e8eb20 100644
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -569,6 +569,24 @@ Processors that mutate the data should be updated to also return it.
             in_data['slug'] = in_data['slug'].lower().strip().replace(' ', '-')
             return in_data
 
+The Nested field no longer supports plucking
+********************************************
+
+In marshmallow 2.x, when a string was passed to a ``Nested`` field's ```only`` parameter, the field would be plucked. In marshmallow 3.x, the ``Pluck`` field must be used instead.
+
+
+.. code-block:: python
+
+    # 2.x
+    class UserSchema(Schema):
+        name = fields.Str()
+        friends = fields.Nested('self', many=True, only='name')
+
+    # 3.x
+    class UserSchema(Schema):
+        name = fields.Str()
+        friends = fields.Pluck('self', 'name', many=True)
+
 
 
 Upgrading to 2.3
diff --git a/marshmallow/fields.py b/marshmallow/fields.py
index d04bbedc..7b734697 100755
--- a/marshmallow/fields.py
+++ b/marshmallow/fields.py
@@ -349,7 +349,7 @@ class Nested(Field):
 
         user = fields.Nested(UserSchema)
         user2 = fields.Nested('UserSchema')  # Equivalent to above
-        collaborators = fields.Nested(UserSchema, many=True, only='id')
+        collaborators = fields.Nested(UserSchema, many=True, only=('id',))
         parent = fields.Nested('self')
 
     When passing a `Schema <marshmallow.Schema>` instance as the first argument,
@@ -401,45 +401,29 @@ class Nested(Field):
             Renamed from `serializer` to `schema`
         """
         if not self.__schema:
-            # Ensure that only parameter is a tuple
-            if isinstance(self.only, basestring):
-                only = (self.only,)
-            else:
-                only = self.only
-
             # Inherit context from parent.
             context = getattr(self.parent, 'context', {})
             if isinstance(self.nested, SchemaABC):
                 self.__schema = self.nested
                 self.__schema.context.update(context)
-            elif isinstance(self.nested, type) and \
-                    issubclass(self.nested, SchemaABC):
-                self.__schema = self.nested(
+            else:
+                if isinstance(self.nested, type) and issubclass(self.nested, SchemaABC):
+                    schema_class = self.nested
+                elif not isinstance(self.nested, basestring):
+                    raise ValueError(
+                        'Nested fields must be passed a '
+                        'Schema, not {0}.'.format(self.nested.__class__),
+                    )
+                elif self.nested == 'self':
+                    schema_class = self.parent.__class__
+                else:
+                    schema_class = class_registry.get_class(self.nested)
+                self.__schema = schema_class(
                     many=self.many,
-                    only=only, exclude=self.exclude, context=context,
+                    only=self.only, exclude=self.exclude, context=context,
                     load_only=self._nested_normalized_option('load_only'),
                     dump_only=self._nested_normalized_option('dump_only'),
                 )
-            elif isinstance(self.nested, basestring):
-                if self.nested == 'self':
-                    parent_class = self.parent.__class__
-                    self.__schema = parent_class(
-                        many=self.many, only=only,
-                        exclude=self.exclude, context=context,
-                        load_only=self._nested_normalized_option('load_only'),
-                        dump_only=self._nested_normalized_option('dump_only'),
-                    )
-                else:
-                    schema_class = class_registry.get_class(self.nested)
-                    self.__schema = schema_class(
-                        many=self.many,
-                        only=only, exclude=self.exclude, context=context,
-                        load_only=self._nested_normalized_option('load_only'),
-                        dump_only=self._nested_normalized_option('dump_only'),
-                    )
-            else:
-                raise ValueError('Nested fields must be passed a '
-                                 'Schema, not {0}.'.format(self.nested.__class__))
             self.__schema.ordered = getattr(self.parent, 'ordered', False)
         return self.__schema
 
@@ -459,37 +443,65 @@ class Nested(Field):
             schema._update_fields(obj=nested_obj, many=self.many)
             self.__updated_fields = True
         try:
-            ret = schema.dump(
+            return schema.dump(
                 nested_obj, many=self.many,
                 update_fields=not self.__updated_fields,
             )
         except ValidationError as exc:
             raise ValidationError(exc.messages, data=obj, valid_data=exc.valid_data)
-        finally:
-            if isinstance(self.only, basestring):  # self.only is a field name
-                only_field = self.schema.fields[self.only]
-                key = only_field.data_key or self.only
-                if self.many:
-                    return utils.pluck(ret, key=key)
-                else:
-                    return ret[key]
-        return ret
 
-    def _deserialize(self, value, attr, data):
+    def _test_collection(self, value):
         if self.many and not utils.is_collection(value):
             self.fail('type', input=value, type=value.__class__.__name__)
 
-        if isinstance(self.only, basestring):  # self.only is a field name
-            if self.many:
-                value = [{self.only: v} for v in value]
-            else:
-                value = {self.only: value}
+    def _load(self, value, data):
         try:
             valid_data = self.schema.load(value, unknown=self.unknown)
         except ValidationError as exc:
             raise ValidationError(exc.messages, data=data, valid_data=exc.valid_data)
         return valid_data
 
+    def _deserialize(self, value, attr, data):
+        self._test_collection(value)
+        return self._load(value, data)
+
+
+class Pluck(Nested):
+    """Allows you to replace nested data with one of the data's fields.
+
+    Examples: ::
+
+        user = fields.Pluck(UserSchema, 'name')
+        collaborators = fields.Pluck(UserSchema, 'id', many=True)
+        parent = fields.Pluck('self', 'name')
+
+    :param Schema nested: The Schema class or class name (string)
+        to nest, or ``"self"`` to nest the :class:`Schema` within itself.
+    :param str field_name:
+    :param kwargs: The same keyword arguments that :class:`Nested` receives.
+    """
+    def __init__(self, nested, field_name, **kwargs):
+        super(Pluck, self).__init__(nested, only=(field_name,), **kwargs)
+        self.field_name = field_name
+
+    def _serialize(self, nested_obj, attr, obj):
+        ret = super(Pluck, self)._serialize(nested_obj, attr, obj)
+        only_field = self.schema.fields[self.field_name]
+        data_key = only_field.data_key or self.field_name
+        key = ''.join([self.schema.prefix or '', data_key])
+        if self.many:
+            return utils.pluck(ret, key=key)
+        else:
+            return ret[key]
+
+    def _deserialize(self, value, attr, data):
+        self._test_collection(value)
+        if self.many:
+            value = [{self.field_name: v} for v in value]
+        else:
+            value = {self.field_name: value}
+        return self._load(value, data)
+
 
 class List(Field):
     """A list field, composed with another `Field` class or


Test patch:
diff --git a/tests/test_deserialization.py b/tests/test_deserialization.py
index d842fc5d..54f643b2 100644
--- a/tests/test_deserialization.py
+++ b/tests/test_deserialization.py
@@ -1026,7 +1026,7 @@ class TestSchemaDeserialization:
 
         class MainSchema(Schema):
             pk = fields.Str()
-            child = fields.Nested(ANestedSchema, only='pk')
+            child = fields.Pluck(ANestedSchema, 'pk')
 
         sch = MainSchema()
         result = sch.load({'pk': '123', 'child': '456'})
@@ -1038,7 +1038,7 @@ class TestSchemaDeserialization:
 
         class MainSchema(Schema):
             pk = fields.Str()
-            children = fields.Nested(ANestedSchema, only='pk', many=True)
+            children = fields.Pluck(ANestedSchema, 'pk', many=True)
 
         sch = MainSchema()
         result = sch.load({'pk': '123', 'children': ['456', '789']})
diff --git a/tests/test_schema.py b/tests/test_schema.py
index 01f2e318..34474580 100755
--- a/tests/test_schema.py
+++ b/tests/test_schema.py
@@ -1717,23 +1717,6 @@ class TestNestedSchema:
         )
         return blog
 
-    def test_flat_nested(self, blog):
-        class FlatBlogSchema(Schema):
-            name = fields.String()
-            user = fields.Nested(UserSchema, only='name')
-            collaborators = fields.Nested(UserSchema, only='name', many=True)
-        s = FlatBlogSchema()
-        data = s.dump(blog)
-        assert data['user'] == blog.user.name
-        for i, name in enumerate(data['collaborators']):
-            assert name == blog.collaborators[i].name
-
-    # Regression test for https://github.com/marshmallow-code/marshmallow/issues/800
-    def test_flat_nested_with_data_key(self, blog):
-        class UserSchema(Schema):
-            name = fields.String(data_key='username')
-            age = fields.Int()
-
         class FlatBlogSchema(Schema):
             name = fields.String()
             user = fields.Nested(UserSchema, only='name')
@@ -1772,15 +1755,6 @@ class TestNestedSchema:
         result2 = s2.dump({'foo': None})
         assert result2['foo'] is None
 
-    def test_flat_nested2(self, blog):
-        class FlatBlogSchema(Schema):
-            name = fields.String()
-            collaborators = fields.Nested(UserSchema, many=True, only='uid')
-
-        s = FlatBlogSchema()
-        data = s.dump(blog)
-        assert data['collaborators'][0] == str(blog.collaborators[0].uid)
-
     def test_nested_field_does_not_validate_required(self):
         class BlogRequiredSchema(Schema):
             user = fields.Nested(UserSchema, required=True)
@@ -1998,6 +1972,44 @@ class TestNestedSchema:
         assert errors == {'foo': {'foo': ['Not a valid integer.']}}
 
 
+class TestPluckSchema:
+
+    def blog(self):
+        user = User(name='Monty', age=81)
+        col1 = User(name='Mick', age=123)
+        col2 = User(name='Keith', age=456)
+        blog = Blog(
+            user=user, categories=['humor', 'violence'],
+            collaborators=[col1, col2],
+        )
+        return blog
+
+    def test_pluck(self, blog):
+        class FlatBlogSchema(Schema):
+            user = fields.Pluck(UserSchema, 'name')
+            collaborators = fields.Pluck(UserSchema, 'name', many=True)
+        s = FlatBlogSchema()
+        data = s.dump(blog)
+        assert data['user'] == blog.user.name
+        for i, name in enumerate(data['collaborators']):
+            assert name == blog.collaborators[i].name
+
+    # Regression test for https://github.com/marshmallow-code/marshmallow/issues/800
+    def test_pluck_with_data_key(self, blog):
+        class UserSchema(Schema):
+            name = fields.String(data_key='username')
+            age = fields.Int()
+
+        class FlatBlogSchema(Schema):
+            user = fields.Pluck(UserSchema, 'name')
+            collaborators = fields.Pluck(UserSchema, 'name', many=True)
+        s = FlatBlogSchema()
+        data = s.dump(blog)
+        assert data['user'] == blog.user.name
+        for i, name in enumerate(data['collaborators']):
+            assert name == blog.collaborators[i].name
+
+
 class TestSelfReference:
 
     @pytest.fixture
@@ -2054,13 +2066,10 @@ class TestSelfReference:
         assert data['employer']['name'] == employer.name
         assert 'age' not in data['employer']
 
-    def test_multiple_nested_self_fields(self, user):
+    def test_multiple_pluck_self_field(self, user):
         class MultipleSelfSchema(Schema):
-            emp = fields.Nested('self', only='name', attribute='employer')
-            rels = fields.Nested(
-                'self', only='name',
-                many=True, attribute='relatives',
-            )
+            emp = fields.Pluck('self', 'name', attribute='employer')
+            rels = fields.Pluck('self', 'name', many=True, attribute='relatives')
 
             class Meta:
                 fields = ('name', 'emp', 'rels')