How to read APIs (Python)(PyBrain)

[K29]

I am having trouble getting the hang of understanding APIs. After going through tutorials I find myself wanting to see what parameters I can pass to an object. So I look in the api and I see stuff like *args and **kwargs

e.g.
http://pybrain.org/docs/api/structu...pybrain.structure.networks.FeedForwardNetwork

I've looked everywhere to try and find what those *args consist of, but I'm at a loss. Anyone frequently consult API documentation and know what I should be reading?

 

[Mark44]

I am having trouble getting the hang of understanding APIs. After going through tutorials I find myself wanting to see what parameters I can pass to an object. So I look in the api and I see stuff like *args and **kwargs

e.g.
http://pybrain.org/docs/api/structu...pybrain.structure.networks.FeedForwardNetwork

I've looked everywhere to try and find what those *args consist of, but I'm at a loss. Anyone frequently consult API documentation and know what I should be reading?

The docs in the link you provided are pretty poor, IMO, as they don't give any information about the arguments of the functions listed, such as what they represent and their types.

About all that one can infer from this page are that arg represents a pointer to something, and that kwargs is a pointer to a pointer to something. In other words, arg holds the address of something, and kwargs holds an address that is the address of something.

 

[jim mcnamara]

This looks like something where you will have to find an associated forum and look at the FAQ. And it does not appear to actively maintained. Which is a bad sign. I would start by reading through this page:

http://pybrain.org/docs/modindex.html The documentation appears more sensible there. You can backwards relate the class information down to the API.

 

[D H]

Even worse, the **args argument to class pybrain.structure.networks.Network(name=None, **args) should have been **kwargs.

Sometimes the only way to see how those extra list arguments (*args) and keyword arguments (**kwargs) are used is to RTFC ("Read The Ffing Code").

This is a dirty little secret to python: You can write functions that take a variable number of positional arguments, and an arbitrary dictionary of keyword arguments. That extra kruft is what these *args and **kwargs are receiving. This approach is often used in constructors of derived classes so that stuff not needed by the derived class but is needed by a base class can be easily collected and passed to the base class constructors.Addendum
See the latter half of section 4.7.2 plus sections 4.7.3 and 4.7.4 in the python tutorial. Link: http://docs.python.org/2/tutorial/controlflow.html#keyword-arguments.

 

[Ibix]

Expanding slightly on what D H says, a function taking the arguments (*args,**kwargs) can take any parameters at all. If you run:

def f(*args,**kwargs):
    print args
    print kwargs

f(1,2,3,x=1,y="n")

you'll find that args is a list containing all of the "bare" parameters ([1,2,3], in this case), and kwargs is a dict containing all of the keyword parameters keyed by the keywords(["x":1,"y":"n"], in this case). So the docs tell you precisely nothing. You'll have to either look at the code or try to talk to someone who knows what they're talking about.

I note that the index page (http://pybrain.org/docs/index.html) links to a Google Group that might be able to help. It requires you to sign up to see, which I haven't done, so I don't know if it's active at all.

 

[K29]

Thanks for all the help everyone.

I tried the modindex first. But its links into the API. Going up the class tree didnt reveal anything new to me as far as **args go. Well I tried the google group first. It looked somewhat active, but after 12 hours of no response I decided to read the code. To be honest reading the code was simple enough. In fact, there was one place in the API that said something along the lines of "this is not all the methods that are available." Very poor documentation indeed. Fortunately the source is very neat and clearly commented.

Also thanks all for the explanations of **args and **kwargs. I was unaware of that.