[PRELIMINARY PATCH] High-level Python "Client" layer API, mark zero

[Walter Mundt <em...@spamcop.net>]

Here's what I've got from before I stopped working.  I'm not including a 
log-message formatted summary because THIS PATCH IS NOT READY.  djames 
asked that I post it so everyone can get an idea of where things stand.

The AuthBaton stuff in core.py is more of a thought experiment than 
anything, thinking about whether I want to separately wrap Subversion 
auth_baton objects in a Python class.  Auth batons include a "parameter" 
map which is an apr_hash_t whole values vary in type depending on what 
key you look up; thus the calls to (nonexistent) helpers which would try 
to sort that out and marshal to Python in some mostly-sane manner. 
Still no decision on whether this makes sense/is important enough to 
justify building/is possible to do sanely given the lack of strong 
typing guarantees on the auth parameters.  Haven't yet looked at how the 
other language bindings handle (or refuse to deal with) this.

The new Client class basically attempts to encapsulate the 
svn_client_ctx_t; rather unambitious, but I'm trying to keep a 
reasonable amount of congruence between the Python bindings and the C 
API where I can.

I'm planning on writing a script to parse XML output from doxygen to 
generate templates for the docstrings for the Client functions with 
direct equivalents in the C API.  Thus the total lack of any docs on 
those for the moment.

Finally, I've left off the numeric suffixes on function variants 
throughout.  This is because most of the changes seem to involve 
introducing new parameters.  In Python, we can just add extra 
optional/defaulted parameters and document "current" and (if needed) 
"deprecated" call semantics without needing to introduce new function names.

Also note the COMPLETE LACK of any new tests at the moment.  Aside from 
making sure it compiles and still passes check-swig-py, I haven't tested 
any of this; thus all the disclaimers about incompleteness and general 
not-ready state of the patch.

Regardless, here you go!  Feel free to discuss any of the points above 
or any other issues that you might see with this patch.

-Walter

Re: [PRELIMINARY PATCH] High-level Python "Client" layer API, mark zero

[Jelmer Vernooij <je...@samba.org>]

On Mon, Jul 10, 2006 at 05:45:44PM +0100, Max Bowsher wrote:
> Walter Mundt wrote:
> > Finally, I've left off the numeric suffixes on function variants
> > throughout.  This is because most of the changes seem to involve
> > introducing new parameters.  In Python, we can just add extra
> > optional/defaulted parameters and document "current" and (if needed)
> > "deprecated" call semantics without needing to introduce new function
> > names.
> I disagree with this quite strongly. There's absolutely NO guarantee
> that all C API revbumping will be compatible with the above methods.
I think it makes a lot of sense for those functions where the 
older function can be implemented by calling the newer function with
some arguments hardcoded. Those functions where the behaviour is 
actually different can always be added with a numeric suffix in Python.

It does, however, mean that in all 80% of the other cases, there are
no numeric suffixes, which is much more user-friendly imho.

Just my $0.02,

Cheers,

Jelmer

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PRELIMINARY PATCH] High-level Python "Client" layer API, mark zero

[David James <dj...@collab.net>]

On 7/10/06, Max Bowsher <ma...@ukf.net> wrote:
> > +def _get_poolarg(pool):
> > +  """Returns an empty tuple if pool is None, or (pool,) otherwise, for use in
> > +     functions taking an optional pool parameter."""
> > +  if pool is None:
> > +    return ()
> > +  else:
> > +    return (pool,)
> ...
> > +  def mkdir(self, paths, pool = None):
> > +    poolarg = core._get_poolarg(pool)
> > +    return mkdir2(paths, self.ctx, *poolarg)
> ...
>
> This poolarg stuff seems a little messy - perhaps we should instead
> adjust the underlying wrapper code to understand None directly, rather
> than insisting on the presence/absence of the pool parameter.

There's no need to change our wrappers. If 'pool = None', we treat the
pool argument as missing. Therefore, the above snippet can be
simplified to:
  def mkdir(self, paths, pool = None):
    return mkdir2(paths, self.ctx, pool)

Cheers,

David

-- 
David James -- http://www.cs.toronto.edu/~james

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PRELIMINARY PATCH] High-level Python "Client" layer API, mark zero

["C. Michael Pilato" <cm...@collab.net>]

Max Bowsher wrote:
>>The AuthBaton stuff in core.py is more of a thought experiment than
>>anything, thinking about whether I want to separately wrap Subversion
>>auth_baton objects in a Python class.  Auth batons include a "parameter"
>>map which is an apr_hash_t whole values vary in type depending on what
>>key you look up; thus the calls to (nonexistent) helpers which would try
>>to sort that out and marshal to Python in some mostly-sane manner. Still
>>no decision on whether this makes sense/is important enough to justify
>>building/is possible to do sanely given the lack of strong typing
>>guarantees on the auth parameters.
> 
> Given the lack of general typing guarantees, I think the only thing you
> can sensibly do is only support access to auth parameters whose type you
> know about, and throw an exception on an attempt to set or get a
> parameter that the bindings code has not yet been explicitly taught about.

This area of our core code has troubled me in the past when working with the
Python bindings.  There really is no reason for that hash to permit
arbitrary value types, and I'd like to see us rev the auth_baton interface
(again, in the Subversion core libraries) such that the hash is a simple
string->string mapping.

-- 
C. Michael Pilato <cm...@collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand

Re: [PRELIMINARY PATCH] High-level Python "Client" layer API, mark zero

[Max Bowsher <ma...@ukf.net>]

Walter Mundt wrote:
> Here's what I've got from before I stopped working.  I'm not including a
> log-message formatted summary because THIS PATCH IS NOT READY.  djames
> asked that I post it so everyone can get an idea of where things stand.

Thanks.

> The AuthBaton stuff in core.py is more of a thought experiment than
> anything, thinking about whether I want to separately wrap Subversion
> auth_baton objects in a Python class.  Auth batons include a "parameter"
> map which is an apr_hash_t whole values vary in type depending on what
> key you look up; thus the calls to (nonexistent) helpers which would try
> to sort that out and marshal to Python in some mostly-sane manner. Still
> no decision on whether this makes sense/is important enough to justify
> building/is possible to do sanely given the lack of strong typing
> guarantees on the auth parameters.

Given the lack of general typing guarantees, I think the only thing you
can sensibly do is only support access to auth parameters whose type you
know about, and throw an exception on an attempt to set or get a
parameter that the bindings code has not yet been explicitly taught about.

> The new Client class basically attempts to encapsulate the
> svn_client_ctx_t; rather unambitious, but I'm trying to keep a
> reasonable amount of congruence between the Python bindings and the C
> API where I can.

Good.

> I'm planning on writing a script to parse XML output from doxygen to
> generate templates for the docstrings for the Client functions with
> direct equivalents in the C API.  Thus the total lack of any docs on
> those for the moment.

I'm not sure that the C docstrings will be adequately relevant for
Python in many cases.

> Finally, I've left off the numeric suffixes on function variants
> throughout.  This is because most of the changes seem to involve
> introducing new parameters.  In Python, we can just add extra
> optional/defaulted parameters and document "current" and (if needed)
> "deprecated" call semantics without needing to introduce new function
> names.

I disagree with this quite strongly. There's absolutely NO guarantee
that all C API revbumping will be compatible with the above methods.

> +def _get_poolarg(pool):
> +  """Returns an empty tuple if pool is None, or (pool,) otherwise, for use in
> +     functions taking an optional pool parameter."""
> +  if pool is None:
> +    return ()
> +  else:
> +    return (pool,)
...
> +  def mkdir(self, paths, pool = None):
> +    poolarg = core._get_poolarg(pool)
> +    return mkdir2(paths, self.ctx, *poolarg)
...

This poolarg stuff seems a little messy - perhaps we should instead
adjust the underlying wrapper code to understand None directly, rather
than insisting on the presence/absence of the pool parameter.

Max.