From 2d085d2c179960dabf5c271850ea6fd33d169276 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 15 Oct 2015 14:31:14 +0200 Subject: [PATCH] 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 --- oslo_serialization/base64.py | 6 ++++++ oslo_serialization/jsonutils.py | 20 ++++++++++++++++---- oslo_serialization/msgpackutils.py | 30 ++++++++++++++++++++++++++---- 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/oslo_serialization/base64.py b/oslo_serialization/base64.py index 0223f6a..34c8e4e 100644 --- a/oslo_serialization/base64.py +++ b/oslo_serialization/base64.py @@ -13,6 +13,12 @@ # License for the specific language governing permissions and limitations # under the License. +""" +Utilities to encode and decode Base64. + +.. versionadded:: 1.10 +""" + from __future__ import absolute_import import base64 diff --git a/oslo_serialization/jsonutils.py b/oslo_serialization/jsonutils.py index 9fb5483..5bd1f43 100644 --- a/oslo_serialization/jsonutils.py +++ b/oslo_serialization/jsonutils.py @@ -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. 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 # 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``. :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 \ of `json.dumps `_ :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``. :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 kwargs: extra named parameters, please see documentation \ of `json.dumps `_ :returns: json formatted string - .. versionadded:: 2.0 + .. versionadded:: 1.10 """ serialized = dumps(obj, default=default, **kwargs) if isinstance(serialized, six.text_type): @@ -215,11 +223,15 @@ def dump(obj, fp, *args, **kwargs): :param obj: object to be serialized :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 \ of `json.dump `_ :param kwargs: extra named parameters, please see documentation \ of `json.dump `_ + + .. versionchanged:: 1.3 + The *default* parameter now uses :func:`to_primitive` by default. """ default = kwargs.get('default', to_primitive) if is_simplejson: diff --git a/oslo_serialization/msgpackutils.py b/oslo_serialization/msgpackutils.py index 2f87567..b73fd1a 100644 --- a/oslo_serialization/msgpackutils.py +++ b/oslo_serialization/msgpackutils.py @@ -23,6 +23,8 @@ This module provides a few things: wrapper will automatically use the :py:attr:`~oslo_serialization.msgpackutils.default_registry` for you if needed. + +.. versionadded:: 1.3 ''' @@ -63,6 +65,8 @@ class HandlerRegistry(object): it to a list. This may be fixed in: https://github.com/msgpack/msgpack-python/pull/100 + + .. versionadded:: 1.5 """ # 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). * ``netaddr.IPAddress`` objects (only if ``netaddr`` is importable). * ``xmlrpclib.DateTime`` datetime objects. + +.. versionadded:: 1.5 """ 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: registry = default_registry # 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): - """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: registry = default_registry return msgpack.pack(obj, fp, @@ -333,7 +347,11 @@ def dump(obj, fp, 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: registry = default_registry return msgpack.packb(obj, @@ -342,7 +360,11 @@ def dumps(obj, 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: registry = default_registry ext_hook = functools.partial(_unserializer, registry)