Python Tutorial - urllib2

classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

Python Tutorial - urllib2

Michael Foord
By the way (and in the vain (sic) of shameless self-promotion...) there
was a suggestion on Dobbs Python-URL that the inclusion of some of my
material on urllib2 would be welcome in the tutorial.

http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa

My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml

The most appropriate sections to include would be on fetching URLs and
handling errors, and possibly the basic authentication example. It
probably fits best in the 'Brief tour of the standard library'.

Would that be welcomed ? It is currently in rest format - and html of
course ;-)

Is reST acceptable for *someone* to add this material - and if so, what
should I do about it ?

By the way my vote is -1 on moving to html as the standard markup format
and +1 on working on docutils to turn that into an usable input format.
Additionally - having a wiki version, or a version that accepts user
commentary would be a very useful way of gathering additional
information. Of course someone has to maintain this... I think AMK did a
simple implementation of this a while ago - although it had usability
issues and the resulting data didn't seem to be used. I guess this is
all part of the ongoing discussion.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Michael Foord
Michael Foord wrote:
> By the way (and in the vain (sic) of shameless self-promotion...) there
> was a suggestion on Dobbs Python-URL that the inclusion of some of my
> material on urllib2 would be welcome in the tutorial.
>
> http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa
>
> My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml
>

Oops... correction :
http://www.voidspace.org.uk/python/articles/urllib2.shtml

Sorry about that. I *would* be interested in helping with the Python
tutorial (and docs where appropriate). it's a question of knowing where
to begin...

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml


> The most appropriate sections to include would be on fetching URLs and
> handling errors, and possibly the basic authentication example. It
> probably fits best in the 'Brief tour of the standard library'.
>
> Would that be welcomed ? It is currently in rest format - and html of
> course ;-)
>
> Is reST acceptable for *someone* to add this material - and if so, what
> should I do about it ?
>
> By the way my vote is -1 on moving to html as the standard markup format
> and +1 on working on docutils to turn that into an usable input format.
> Additionally - having a wiki version, or a version that accepts user
> commentary would be a very useful way of gathering additional
> information. Of course someone has to maintain this... I think AMK did a
> simple implementation of this a while ago - although it had usability
> issues and the resulting data didn't seem to be used. I guess this is
> all part of the ongoing discussion.
>
> All the best,
>
> Fuzzyman
> http://www.voidspace.org.uk/python/index.shtml
> _______________________________________________
> Doc-SIG maillist  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>
>
>

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Fredrik Lundh
In reply to this post by Michael Foord
Michael Foord wrote:

> By the way my vote is -1 on moving to html as the standard markup format
> and +1 on working on docutils to turn that into an usable input format.

so how to you plan to achieve the required level of semantic markup in ReST?

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Aahz
In reply to this post by Michael Foord
On Thu, Dec 22, 2005, Michael Foord wrote:
>
> Is reST acceptable for *someone* to add this material - and if so, what
> should I do about it ?

Submit in reST or plain-text and someone will do any necessary
conversions.  Really, don't worry about it, Just Do It.
--
Aahz ([hidden email])           <*>         http://www.pythoncraft.com/

"Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck."  --USENET schmuck (aka Robert Kern)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Martin Blais-2
In reply to this post by Michael Foord
On 12/22/05, Michael Foord <[hidden email]> wrote:

> By the way (and in the vain (sic) of shameless self-promotion...) there
> was a suggestion on Dobbs Python-URL that the inclusion of some of my
> material on urllib2 would be welcome in the tutorial.
>
> http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa
>
> My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml
>
> The most appropriate sections to include would be on fetching URLs and
> handling errors, and possibly the basic authentication example. It
> probably fits best in the 'Brief tour of the standard library'.
>
> Would that be welcomed ? It is currently in rest format - and html of
> course ;-)

Your tutorial is great.  Read it a while ago.  Would love to see it
along the other tutorials or even in the library docs for the module
(as the urllib2 docs are a bit thin on explanations).


> Is reST acceptable for *someone* to add this material - and if so, what
> should I do about it ?

Convert it to LaTeX (it's easy) and submit it.


> By the way my vote is -1 on moving to html as the standard markup format
> and +1 on working on docutils to turn that into an usable input format.
> Additionally - having a wiki version, or a version that accepts user
> commentary would be a very useful way of gathering additional
> information. Of course someone has to maintain this... I think AMK did a
> simple implementation of this a while ago - although it had usability
> issues and the resulting data didn't seem to be used. I guess this is
> all part of the ongoing discussion.

There was a long and detailed discussion about using ReST as an input
format for documentation a while ago.  The consensus was that ReST
does not allow sufficient markup for technical documentation, which is
necessary for this kind of document.

The LaTeX input format using the macros from the python docs is very
simple.  Converting your document should be easy.

cheers,
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Michael Foord
Martin Blais wrote:

> On 12/22/05, Michael Foord <[hidden email]> wrote:
>
>>By the way (and in the vain (sic) of shameless self-promotion...) there
>>was a suggestion on Dobbs Python-URL that the inclusion of some of my
>>material on urllib2 would be welcome in the tutorial.
>>
>>http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa
>>
>>My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml
>>
>>The most appropriate sections to include would be on fetching URLs and
>>handling errors, and possibly the basic authentication example. It
>>probably fits best in the 'Brief tour of the standard library'.
>>
>>Would that be welcomed ? It is currently in rest format - and html of
>>course ;-)
>
>
> Your tutorial is great.  Read it a while ago.  Would love to see it
> along the other tutorials or even in the library docs for the module
> (as the urllib2 docs are a bit thin on explanations).
>
>
>
>>Is reST acceptable for *someone* to add this material - and if so, what
>>should I do about it ?
>
>
> Convert it to LaTeX (it's easy) and submit it.
>

One of the docutils output forms is LayTeX - but the Python
documentation LayTeX is pretty specific ?

Anyway, that *aside* - it looks like Fred has taken on 'TeXifying' the
relevant part I submitted as a patch to the urllib2 docs. (Many thanks).

I'll probably wait and see how that reads and evaluate if a longer entry
in the tutorial is appropriate. If it *is* then I'll customise
appropriately.

If I was to do this - what *is* the appropriate way to submit ? Via
sourceforge ?


>
>
>>By the way my vote is -1 on moving to html as the standard markup format
>>and +1 on working on docutils to turn that into an usable input format.
>>Additionally - having a wiki version, or a version that accepts user
>>commentary would be a very useful way of gathering additional
>>information. Of course someone has to maintain this... I think AMK did a
>>simple implementation of this a while ago - although it had usability
>>issues and the resulting data didn't seem to be used. I guess this is
>>all part of the ongoing discussion.
>
>
> There was a long and detailed discussion about using ReST as an input
> format for documentation a while ago.  The consensus was that ReST
> does not allow sufficient markup for technical documentation, which is
> necessary for this kind of document.
>

Doesn't currently - or can't ? I thought it was just the current state
that was a problem. I'd be disappointed if it was never likely to be
possible to create the python docs with reST.


All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> The LaTeX input format using the macros from the python docs is very
> simple.  Converting your document should be easy.
>
> cheers,
>
>
>

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Martin Blais-2
> >>By the way my vote is -1 on moving to html as the standard markup format
> >>and +1 on working on docutils to turn that into an usable input format.
> >>Additionally - having a wiki version, or a version that accepts user
> >>commentary would be a very useful way of gathering additional
> >>information. Of course someone has to maintain this... I think AMK did a
> >>simple implementation of this a while ago - although it had usability
> >>issues and the resulting data didn't seem to be used. I guess this is
> >>all part of the ongoing discussion.
> >
> >
> > There was a long and detailed discussion about using ReST as an input
> > format for documentation a while ago.  The consensus was that ReST
> > does not allow sufficient markup for technical documentation, which is
> > necessary for this kind of document.
> >
>
> Doesn't currently - or can't ? I thought it was just the current state
> that was a problem. I'd be disappointed if it was never likely to be
> possible to create the python docs with reST.

Well, be disappointed.
It does not currently, and most likely won't.

As much as we all would like some kind of magic silver bullet text
format that just "knows" what we mean and want to express, it is
rather unlikely that ReST develops to become that for every kind of
domain.  ReST does a fair amount of *generic* structure inference, and
that is its scope.  The amount of ugly directives and markup being
regularly proposed on the docutils mailing-list indicates that ReST
may have already reached its potential in terms of automatically
guessing structure from simple text files.  Even if this is not the
case, extending ReST to include keywords for functions, variables,
classes, lists of arguments, etc.  would render it into just an
equally ugly form of input equivalent to the current LaTeX sources,
... and without the power of expression of TeX macros!

You see, for the technical docs we NEED to indicate the nature of the
identifiers, not just to render them consistently, but for generating
indexes, and cross-references, and for plenty of fother reasons.  You
can't do that in ReST (well, the interpreted roles do take you part of
the way, but not enough).  At some point you have to tell the computer
all the information that is in your head, and the ReST format simply
does not stretch that far, and LaTeX is a great tool for this at the
moment.

What sucks now is the inflexibliity of the produced document: the
tools to convert from the LaTeX sources to other formats are nothing
short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we
could obtain some kind of meaningful intermediate representation from
the source, from which we could then generate various output formats
(a bit like how docutils is structured).  I saw some project like that
a while ago, generating XML from LaTeX sources, never had time to
check it out more seriously.

cheers,
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

A.M. Kuchling
In reply to this post by Martin Blais-2
On Thu, Dec 22, 2005 at 10:06:48AM -0500, Martin Blais wrote:
> Your tutorial is great.  Read it a while ago.  Would love to see it
> along the other tutorials or even in the library docs for the module
> (as the urllib2 docs are a bit thin on explanations).

There's also the Doc/howto directory.  It's not part of the standard
documentation set yet, but it already includes one reST document
(unicode.rst), so your tutorial could just be added as a urllib2 HOWTO
without any conversion.  (At that point we probably *should* be
thinking of building the HOWTOs as part of the docset.)

--amk
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Michael Foord
A.M. Kuchling wrote:

> On Thu, Dec 22, 2005 at 10:06:48AM -0500, Martin Blais wrote:
>
>>Your tutorial is great.  Read it a while ago.  Would love to see it
>>along the other tutorials or even in the library docs for the module
>>(as the urllib2 docs are a bit thin on explanations).
>
>
> There's also the Doc/howto directory.  It's not part of the standard
> documentation set yet, but it already includes one reST document
> (unicode.rst), so your tutorial could just be added as a urllib2 HOWTO
> without any conversion.  (At that point we probably *should* be
> thinking of building the HOWTOs as part of the docset.)
>

My source document uses some macros - e.g. to colorize the python code
examples. I'm happy to clean it up for inclusion as a "HOWTO Fetch
Internet Resources Using urllib2".

I don't have unrestricted internet access here (ironically enough) - so
could you email me the unicode.rst source so I can give it a similar format.

Should I privately email you the result for you to assess ? I could
probably complete this tonight...

The risk it that it will duplicate some of the material which should be
(soon) included in the urllib2 documentation.

Again, I could wait until Fred has done this and see if a fuller
tutorial is appropriate ?

Many Thanks

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> --amk
> _______________________________________________
> Doc-SIG maillist  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>
>
>

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Fred Drake-3
In reply to this post by Aahz
On Thursday 22 December 2005 09:57, Aahz wrote:
 > Submit in reST or plain-text and someone will do any necessary
 > conversions.  Really, don't worry about it, Just Do It.

For the record, I've assigned Fuzzyman's issue to myself, but we should make
it easier for other Python project members to refer issues to the
LaTeX-willing as needed.  At least better document the policy in general and
make sure project members know how to get someone to handle TeXification.


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Fred Drake-3
In reply to this post by Martin Blais-2
On Thursday 22 December 2005 10:06, Martin Blais wrote:
 > Convert it to LaTeX (it's easy) and submit it.

Or just submit as ReST, and request conversion.  I like spending my time in
XEmacs.  :-)

 > The LaTeX input format using the macros from the python docs is very
 > simple.  Converting your document should be easy.

This is mostly true; some LaTeXishness can be subtle.  If someone does want to
do their own LaTeX, that's fine, and I try to make the documentation for the
Python-specific macros fairly complete ("Documenting Python":
http://docs.python.org/doc/doc.html).  If there are questions after reading
that, I'm glad to answer them and improve that document as well.


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Fred Drake-3
In reply to this post by Martin Blais-2
On Thursday 22 December 2005 10:47, Martin Blais wrote:
 > Well, be disappointed.
 > It does not currently, and most likely won't.

Yes and no.

Docutils provides support for creating new directives ("dot-dot things") and
interpreted text roles (":colon: things").  These would go a long way to
doing what we want, and some experimentation was done toward this
specifically to support documenting Python modules in a style similar to the
standard library documentation.  This is somewhere in the docutils sandbox.

 > guessing structure from simple text files.  Even if this is not the
 > case, extending ReST to include keywords for functions, variables,
 > classes, lists of arguments, etc.  would render it into just an
 > equally ugly form of input equivalent to the current LaTeX sources,
 > ... and without the power of expression of TeX macros!

Whether :function:`os.popen()` is any uglier than \function{os.popen()} is
largely a matter of what you're used to.  I will note that the LaTeX version
is one character shorter.  :-)

I think there are appealing qualities to both the TeX macros and the
availability of the docutils document object model.  Both allow for lots of
neat things.

 > What sucks now is the inflexibliity of the produced document: the
 > tools to convert from the LaTeX sources to other formats are nothing
 > short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we
 > could obtain some kind of meaningful intermediate representation from

Yes, that is the biggest source of pain.

 > the source, from which we could then generate various output formats
 > (a bit like how docutils is structured).  I saw some project like that
 > a while ago, generating XML from LaTeX sources, never had time to
 > check it out more seriously.

I should get back to that; as someone else noted, the code is really old, and
doesn't support everything in the current LaTeX markup.


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Martin Blais-2
On 12/22/05, Fred L. Drake, Jr. <[hidden email]> wrote:

> On Thursday 22 December 2005 10:47, Martin Blais wrote:
>  > Well, be disappointed.
>  > It does not currently, and most likely won't.
>
> Yes and no.
>
> Docutils provides support for creating new directives ("dot-dot things") and
> interpreted text roles (":colon: things").  These would go a long way to
> doing what we want, and some experimentation was done toward this
> specifically to support documenting Python modules in a style similar to the
> standard library documentation.  This is somewhere in the docutils sandbox.

It would still not be significantly better than using LaTeX.
if it's not better, why change?


>  > guessing structure from simple text files.  Even if this is not the
>  > case, extending ReST to include keywords for functions, variables,
>  > classes, lists of arguments, etc.  would render it into just an
>  > equally ugly form of input equivalent to the current LaTeX sources,
>  > ... and without the power of expression of TeX macros!
>
> Whether :function:`os.popen()` is any uglier than \function{os.popen()} is
> largely a matter of what you're used to.  I will note that the LaTeX version
> is one character shorter.  :-)

It's not just that: the LaTeX macro call allows variations (e.g.
optional arguments) that the ReST form does not allow.   It's more
powerful.

Also, the dot-dot directives impose constraints on the layout contents
(has to be indented), which for some uses can make them awkward to
use.  The LaTeX model (delimiting with {}, not caring about
whitespace) is more flexible.


> I think there are appealing qualities to both the TeX macros and the
> availability of the docutils document object model.  Both allow for lots of
> neat things.

Apart from the syntax and a little less markup, I would like to know
are those qualities is that thing that are better with ReST than in
the LaTeX model.  The only thing I can see is the ease of conversion.
Everything else is less convenient.


>  > What sucks now is the inflexibliity of the produced document: the
>  > tools to convert from the LaTeX sources to other formats are nothing
>  > short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we
>  > could obtain some kind of meaningful intermediate representation from
>
> Yes, that is the biggest source of pain.
>
>  > the source, from which we could then generate various output formats
>  > (a bit like how docutils is structured).  I saw some project like that
>  > a while ago, generating XML from LaTeX sources, never had time to
>  > check it out more seriously.
>
> I should get back to that; as someone else noted, the code is really old, and
> doesn't support everything in the current LaTeX markup.

Oh, you did that?  What a wizard :-)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: reStructuredText v. LaTeX

Fred Drake-3
Note the new subject line; it's a not-so-subtle hint that this is a dying
thread. :-)

On Thursday 22 December 2005 11:53, Martin Blais wrote:
 > It would still not be significantly better than using LaTeX.
 > if it's not better, why change?

I'm not proposing change.  Just noting what's been considered.  (I'm also not
ruling out change; my priority on the matter is high-quality documentation,
not toolchain.)

 > It's not just that: the LaTeX macro call allows variations (e.g.
 > optional arguments) that the ReST form does not allow.   It's more
 > powerful.

Yes, it is.  Sometimes that's good.

 > Also, the dot-dot directives impose constraints on the layout contents
 > (has to be indented), which for some uses can make them awkward to
 > use.  The LaTeX model (delimiting with {}, not caring about
 > whitespace) is more flexible.

Yes.  I think that's a bigger problem for the Python documentation.

 > Apart from the syntax and a little less markup, I would like to know
 > are those qualities is that thing that are better with ReST than in
 > the LaTeX model.  The only thing I can see is the ease of conversion.
 > Everything else is less convenient.

The benefit of ReST is the document object model that's available.  Tools can
be written to use that to create new features (such as navigational aids).

 > Oh, you did that?  What a wizard :-)

Either that, or a lunatic.  ;-)


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Laura Creighton
In reply to this post by Michael Foord
Is there a list somewhere of exactly what it is that would need to be
added to ReST in order to support writing Python documentation in
ReST?

Laura

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Fredrik Lundh
In reply to this post by Fred Drake-3
Fred L. Drake, Jr. wrote:

> Whether :function:`os.popen()` is any uglier than \function{os.popen()} is
> largely a matter of what you're used to.  I will note that the LaTeX version
> is one character shorter.  :-)

javadoc's

    {@link os.popen}

is even shorter.

hmm.  maybe a combination of rest/html/whatever and pythondoc markup
would be the ultimate tool for the library reference...

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Martin Blais-2
On 12/22/05, Fredrik Lundh <[hidden email]> wrote:

> Fred L. Drake, Jr. wrote:
>
> > Whether :function:`os.popen()` is any uglier than \function{os.popen()} is
> > largely a matter of what you're used to.  I will note that the LaTeX version
> > is one character shorter.  :-)
>
> javadoc's
>
>     {@link os.popen}
>
> is even shorter.
>
> hmm.  maybe a combination of rest/html/whatever and pythondoc markup
> would be the ultimate tool for the library reference...

<* heavy clapping sound of my footsteps while running away screaming in fear *>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Python Tutorial - urllib2

Fredrik Lundh
Martin Blais wrote:

> > javadoc's
> >
> >     {@link os.popen}
> >
> > is even shorter.
> >
> > hmm.  maybe a combination of rest/html/whatever and pythondoc markup
> > would be the ultimate tool for the library reference...
>
> <* heavy clapping sound of my footsteps while running away screaming in fear *>

really?  so what's so problematic with

    Converts a Python tuple or a Fault instance to an XML-RPC request.

    @def dumps(params, **options)
    @param params A tuple or {@link Fault} instance.
    @keyparam methodname If given, create a methodCall request for
        this method name.
    @keyparam methodresponse If given, create a methodResponse packet.
        If used with a tuple, the tuple must be a singleton (that is,
        it must contain exactly one element).
    @keyparam encoding The encoding to use for this request. Defaults to
        UTF-8.
    @return A string containing marshalled data.

compared to

    \begin{funcdesc}{dumps}{params\optional{, methodname\optional{,
                            methodresponse\optional{, encoding}}}}
    Convert \var{params} into an XML-RPC request.
    or into a response if \var{methodresponse} is true.
    \var{params} can be either a tuple of arguments or an instance of the
    \exception{Fault} exception class.  If \var{methodresponse} is true,
    only a single value can be returned, meaning that \var{params} must be of length 1.
    \var{encoding}, if supplied, is the encoding to use in the generated
    XML; the default is UTF-8.
    \end{funcdesc}

given that the former can be trivially converted to a well-defined information
model:

    <function name="xmlrpclib.dumps">
        <info>
            <name>dumps</name>
            <summary>Convert a Python tuple or a Fault instance to an
                XML-RPC request.</summary>
            <description>Convert a Python tuple or a Fault instance to an
                XML-RPC request.</description>
            <def>dumps(params, **options)</def>
            <param name="params">A tuple or Fault instance.</param>
            <keyparam name="methodname">If given, create a methodCall
                request for this method name.</keyparam>
            <keyparam name="methodresponse">If given, create a
                methodResponse packet. If used with a tuple, the tuple must
                be a singleton (that is, it must contain exactly one element).
                </keyparam>
            <keyparam name="encoding">The request encoding. Defaults to
                UTF-8.</keyparam>
            <return>A string containing marshalled data.</return>
        </info>
    </function>

for further processing, while the latter results in a nice

    <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
      <td><nobr><b><tt id='l2h-3717' xml:id='l2h-3717' class="function">dumps</tt></b>(</nobr></td>
      <td><var>params</var><big>[</big><var>, methodname</var><big>[</big><var>,
                     methodresponse</var><big>[</big><var>, encoding</var><var></var><big>]
        </big><var></var><big>]    </big><var></var><big>]</big><var></var>)
        </td></tr></table></dt>
    <dd>
    <P>
    Convert <var>params</var> into an XML-RPC request.
    or into a response if <var>methodresponse</var> is true.
    <var>params</var> can be either a tuple of arguments or an instance of the
    <tt class="exception">Fault</tt> exception class.  If <var>methodresponse</var> is true,
    only a single value can be returned, meaning that <var>params</var> must be of length 1.
    <var>encoding</var>, if supplied, is the encoding to use in the generated
    XML; the default is UTF-8.
    </dl>

tag soup.

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig