[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Higher Level Python APIs

From: David James <james_at_cs.toronto.edu>
Date: 2007-02-22 19:05:52 CET

On 2/8/07, Jeremy Whitlock <jcscoobyrs@gmail.com> wrote:
> 1. I need to get the Python bindings to expose all necessary functionality
> of the Subversion API.
> 2. Once that is complete, we would create Python classes to encapsulate the
> lower level api calls making usage of the Python bindings easier.
> 3. Document the new api.
>
> I know this is a simplified approach but those are the steps that will be
> taken if we decide to do this and I am the person doing it. Please provide
> any feedback and if you are interested in helping, please let me know.

Hi Jeremy,

It's great to hear you're interested in helping out with the Python
bindings. Your approach looks good.

The easiest way to get started (and to start understanding our Python
bindings) is to write some tests for the functions that already work,
but aren't documented or tested. If you could write a few tests along
with documentation for the untested functionality, it would be much
appreciated.

A key example:
   http://svn.haxx.se/dev/archive-2007-02/0454.shtml

In that email, Charles Duffy asked how to use svn_ra_do_diff2. To
answer his question, I looked up the documentation for svn_ra_do_diff2
in include/svn_ra.h, and tried to figure out how the SWIG bindings
would wrap it.

Here's how I addressed his question. First, I looked at the documentation.

> /**
> * Ask the RA layer to 'diff' a working copy against @a versus_url;
> * it's another form of svn_ra_do_update().
> *
> * @note This function cannot be used to diff a single file, only a
> * working copy directory. See the svn_ra_do_switch() function
> * for more details.
>
> * The client initially provides a @a diff_editor/@a diff_baton to the RA
> * layer; this editor contains knowledge of where the common diff
> * root is in the working copy (when open_root() is called).
> *
> * In return, the client receives a @a reporter/@a report_baton. The
> * client then describes its working-copy revision numbers by making
> * calls into the @a reporter structure; the RA layer assumes that all
> * paths are relative to the URL used to open @a session.
> *
> * When finished, the client calls @a reporter->finish_report(). The
> * RA layer then does a complete drive of @a diff_editor, ending with
> * close_edit(), to transmit the diff.
> *
> * @a diff_target is an optional single path component will restrict
> * the scope of the diff to an entry in the directory represented by
> * the @a session's URL, or empty if the entire directory is meant to be
> * one of the diff paths.
> *
> * The working copy will be diffed against @a versus_url as it exists
> * in revision @a revision, or as it is in head if @a revision is
> * @c SVN_INVALID_REVNUM.
> *
> [..snip...]
> svn_error_t *svn_ra_do_diff2(svn_ra_session_t *session,
> const svn_ra_reporter2_t **reporter,
> void **report_baton,
> svn_revnum_t revision,
> const char *diff_target,
> svn_boolean_t recurse,
> svn_boolean_t ignore_ancestry,
> svn_boolean_t text_deltas,
> const char *versus_url,
> const svn_delta_editor_t *diff_editor,
> void *diff_baton,
> apr_pool_t *pool);

According to the above documentation, svn_ra_do_diff2 has ten input
arguments, and two output arguments (reporter and report_baton).
"pool" arguments are always optional.

So, here's how to call the function:
    reporter, reporter_baton = ra.do_diff2(session, revision,
diff_target, recurse, ignore_ancestry, text_deltas, versus_url,
diff_editor, diff_baton)

To help out Charles, I added a test for the do_diff2 function in
r23464, but this test isn't exactly complete. I didn't test, for
example, whether the diff2 function can report on copies, deletes, or
property changes. I also didn't put much effort into figuring out how
the diff2 function is really supposed to be used -- I didn't, for
example, set up a real working copy to diff against, which seems to be
a requirement of the function. All of these things could definitely be
improved in the test suite, and I'd love your help.

Jeremy, it'd be great if you could extend the do_diff2 test to test a
little more, and add new tests for other functions. By writing these
tests, you'll learn more about the Python bindings.

When you write tests for the Python bindings, you'll most likely run
into some things you don't like -- i.e., stuff that doesn't work and
stuff which is confusing or undocumented. As you work, keep track of
these things, and once you're done writing a few tests, send a
proposal to the list explaining what you'd like to fix.

Hope this helps,

David

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Feb 22 19:10:07 2007

This is an archived mail posted to the Subversion Dev mailing list.