Deprecate metadata as additional field kwargs

Add `metadata=...` as an explicit keyword argument, which dict-ifies a
mapping, and treat any additional kwargs as "added metadata" which
triggers a deprecation warning.

This is backwards compatible *except* in the case where someone is
already using `metadata` as the name of a metadata field. Which is
probably never intentional if it's done at all.

resolves marshmallow-code#1350

CHANGELOG.rst

@@ -1,6 +1,15 @@
 Changelog
 ---------
 
+3.10.0 (Unreleased)
+*******************
+
+Deprecations:
+
+- Passing field metadata via keyword arguments is deprecated and will be
+  removed in marshmallow 4 (:issue:`1350`). Use the explicit `metadata=...`
+  argument instead.
+
 3.9.1 (2020-11-07)
 ******************
 

src/marshmallow/fields.py

@@ -101,7 +101,7 @@ class Field(FieldABC):
         its value will be present in the deserialized object. In the context of an
         HTTP API, this effectively marks the field as "read-only".
     :param dict error_messages: Overrides for `Field.default_error_messages`.
-    :param metadata: Extra arguments to be stored as metadata.
+    :param metadata: Extra information to be stored as field metadata.
 
     .. versionchanged:: 2.0.0
         Removed `error` parameter. Use ``error_messages`` instead.
@@ -160,7 +160,8 @@ def __init__(
         load_only: bool = False,
         dump_only: bool = False,
         error_messages: typing.Optional[typing.Dict[str, str]] = None,
-        **metadata
+        metadata: typing.Optional[typing.Mapping[str, typing.Any]] = None,
+        **additional_metadata
     ) -> None:
         self.default = default
         self.attribute = attribute
@@ -187,7 +188,19 @@ def __init__(
             raise ValueError("'missing' must not be set for required fields.")
         self.required = required
         self.missing = missing
-        self.metadata = metadata
+
+        # intentionally shallow-copy so that more data can be added without changing
+        # the original mapping object, but objects can be referenced from field
+        # metadata
+        self.metadata = dict(metadata) if metadata is not None else {}
+        if additional_metadata:
+            self.metadata.update(additional_metadata)
+            warnings.warn(
+                "Passing field metadata as a keyword arg is deprecated. Use the "
+                "explicit `metadata=...` argument instead.",
+                RemovedInMarshmallow4Warning,
+            )
+
         self._creation_index = Field._creation_index
         Field._creation_index += 1