You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@subversion.apache.org by Paul Koning <pk...@equallogic.com> on 2006/03/10 14:38:08 UTC
API documentation wanted (for Python in particular)
I've been trying to do things with the Subversion API without much
luck.
The underlying problem is that the API is utterly undocumented, except
for one or two trivial examples in the book.
I've figured out how to do a number of the "inspection" things by
staring at ViewVC, and/or using its routines. But that doesn't help
at all when I try to do "modification" things.
For example, I want to issue a "copy" operation through the API. The
obvious answer is to look in the "client" module, and sure enough,
there's a "copy". There is also a "copy2". But there is NO
documentation, none, nada, about what these do, what the parameters
do, etc.
Looking at the svn command line client is no help either, especially
since I want to use the Python API, not the C one.
The function documentation strings don't help; for one thing, they are
wrong. The copy/copy2 documentation strings (in 1.3.0) say that the
first argument is a svn_commit_info_t, whatever that means. But
experiments show that there isn't any such argument, and the first
argument is actually a pathname (documented as the second argument).
Ok, Brownian motion experiments as the way to discover the API is
doable, up to a point.
Finally I got what appeared to be a valid copy call, but then my
server rejected it because I had no commit log message. Sure enough.
And I can see no way to put one in. There seems to be an
svn_client_ctx_t argument, which by examination seems to have a
log_msg_func argument (as well as several other mysterious log_msg_xxx
arguments). But even after quite a lot of searching I could find no
way to create a log_msg_func argument, nor did I ever get the feeling
that, if I did, it would actually get me anywhere.
I finally gave up and used the svn command line to perform the
operation. Yuck.
Is any of this stuff documented anywhere? Are there any plans to
document any of it? Right now the API effectively doesn't exist, as
far as I can see.
paul
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Barry Scott <ba...@barrys-emacs.org>.
Take a look at pysvn at http://pysvn.tigris.org
It's documented and has a very pythonic API.
Barry
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by eg <eg...@gmail.com>.
Paul Koning wrote:
>
> Is any of this stuff documented anywhere? Are there any plans to
> document any of it? Right now the API effectively doesn't exist, as
> far as I can see.
>
> paul
Garret Rooney's book "Practical Subversion" has a small section of a
chapter discussing the Python bindings. As well as his tiny code
example, he suggests other examples:
Mailer.py in the tools/hook-scripts mailer directory,
some smaller examples in tools/examples,
Other consumers of the bindings are: ViewCVS and SubWiki.
There are also some small examples and comments in William Nagel's book.
Info on this book (including a downloadable pdf) can be found:
http://svn.haxx.se/users/archive-2006-01/1204.shtml
As to other docs... I personally don't know.
E.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Barry Scott <ba...@barrys-emacs.org>.
On Mar 13, 2006, at 00:48, Daniel Berlin wrote:
>> Expecting people to read cryptic .h files AND even more cryptic SWIG
>> files is really not very nice at all.
> See, this is where i disagree.
> Expecting people to read well documented .h files to discover what the
> interface for something is, IMHO, is perfectly fine.
A couple of years ago I did not think the SVN API was good for python
and did not think
that the lack of documentation was reasonable either.
That is why I wrote pysvn and critically documented it.
Oh and personally I find that reading the .h is rarely good enough. I
end up reading the .c files
as well to figure out stuff that is not in the .h comments.
Barry
pysvn developer
Re: API documentation wanted (for Python in particular)
Posted by Ryan Schmidt <su...@ryandesign.com>.
On Mar 13, 2006, at 15:31, Paul Koning wrote:
> Part of the problem is this: the .h files or doxygen provide the
> "vocabulary" but nothing else. There is no description of the
> organizing principles, or of the semantics. What is a "baton"? How
> are log messages handled? Etc...
I know it's not a help to all your questions, but to one specific one...
http://subversion.tigris.org/faq.html#baton
:-/
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Daniel Berlin <db...@dberlin.org>.
On Mon, 2006-03-13 at 09:31 -0500, Paul Koning wrote:
> >>>>> "Daniel" == Daniel Berlin <db...@dberlin.org> writes:
>
> >> Personally, I don't find that "read the source" is reasonable
> >> documentation, but I guess opinions differ. And I suppose SWIG is
> >> a mechanical transformation.
>
> Daniel> Okay, well, you can always use the doxygen generated docs if
> Daniel> you like.
>
> Daniel> That is how gcc, for example, documents libstdc++.
>
> Daniel> It's pretty standard in projects i've seen to keep API
> Daniel> documentation in the code, or have it generated from the
> Daniel> comments. Anything else gets out of date *very* quickly, and
> Daniel> becomes worse than useless.
>
> I'd offer gccint as a counterexample. I suppose it's a fairly rare
> one; other *int manuals tend to be marginal at best.
gccint is horribly out of date, actually, and getting moreso all the
time.
It is also useless to anyone actually attempting to do anything but
write a port (IE write a new pass, etc).
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Paul Koning <pk...@equallogic.com>.
>>>>> "Daniel" == Daniel Berlin <db...@dberlin.org> writes:
>> Personally, I don't find that "read the source" is reasonable
>> documentation, but I guess opinions differ. And I suppose SWIG is
>> a mechanical transformation.
Daniel> Okay, well, you can always use the doxygen generated docs if
Daniel> you like.
Daniel> That is how gcc, for example, documents libstdc++.
Daniel> It's pretty standard in projects i've seen to keep API
Daniel> documentation in the code, or have it generated from the
Daniel> comments. Anything else gets out of date *very* quickly, and
Daniel> becomes worse than useless.
I'd offer gccint as a counterexample. I suppose it's a fairly rare
one; other *int manuals tend to be marginal at best.
Part of the problem is this: the .h files or doxygen provide the
"vocabulary" but nothing else. There is no description of the
organizing principles, or of the semantics. What is a "baton"? How
are log messages handled? Etc...
I feel a bit like a guy trying to learn German and being offered a
dictionary as the answer. Oh yes, and it's a German-Russian
dictionary, and I don't know Russian. "No problem, there's a Russian
textbook over there". Yes, but even once I learn the words of German
that doesn't mean I know German.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Alan Barrett <ap...@cequrux.com>.
On Sun, 12 Mar 2006, Daniel Berlin wrote:
> > Daniel> See, this is where i disagree. Expecting people to read well
> > Daniel> documented .h files to discover what the interface for
> > Daniel> something is, IMHO, is perfectly fine.
I strongly disagree. Expecting people to have the sources lying around
is unreasonable. The people who install binary packages that were
created by third parties would also like documentation.
> It's pretty standard in projects i've seen to keep API documentation in
> the code, or have it generated from the comments. Anything else gets
> out of date *very* quickly, and becomes worse than useless.
Generating documentation from structured comments in the code makes
a lot of sense. Doxygen can do that. The subversion project uses
doxygen. The missing pieces are:
* The procedure for rolling release tarballs doesn't include
"run doxygen to generate the documentation".
* The release tarballs don't include the doxygen-generated
documentation.
* The install procedure doesn't install the doxygen-documented
documentation.
--apb (Alan Barrett)
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Daniel Berlin <db...@dberlin.org>.
On Sun, 2006-03-12 at 20:01 -0500, Paul Koning wrote:
> >>>>> "Daniel" == Daniel Berlin <db...@dberlin.org> writes:
>
> >> Expecting people to read cryptic .h files AND even more cryptic
> >> SWIG files is really not very nice at all.
> Daniel> See, this is where i disagree. Expecting people to read well
> Daniel> documented .h files to discover what the interface for
> Daniel> something is, IMHO, is perfectly fine.
>
> Daniel> Expecting people to understand that in order to wrap this API
> Daniel> into certain languages, some mechcanical transformations were
> Daniel> performed to it, is also okay.
>
> Daniel> You are acting like this is a huge secret deal where every
> Daniel> single function has had something different done to it, and
> Daniel> it's just not so.
>
> I think part of the reason I feel that way is that there is not the
> slightest hint of ANY description anywhere that I can find to get a
> person started in this direction.
> Personally, I don't find that "read the source" is reasonable
> documentation, but I guess opinions differ. And I suppose SWIG is a
> mechanical transformation.
Okay, well, you can always use the doxygen generated docs if you like.
That is how gcc, for example, documents libstdc++.
It's pretty standard in projects i've seen to keep API documentation in
the code, or have it generated from the comments. Anything else gets
out of date *very* quickly, and becomes worse than useless.
>
> But how was I supposed to know that? It isn't stated anywhere! There
> is a faint tantalizing hint of conventional documentation (actual
> descriptive text) in the book, which implies that one would expect to
> see more of that, but there isn't any more. How about a FAQ entry
> to tell people "the C API is documented in the .h files; for other
> languages, read the SWIG documentation and the SWIG wrapper files to
> learn how the C API is transformed to those other languages". Then at
> least people would have a place to start.
It is true that nobody has yet written this stuff. Documentation in
open source projects is one of the things people work on the least,
unless someone is paid to do it. This is generally true of non-open
source projects i've observed as well :).
The best way to get good docs is to write down what you've discovered,
or learned, and put it somewhere, and someone will come and improve it
with what they've learned, etc.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by kf...@collab.net.
Paul Koning <pk...@equallogic.com> writes:
> I think part of the reason I feel that way is that there is not the
> slightest hint of ANY description anywhere that I can find to get a
> person started in this direction.
When I said "looks like you'll have to write it", what I meant was:
We need you to remember the places where you expected to find
documentation or pointers to documentation, and it'd be great if you
could help us fix those places so they contain what you expected.
If you don't have time for that level of involvement, that's
understandable. However, I would ask then that you not complain *too*
hard. We're not in possession of some magic potion that we can
sprinkle over the project to make everything be perfectly organized.
We need involvement -- yours and others' -- to make things go right.
Most people here are volunteering their time (disclaimer: I'm not,
CollabNet pays me to work on Subversion... but then, I've got plenty
of stuff on my plate and it's 11:45pm right now, so you could say I'm
volunteering my time at this particular moment :-) ).
> But how was I supposed to know that? It isn't stated anywhere! There
> is a faint tantalizing hint of conventional documentation (actual
> descriptive text) in the book, which implies that one would expect to
> see more of that, but there isn't any more. How about a FAQ entry
> to tell people "the C API is documented in the .h files; for other
> languages, read the SWIG documentation and the SWIG wrapper files to
> learn how the C API is transformed to those other languages". Then at
> least people would have a place to start.
Yes, that'd be a fine FAQ entry; you've written half of it already.
See http://subversion.tigris.org/mailing-list-guidelines.html#patches
for guidelines on how to submit a patch (including a patch to the FAQ,
not just to source code). The master copy of the FAQ is here:
http://svn.collab.net/repos/svn/trunk/www/faq.html
> Daniel> I've written very complex applications using the SWIG API,
> Daniel> that use parts of SVN i was never familiar with at all (IE
> Daniel> the fact that i am an svn developer didn't help me), and it
> Daniel> just wasn't that big a problem.
>
> Hm. Well, part of the trouble I have is that I was trying to do
> something quite simple, which I could have done in a shell script in
> 15 minutes (but not robust enough to my taste). And it took several
> hours of Brownian motion, doing random experiments that lead nowhere.
> I just don't find this acceptable... sorry.
Then don't accept it -- do something about it!
Thank you,
-Karl
--
www.collab.net <> CollabNet | Distributed Development On Demand
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Emmanuel Blot <ma...@gmail.com>.
> But how was I supposed to know that? It isn't stated anywhere!
I dumped into the same question a couple of months ago, as I needed to
write some pre/post commit script, and I wanted to write them in
Python language. I looked at some examples of use of the SVN/SWIG API
for Python, and it did not take long (about half an hour or so) to
understand how parameters are passed, and how output parameters are
retrieved. It's a mechanical transformation that is not difficult to
follow, once you read a couple of examples.
The only things I did not find in the wrappers are some constants. The
rest of the Python API is pretty straightforward to guess from the C
API, from my perspective.
As already written in this thread, if you do not like the C-to-Python
translation made with the help of SWIG, you probably want to have a
look at the pysvn project.
--
Manu
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Paul Koning <pk...@equallogic.com>.
>>>>> "Daniel" == Daniel Berlin <db...@dberlin.org> writes:
>> Expecting people to read cryptic .h files AND even more cryptic
>> SWIG files is really not very nice at all.
Daniel> See, this is where i disagree. Expecting people to read well
Daniel> documented .h files to discover what the interface for
Daniel> something is, IMHO, is perfectly fine.
Daniel> Expecting people to understand that in order to wrap this API
Daniel> into certain languages, some mechcanical transformations were
Daniel> performed to it, is also okay.
Daniel> You are acting like this is a huge secret deal where every
Daniel> single function has had something different done to it, and
Daniel> it's just not so.
I think part of the reason I feel that way is that there is not the
slightest hint of ANY description anywhere that I can find to get a
person started in this direction.
Personally, I don't find that "read the source" is reasonable
documentation, but I guess opinions differ. And I suppose SWIG is a
mechanical transformation.
But how was I supposed to know that? It isn't stated anywhere! There
is a faint tantalizing hint of conventional documentation (actual
descriptive text) in the book, which implies that one would expect to
see more of that, but there isn't any more. How about a FAQ entry
to tell people "the C API is documented in the .h files; for other
languages, read the SWIG documentation and the SWIG wrapper files to
learn how the C API is transformed to those other languages". Then at
least people would have a place to start.
Daniel> I've written very complex applications using the SWIG API,
Daniel> that use parts of SVN i was never familiar with at all (IE
Daniel> the fact that i am an svn developer didn't help me), and it
Daniel> just wasn't that big a problem.
Hm. Well, part of the trouble I have is that I was trying to do
something quite simple, which I could have done in a shell script in
15 minutes (but not robust enough to my taste). And it took several
hours of Brownian motion, doing random experiments that lead nowhere.
I just don't find this acceptable... sorry.
paul
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Daniel Berlin <db...@dberlin.org>.
On Sun, 2006-03-12 at 19:31 -0500, Paul Koning wrote:
> >>>>> "Daniel" == Daniel Berlin <db...@dberlin.org> writes:
>
> Daniel> On Fri, 2006-03-10 at 17:34 -0500, Paul Koning wrote:
> >> Unfortunately, I want to do it in Python. And I can't find any
> >> information at all about that. It looks like I have to create a
> >> client_ctx object and put a log_msg_func2 into that, which means I
> >> have to create that function. But what is the function signature
> >> in Python? That's where I lost it before, and I still see no
> >> answer.
>
> Daniel> The python API is simply a wrapping of the C one.
>
> Not true. The client_copy function doesn't have the first argument,
> for example. On really careful reading that makes sense, since it
> seems to be an output argument.
>
Errr, yes, that doesn't make it not a wrapping of the C one however.
It just means that output arguments are transformed in some mechanical
way
They are returned as return values, and swig takes care of passing in a
temporary one for you.
> Daniel> Thus, the docs are the same, as are the signatures.
>
> Daniel> However you'd do it in C is usually exactly how you'd do it
> Daniel> in python.
>
> When the two languages match, yes, it seems that way. But, for
> example, the log_msg_func returns a string via a char ** argument, and
> Python doesn't have any such thing. So it has to be something
> different in Python.
> Expecting people to read cryptic .h files AND even more cryptic SWIG
> files is really not very nice at all.
See, this is where i disagree.
Expecting people to read well documented .h files to discover what the
interface for something is, IMHO, is perfectly fine.
Expecting people to understand that in order to wrap this API into
certain languages, some mechcanical transformations were performed to
it, is also okay.
You are acting like this is a huge secret deal where every single
function has had something different done to it, and it's just not so.
I've written very complex applications using the SWIG API, that use
parts of SVN i was never familiar with at all (IE the fact that i am an
svn developer didn't help me), and it just wasn't that big a problem.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Paul Koning <pk...@equallogic.com>.
>>>>> "Daniel" == Daniel Berlin <db...@dberlin.org> writes:
Daniel> On Fri, 2006-03-10 at 17:34 -0500, Paul Koning wrote:
>> Unfortunately, I want to do it in Python. And I can't find any
>> information at all about that. It looks like I have to create a
>> client_ctx object and put a log_msg_func2 into that, which means I
>> have to create that function. But what is the function signature
>> in Python? That's where I lost it before, and I still see no
>> answer.
Daniel> The python API is simply a wrapping of the C one.
Not true. The client_copy function doesn't have the first argument,
for example. On really careful reading that makes sense, since it
seems to be an output argument.
Daniel> Thus, the docs are the same, as are the signatures.
Daniel> However you'd do it in C is usually exactly how you'd do it
Daniel> in python.
When the two languages match, yes, it seems that way. But, for
example, the log_msg_func returns a string via a char ** argument, and
Python doesn't have any such thing. So it has to be something
different in Python.
Expecting people to read cryptic .h files AND even more cryptic SWIG
files is really not very nice at all.
paul
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Daniel Berlin <db...@dberlin.org>.
On Fri, 2006-03-10 at 17:34 -0500, Paul Koning wrote:
>
> Unfortunately, I want to do it in Python. And I can't find any
> information at all about that. It looks like I have to create a
> client_ctx object and put a log_msg_func2 into that, which means I
> have to create that function. But what is the function signature in
> Python? That's where I lost it before, and I still see no answer.
The python API is simply a wrapping of the C one.
Thus, the docs are the same, as are the signatures.
However you'd do it in C is usually exactly how you'd do it in python.
>>> from svn import *
>>> newctx = client.svn_client_ctx_t()
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Paul Koning <pk...@equallogic.com>.
>>>>> "kfogel" == kfogel <kf...@collab.net> writes:
kfogel> Paul Koning <pk...@equallogic.com> writes:
>> Unfortunately, I want to do it in Python. And I can't find any
>> information at all about that. It looks like I have to create a
>> client_ctx object and put a log_msg_func2 into that, which means I
>> have to create that function. But what is the function signature
>> in Python? That's where I lost it before, and I still see no
>> answer.
kfogel> Looks like you'll have to write it.
Hm. It would make more sense for someone who knows Subversion
internals to do that...
Someone suggested PySVN; I'm going to look there.
paul
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by kf...@collab.net.
Paul Koning <pk...@equallogic.com> writes:
> Unfortunately, I want to do it in Python. And I can't find any
> information at all about that. It looks like I have to create a
> client_ctx object and put a log_msg_func2 into that, which means I
> have to create that function. But what is the function signature in
> Python? That's where I lost it before, and I still see no answer.
Looks like you'll have to write it.
-Karl
--
www.collab.net <> CollabNet | Distributed Development On Demand
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by Paul Koning <pk...@equallogic.com>.
>>>>> "kfogel" == kfogel <kf...@collab.net> writes:
kfogel> Paul Koning <pk...@equallogic.com> writes:
>> I've been trying to do things with the Subversion API without much
>> luck.
>>
>> The underlying problem is that the API is utterly undocumented,
>> except for one or two trivial examples in the book.
kfogel> It is completely documented, in the header files
kfogel> (include/svn_*.h), and we generate Doxygen pages here
kfogel> http://svn.collab.net/svn-doxygen/.
That helps just a little. It's seriously cryptic and has no roadmap
at all, but if you can somehow guess where to look it helps.
It would be a very good idea to have pointers to this site in the main
Subversion documentation (both in the book, and on
subversion.tigris.org). If those already exist, I managed to miss
them.
I just looked at the "svn copy" API call. I *think* it has just
enough information, if I wanted to program in C.
Unfortunately, I want to do it in Python. And I can't find any
information at all about that. It looks like I have to create a
client_ctx object and put a log_msg_func2 into that, which means I
have to create that function. But what is the function signature in
Python? That's where I lost it before, and I still see no answer.
paul
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: API documentation wanted (for Python in particular)
Posted by kf...@collab.net.
Paul Koning <pk...@equallogic.com> writes:
> I've been trying to do things with the Subversion API without much
> luck.
>
> The underlying problem is that the API is utterly undocumented, except
> for one or two trivial examples in the book.
It is completely documented, in the header files (include/svn_*.h),
and we generate Doxygen pages here http://svn.collab.net/svn-doxygen/.
-Karl
--
www.collab.net <> CollabNet | Distributed Development On Demand
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org