Learning python, but docs seem incomplete/disorganized?

Jumpfroggy · October 14, 2009, 4:23pm

I was looking at one of the sample files, hangman.py, to get a quick
view of what wxPython looks like. I saw this line:

self.wnd.Bind(wx.EVT_CHAR, self.OnChar)

In an object derived from wxFrame, so I went to the docs to find out
more about this function. This led me to this page:
http://docs.wxwidgets.org/stable/wx_wxframe.html#wxframe

However, the Bind() member function does not exists for the wxFrame
class. This is confusing, since it's clearly being used and does not
cause any errors in the sample program. Then I look at each of the
base classes in turn, especially wxEvtHandler. Still no Bind() member
function.

Eventually, through some google searching, I find this page:
http://docs.wxwidgets.org/trunk/classwx_evt_handler.html#84b1e446053bda8f76f13336839e8b64

What is this different documentation? How can I get to it from the
main page, and why are there two sets of docs? (not just stable vs.
trunk, but two completely different styles of docs with different navs
and different information on the same classes) Moreover, why isn't
Bind() in the first set of docs at docs.wxwidgets/stable?

I'm trying to learn python, but first I've got to figure out how the
documentation is arranged before I can really learn anything more,
since right now it seems like the first set is incomplete. Thanks!

Gadget_Steve · October 14, 2009, 5:43pm

I agree that the wxPython documentation is sometimes a little confusing, (especially regarding Bind), this is basically a result of the fact that it is documenting the C++ classes with occasional reference to Python and Perl where they differ. In a lot of cases you need to look at the documentation for the classes that the specific item is based on to find all the functions that are available. The Bind function is hidden as in C++ it is more usual to use the event macros to bind the events for you - so these are documented an the actual event names and bind functions are usually not.

Personally I find the examples in the wxPython demo from the Demo and Docs package contains a large number of useful examples to work from and there are a number of books, (some for free download), that can help a lot also, (a quick creep as several of the authors are here in the newsgroup).

Best of luck and enjoy learning Python and wxPython - from the sound of it you are trying to do both at the same time - I was lucky that I have a lot of experience of using wxWidgets in C and C++ before I met the old snake.

GadgetSteve

Cody · October 14, 2009, 6:10pm

Hi,

I was looking at one of the sample files, hangman.py, to get a quick
view of what wxPython looks like. I saw this line:

self.wnd.Bind(wx.EVT_CHAR, self.OnChar)

In an object derived from wxFrame, so I went to the docs to find out
more about this function. This led me to this page:
http://docs.wxwidgets.org/stable/wx_wxframe.html#wxframe

However, the Bind() member function does not exists for the wxFrame
class. This is confusing, since it's clearly being used and does not
cause any errors in the sample program. Then I look at each of the
base classes in turn, especially wxEvtHandler. Still no Bind() member
function.

You just need to keep following the class hierarchy. (which is shown
on the top of each classes documentation page).

i.e)

wxFrame Derives from TopLevelWindow, which in turn derives from
Window, ..., Derives from EvtHandler.

Only the methods implemented directly by that class are shown on each
classes page, which makes it easier to reference things and prevents
duplication. Most api documentation is this way (see msdn for
example).

What is this different documentation? How can I get to it from the
main page, and why are there two sets of docs? (not just stable vs.
trunk, but two completely different styles of docs with different navs
and different information on the same classes) Moreover, why isn't
Bind() in the first set of docs at docs.wxwidgets/stable?

wxPython is a Python wrapper around the C++ wxWidgets library. The
first set of documentation is for wxWidgets. The second link (New
Documentation) is the python specific documentation.

Cody

···

On Wed, Oct 14, 2009 at 11:23 AM, Jumpfroggy <rocketmonkeys@gmail.com> wrote:

Jumpfroggy · October 14, 2009, 8:40pm

First off, thanks everyone for the quick (!) feedback. Responses
below.

The Bind function is hidden as in C++ it is more usual
to use the event macros to bind the events for you - so these are documented
an the actual event names and bind functions are usually not.

Is this practice different in python? If not, the sample should
probably be different. It makes more sense to show users how they're
supposed to do things in the examples & learning docs, vs. showing
them 'discouraged' or 'unpopular' methods. If there's a better way,
I'd love to use that instead. At any rate, even if a function is not
commonly used, it should probably still be possible to find the
documentation for it w/o jumping through too many hoops (even if it's
something like 'use X instead', which would be helpful).

Best of luck and enjoy learning Python and wxPython - from the sound of it
you are trying to do both at the same time - I was lucky that I have a lot
of experience of using wxWidgets in C and C++ before I met the old snake.

Thanks for the well wishes! I'm experienced in Python and C++, but
I'm trying to bite the bullet and finally learn GUI programming. It
is a bit confusing that wxPython docs seem less complete than the C++
version, which is understandable considering the history of the
projects. I'm trying to figure out where the problem lies, and if
there's anything I can do (as a newcomer) to help fix it.

You just need to keep following the class hierarchy. (which is shown
on the top of each classes documentation page).
i.e)
wxFrame Derives from TopLevelWindow, which in turn derives from
Window, ..., Derives from EvtHandler.

I think the flow might be broken here. If I go to the wxpython.org
docs link, then click on "Classes by category", then click on wxFrame,
I get to (http://docs.wxwidgets.org/stable/wx_wxframe.html#wxframe).
Then under "Derived from" I click on wxEvtHandler and get to (http://
docs.wxwidgets.org/stable/wx_wxevthandler.html#wxevthandler). There
is no mention of Bind() on that page at all, so from this we'd assume
that the wxEvtHandler class does not define a Bind() member function.
This is the problem with the docs I was referring to. That second
link I found mentions it, but there doesn't seem to be a way to get
there from the first docs. I'm trying to figure out why Bind() is on
the second docs and not the first, and how the first & second docs are
different, and how to get from one to the other.

Only the methods implemented directly by that class are shown on each
classes page, which makes it easier to reference things and prevents
duplication. Most api documentation is this way (see msdn for
example).

This style of docs makes it easier for the scenario, "I already know
the base object, so what new things does this derived class give me?"
It's less helpful for a newcomer's scenario, "What can I use this
class for?" In the second scenario, a newcomer (like me) is hindered
more by having to search through multiple pages of classes to find
what member functions are available, and how they relate, just to find
out "What can I do?" and "Which function should I use?". I've seen
other docs with this type of format:

class wxFrame

Member Functions:

    a()
    b()
    c()

Inherited member functions

    w() (from wxEvtHandler)
    x() (from wxObject)
    y() (from wxWindow)
    z() (from wxWindow)

This makes it easy to tell at a glance everything that this class can
do (without having to already know 4 other base classes). It is
duplication of text, but it's also a lot more useful. And the amount
of duplication is very small; just a link to another page with an
anchor to that specific function. I like this method of docs, and
it's always seemed to help me learn libraries more quickly, and even
later when I know things it still helps to be able to reference a
single page for a single class, vs. multiple pages all the time.

wxPython is a Python wrapper around the C++ wxWidgets library. The
first set of documentation is for wxWidgets. The second link (New
Documentation) is the python specific documentation.

The first link I put was (wxWidgets: Documentation
wx_wxframe.html), and the second was (wxWidgets: Documentation
classwx_evt_handler.html). Both are on docs.wxwidgets.org, and both
seem to be for the C++ version of the wx framework. More confusingly,
these:

http://docs.wxwidgets.org/stable/wx_wxevthandler.html
http://docs.wxwidgets.org/trunk/classwx_evt_handler.html

Are two different docs for the same wxEvtHandler in C++. However, one
is a completely different style than the other, and only one mentions
Bind() at all (even though it should exist in both). Did the
documentation-generation backend change between the stable & trunk
versions? The question still remains, where is the documentation for
Bind() in the stable docs?

···

On Oct 14, 1:43 pm, <GadgetSt...@live.co.uk> wrote:
On Oct 14, 2:10 pm, Cody Precord <codyprec...@gmail.com> wrote:

--

Thanks for all your feedback, I've tried to learn wxPython a few times
but always gave up since the docs were very confusing. I'm trying to
stick it out so I can finally start enjoying GUI-goodness on my hobby
utilities that I keep writing. I hope that my criticisms are
constructive and not offensive, as I really do want to help improve
wxPython any way I can.

Robin · October 14, 2009, 9:47pm

Eventually, through some google searching, I find this page:
wxWidgets: wxEvtHandler Class Reference

This is the docs for the 2.9.x version of wxWidgets.

What is this different documentation? How can I get to it from the
main page, and why are there two sets of docs? (not just stable vs.
trunk, but two completely different styles of docs with different navs
and different information on the same classes) Moreover, why isn't
Bind() in the first set of docs at docs.wxwidgets/stable?

Because it is a Python-only function that doesn't have a matching method in the 2.8 C++ code. (In 2.9 something like it has been added because the C++ guys liked it, but wxPython will still be keeping its version unless there is some compelling reason not to.)

The docs for the wxPython Bind is here in the Python-specific version of the docs[1]:

wxPython API Documentation — wxPython Phoenix 4.2.2 documentation

Or you can get it by typing "pydoc wx.EvtHandler.Bind" on a command line. (Or "pydoc wx.Frame.Bind" would work too.)

Eventually we will be attempting to generate the Python wx docs from the same source that the C++ wx docs are coming from, with the Python specific things merged in. In the meantime, most people are fairly successful using the examples in the demo and the wiki to learn from, and using a combination of the C++ docs and the Python docs for reference. And there is always the book: wxPythonInAction - wxPyWiki, and if you haven't seen it yet be sure to read the tutorial at wxPython tutorial - Python GUI programming in wxPython

[1] This was an attempt from a few years ago to have a Python specific version of the docs be generated directly from the wrapper interface files so it would include exactly what is in wxPython and not force the reader to filter through the C++ specific stuff. The effort stalled after a while because of the amount of work needed to create it, but there is still a lot of good info there. For example there is at least an auto-generated stub for every wrapper method that shows the expected parameters, uses the name visible to Python which may be different than C++ if it's overloaded, etc. I expect that once the tools are created for the new docs version alluded to above are in place then keeping the docs in sync will be fairly easy and we won't have to keep making apologies.

···

On 10/14/09 9:23 AM, Jumpfroggy wrote:

--
Robin Dunn
Software Craftsman

Robin · October 14, 2009, 9:47pm

Bind is the right way to do it in Python.

···

On 10/14/09 1:40 PM, Jumpfroggy wrote:

First off, thanks everyone for the quick (!) feedback. Responses
below.

On Oct 14, 1:43 pm,<GadgetSt...@live.co.uk> wrote:

The Bind function is hidden as in C++ it is more usual
to use the event macros to bind the events for you - so these are documented
an the actual event names and bind functions are usually not.

Is this practice different in python? If not, the sample should
probably be different. It makes more sense to show users how they're
supposed to do things in the examples& learning docs, vs. showing
them 'discouraged' or 'unpopular' methods. If there's a better way,
I'd love to use that instead. At any rate, even if a function is not
commonly used, it should probably still be possible to find the
documentation for it w/o jumping through too many hoops (even if it's
something like 'use X instead', which would be helpful).

--
Robin Dunn
Software Craftsman

Mike_Conley · October 14, 2009, 9:51pm

Try this page for better organization

http://xoomer.virgilio.it/infinity77/wxPython/index.html

and go to the link at bottom of page.

I was able to search for and find Bind in this documentation set. Granted the documentation is pretty sparse for Bind and I don’t know how much help it gives a newbie, but since it is based on the wxwidgets docs, there isn’t much the python people can do about that. Other items are much more complete.

I’m not sure of the history of this site, but I think there is also an effort to make the official wxPython docs more complete and easier to use. I think the newer version is available somewhere.

I think the wxWidgets folks are in the process of redoing their docs also. If so, that explains most of the differences you see between “stable” (=released or very nearly there) and “trunk” (=best we have in development) versions.

If you search the newsgroup
http://groups.google.com/group/wxpython-users
you will also find other threads about documentation that might help.

Steven_Sproat · October 14, 2009, 9:53pm

Jumpfroggy wrote:

First off, thanks everyone for the quick (!) feedback. Responses
below.

[snip snap]

By the way, you are looking at the wrong documentation.

http://www.wxpython.org/docs/api/wx.EvtHandler-class.html

The Bind is implemented in Python, as seen:

    def Bind(self, event, handler, source=None, id=wx.ID_ANY,
id2=wx.ID_ANY):
        """
        Bind an event to an event handler.
        """
        if source is not None:
            id = source.GetId()
        event.Bind(self, id, id2, handler)

which is calling Bind in PyEvtHandler

class PyEventBinder(object):
    """
    Instances of this class are used to bind specific events to event
    handlers.
    """
[....]

    def Bind(self, target, id1, id2, function):
        """Bind this set of event types to target."""
        for et in self.evtType:
            target.Connect(id1, id2, et, function)

You may wish to take a look through the wiki for some great starting
points, and just browsing some of the demos for particular widgets,
they're generally small enough demos to easily get a feel of how a
widget works.

Vlastimil_Brom · October 14, 2009, 11:41pm

Hi, to add even more to this plurality, there are inofficial versions
of the docs.
You may eventually check the alternative wxPython documentation by Andrea Gavana
http://xoomer.virgilio.it/infinity77/wxPython/index.html
Although it is experimental and maybe won't be updated, some relations
are probably quite a bit clearer here than in other docs.

e.g. to get info in Bind, you can use the "index" (top right link)
http://xoomer.virgilio.it/infinity77/wxPython/genindex.html
the item sub B ... Bind leads to
http://xoomer.virgilio.it/infinity77/wxPython/Widgets/wx.EvtHandler.html#Bind

vbr

···

2009/10/14 Jumpfroggy <rocketmonkeys@gmail.com>:

I was looking at one of the sample files, hangman.py, to get a quick
view of what wxPython looks like. I saw this line:

self.wnd.Bind(wx.EVT_CHAR, self.OnChar)

In an object derived from wxFrame, so I went to the docs to find out
more about this function. This led me to this page:
http://docs.wxwidgets.org/stable/wx_wxframe.html#wxframe

However, the Bind() member function does not exists for the wxFrame
class. This is confusing, since it's clearly being used and does not
cause any errors in the sample program. Then I look at each of the
base classes in turn, especially wxEvtHandler. Still no Bind() member
function.

Eventually, through some google searching, I find this page:
wxWidgets: wxEvtHandler Class Reference

What is this different documentation? How can I get to it from the
main page, and why are there two sets of docs? (not just stable vs.
trunk, but two completely different styles of docs with different navs
and different information on the same classes) Moreover, why isn't
Bind() in the first set of docs at docs.wxwidgets/stable?

I'm trying to learn python, but first I've got to figure out how the
documentation is arranged before I can really learn anything more,
since right now it seems like the first set is incomplete. Thanks!

>

Che_M · October 15, 2009, 12:29am

I was looking at one of the sample files, hangman.py, to get a quick
view of what wxPython looks like. I saw this line:

self.wnd.Bind(wx.EVT_CHAR, self.OnChar)

In an object derived from wxFrame, so I went to the docs to find out
more about this function. This led me to this page:
http://docs.wxwidgets.org/stable/wx_wxframe.html#wxframe

However, the Bind() member function does not exists for the wxFrame
class. This is confusing, since it's clearly being used and does not
cause any errors in the sample program. Then I look at each of the
base classes in turn, especially wxEvtHandler. Still no Bind() member
function.

Although many have given good advice here, there is also this approach:

1. Go to IDLE (or whatever Python shell you want; best if it can search text)
2. >>> import wx
3. >>> help(wx.Frame)

This will bring up ALL the methods (I think) available to wx.Frame.

4. Ctrl-F in IDLE and search for Bind( [I put the right paren to distinguish
it from other uses of the word in the docs] brings up:

> Bind(self, event, handler, source=None, id=-1, id2=-1)
> Bind an event to an event handler.
>
> :param event: One of the EVT_* objects that specifies the
> type of event to bind,
>
> :param handler: A callable object to be invoked when the
> event is delivered to self. Pass None to
> disconnect an event handler.
>
> :param source: Sometimes the event originates from a
> different window than self, but you still
> want to catch it in self. (For example, a
> button event delivered to a frame.) By
> passing the source of the event, the event
> handling system is able to differentiate
> between the same event type from different
> controls.
>
> :param id: Used to spcify the event source by ID instead
> of instance.
>
> :param id2: Used when it is desirable to bind a handler
> to a range of IDs, such as with EVT_MENU_RANGE.

HTH,
Che

···

On Wed, Oct 14, 2009 at 12:23 PM, Jumpfroggy <rocketmonkeys@gmail.com> wrote:

Che_M · October 15, 2009, 12:31am

4. Ctrl-F in IDLE and search for Bind( [I put the right paren to distinguish

[whoops, meant left paren...you get the idea]

Werner · October 15, 2009, 9:26am

C M wrote:


I was looking at one of the sample files, hangman.py, to get a quick
view of what wxPython looks like.  I saw this line:
   self.wnd.Bind(wx.EVT_CHAR, self.OnChar)
In an object derived from wxFrame, so I went to the docs to find out
more about this function.  This led me to this page:
However, the Bind() member function does not exists for the wxFrame
class.  This is confusing, since it's clearly being used and does not
cause any errors in the sample program.  Then I look at each of the
base classes in turn, especially wxEvtHandler.  Still no Bind() member
function.


Although many have given good advice here, there is also this approach:
1. Go to IDLE (or whatever Python shell you want; best if it can search text)
2. >>> import wx
3. >>> help(wx.Frame)
This will bring up ALL the methods (I think) available to wx.Frame.

Or in Boa you hit ctrl-h and type bind. Select the top option and it
will take you to wx.PyEventBinder or wx.EvtHandler doc.

Werner

P.S.

The doc in Boa is a bit out of date, 2.8.4 - one of these days I have
to figure out how to run the scripts to update this stuff.

···

rocketmonkeys@gmail.com http://docs.wxwidgets.org/stable/wx_wxframe.html#wxframe