Use versionadded and versionchanged in doc

Document in which version new types and functions were added using
".. versionadded:: x.y". Document changes using
".. versionchanged:: x.y."

For base64 module, add the versionadded tag in the module top
docstring, not on each type/function.

I used "git blame" + "git tag --contains=SHA1" to find these version,
and then I checked manually each version.

Change-Id: I4a891b18064fe7b857a79c57030ff31f7a0370b4
This commit is contained in:
Victor Stinner 2015-10-15 14:31:14 +02:00
parent f09b9b1e4e
commit 2d085d2c17
3 changed files with 48 additions and 8 deletions

View File

@ -13,6 +13,12 @@
# License for the specific language governing permissions and limitations # License for the specific language governing permissions and limitations
# under the License. # under the License.
"""
Utilities to encode and decode Base64.
.. versionadded:: 1.10
"""
from __future__ import absolute_import from __future__ import absolute_import
import base64 import base64

View File

@ -86,6 +86,12 @@ def to_primitive(value, convert_instances=False, convert_datetime=True,
track the depth of the object inspections and don't go too deep. track the depth of the object inspections and don't go too deep.
Therefore, ``convert_instances=True`` is lossy ... be aware. Therefore, ``convert_instances=True`` is lossy ... be aware.
.. versionchanged:: 1.3
Support UUID encoding.
.. versionchanged:: 1.6
Dictionary keys are now also encoded.
""" """
# handle obvious types first - order of basic types determined by running # handle obvious types first - order of basic types determined by running
# full tests on nova project, resulting in the following counts: # full tests on nova project, resulting in the following counts:
@ -178,7 +184,8 @@ def dumps(obj, default=to_primitive, **kwargs):
"""Serialize ``obj`` to a JSON formatted ``str``. """Serialize ``obj`` to a JSON formatted ``str``.
:param obj: object to be serialized :param obj: object to be serialized
:param default: function that returns a serializable version of an object :param default: function that returns a serializable version of an object,
:func:`to_primitive` is used by default.
:param kwargs: extra named parameters, please see documentation \ :param kwargs: extra named parameters, please see documentation \
of `json.dumps <https://docs.python.org/2/library/json.html#basic-usage>`_ of `json.dumps <https://docs.python.org/2/library/json.html#basic-usage>`_
:returns: json formatted string :returns: json formatted string
@ -195,13 +202,14 @@ def dump_as_bytes(obj, default=to_primitive, encoding='utf-8', **kwargs):
"""Serialize ``obj`` to a JSON formatted ``bytes``. """Serialize ``obj`` to a JSON formatted ``bytes``.
:param obj: object to be serialized :param obj: object to be serialized
:param default: function that returns a serializable version of an object :param default: function that returns a serializable version of an object,
:func:`to_primitive` is used by default.
:param encoding: encoding used to encode the serialized JSON output :param encoding: encoding used to encode the serialized JSON output
:param kwargs: extra named parameters, please see documentation \ :param kwargs: extra named parameters, please see documentation \
of `json.dumps <https://docs.python.org/2/library/json.html#basic-usage>`_ of `json.dumps <https://docs.python.org/2/library/json.html#basic-usage>`_
:returns: json formatted string :returns: json formatted string
.. versionadded:: 2.0 .. versionadded:: 1.10
""" """
serialized = dumps(obj, default=default, **kwargs) serialized = dumps(obj, default=default, **kwargs)
if isinstance(serialized, six.text_type): if isinstance(serialized, six.text_type):
@ -215,11 +223,15 @@ def dump(obj, fp, *args, **kwargs):
:param obj: object to be serialized :param obj: object to be serialized
:param fp: a ``.write()``-supporting file-like object :param fp: a ``.write()``-supporting file-like object
:param default: function that returns a serializable version of an object :param default: function that returns a serializable version of an object,
:func:`to_primitive` is used by default.
:param args: extra arguments, please see documentation \ :param args: extra arguments, please see documentation \
of `json.dump <https://docs.python.org/2/library/json.html#basic-usage>`_ of `json.dump <https://docs.python.org/2/library/json.html#basic-usage>`_
:param kwargs: extra named parameters, please see documentation \ :param kwargs: extra named parameters, please see documentation \
of `json.dump <https://docs.python.org/2/library/json.html#basic-usage>`_ of `json.dump <https://docs.python.org/2/library/json.html#basic-usage>`_
.. versionchanged:: 1.3
The *default* parameter now uses :func:`to_primitive` by default.
""" """
default = kwargs.get('default', to_primitive) default = kwargs.get('default', to_primitive)
if is_simplejson: if is_simplejson:

View File

@ -23,6 +23,8 @@ This module provides a few things:
wrapper will automatically use wrapper will automatically use
the :py:attr:`~oslo_serialization.msgpackutils.default_registry` for the :py:attr:`~oslo_serialization.msgpackutils.default_registry` for
you if needed. you if needed.
.. versionadded:: 1.3
''' '''
@ -63,6 +65,8 @@ class HandlerRegistry(object):
it to a list. it to a list.
This may be fixed in: https://github.com/msgpack/msgpack-python/pull/100 This may be fixed in: https://github.com/msgpack/msgpack-python/pull/100
.. versionadded:: 1.5
""" """
# Applications can assign 0 to 127 to store # Applications can assign 0 to 127 to store
@ -309,11 +313,17 @@ This registry has msgpack extensions for the following:
* ``set`` and ``frozenset`` container(s). * ``set`` and ``frozenset`` container(s).
* ``netaddr.IPAddress`` objects (only if ``netaddr`` is importable). * ``netaddr.IPAddress`` objects (only if ``netaddr`` is importable).
* ``xmlrpclib.DateTime`` datetime objects. * ``xmlrpclib.DateTime`` datetime objects.
.. versionadded:: 1.5
""" """
def load(fp, registry=None): def load(fp, registry=None):
"""Deserialize ``fp`` into a Python object.""" """Deserialize ``fp`` into a Python object.
.. versionchanged:: 1.5
Added *registry* parameter.
"""
if registry is None: if registry is None:
registry = default_registry registry = default_registry
# NOTE(harlowja): the reason we can't use the more native msgpack functions # NOTE(harlowja): the reason we can't use the more native msgpack functions
@ -324,7 +334,11 @@ def load(fp, registry=None):
def dump(obj, fp, registry=None): def dump(obj, fp, registry=None):
"""Serialize ``obj`` as a messagepack formatted stream to ``fp``.""" """Serialize ``obj`` as a messagepack formatted stream to ``fp``.
.. versionchanged:: 1.5
Added *registry* parameter.
"""
if registry is None: if registry is None:
registry = default_registry registry = default_registry
return msgpack.pack(obj, fp, return msgpack.pack(obj, fp,
@ -333,7 +347,11 @@ def dump(obj, fp, registry=None):
def dumps(obj, registry=None): def dumps(obj, registry=None):
"""Serialize ``obj`` to a messagepack formatted ``str``.""" """Serialize ``obj`` to a messagepack formatted ``str``.
.. versionchanged:: 1.5
Added *registry* parameter.
"""
if registry is None: if registry is None:
registry = default_registry registry = default_registry
return msgpack.packb(obj, return msgpack.packb(obj,
@ -342,7 +360,11 @@ def dumps(obj, registry=None):
def loads(s, registry=None): def loads(s, registry=None):
"""Deserialize ``s`` messagepack ``str`` into a Python object.""" """Deserialize ``s`` messagepack ``str`` into a Python object.
.. versionchanged:: 1.5
Added *registry* parameter.
"""
if registry is None: if registry is None:
registry = default_registry registry = default_registry
ext_hook = functools.partial(_unserializer, registry) ext_hook = functools.partial(_unserializer, registry)