Re: Python bindings API confusion

On 2020/08/29 2:49, C. Michael Pilato wrote:
> On Fri, Aug 21, 2020 at 7:10 AM Daniel Shahaf <d.s_at_daniel.shahaf.name>
> wrote:
>
>> C. Michael Pilato wrote on Tue, 18 Aug 2020 10:23 -0400:
>>> Sending subversion/bindings/swig/include/svn_types.swg
>>> Sending
>> subversion/bindings/swig/python/libsvn_swig_py/swigutil_py.c
>>> Sending
>> subversion/bindings/swig/python/libsvn_swig_py/swigutil_py.h
>>> Sending subversion/bindings/swig/svn_fs.i
>>> Sending subversion/bindings/swig/svn_repos.i
>>> Transmitting file data .....done
>>> Committing transaction...
>>> Committed revision 1880967.
>>>
>>> I made only minor comment/formatting changes.
>>
>> Shouldn't the change be documented somewhere for users of the
>> bindings? (E.g., release notes, API errata, API documentation…)
>>
>
> Yes, I think that makes sense. The release notes for sure. As for API
> docs/errata ... do we even have such a thing for the bindings?

I'm very sorry for my late reply.

This change affects all programs using return value of svn.fs.commit_txn.
So I think api-errata is needed.

As you all and I know my English is too bad, however I wrote it as a
starting point. Please refine or rewrite if the errata is needed.
[[[
API ERRATA -- $Id$

Root Cause of Errata: design error of wrapper function
 Library(s) Affected: (SWIG Python bindings)svn.fs
Function(s) Affected: (SWIG Python bindings)svn.fs.commit_txn
     New Behavior in: 1.15
      Related Issues: n/a

== Details ==

The C API svn_fs_commit_txn has two pointer arguments to return values,
'conflict' and 'new_rev'. However 'conflict' is always NULL unless
svn_fs_commit_txn cause error, and as Python Wrapper function raises
error if C API returns error state, the return value of Python Wrapper
function svn.fs.commit_txn returned 2-tupple of None and 'new_rev' value
since 1.14.

This behavior is quite useless and inconsistent with the behavior
of svn.repos.commit_txn, the wrapper of svn_repos_commit_txn, which
has also two pointer arguments 'conflict' and 'new_rev' but only
returns 'new_rev' singleton.

For the 1.15 release, svn.fs.commit_txn returns 'new_rev' singleton
if it doesn't raise exception. In addtion, we introduce framework
to add attributes to 'SubversionException' to return values to caller
if argments for output in C API are useful when the API returns an error
(however this new feature actually is not a part of the errata).

If an API user expects that it returns a 2-tuple will get some exceptions
when try to retrieve its element.

All API users should review their treatments of return value of the API.
]]]

I also worry but couldn't wrote description of this change for API docs.

Thanks,

-- 
Yasuhito FUTATSUKI <futatuki_at_yf.bsclub.org>