pop() clarification

[sjdevnull at yahoo.com]

Carl Banks wrote:
> On Apr 11, 3:10 pm, "7stud" <bbxx789_0... at yahoo.com> wrote:
> > On Apr 11, 10:44 am, "Scott" <s_brosci... at comcast.net> wrote:
> >
> >
> >
> > > As said before I'm new to programming, and I need in depth explaination to
> > > understand everything the way I want to know it, call it a personality quirk
> > > ;p.
> >
> > > With pop() you remove the last element of a list and return its value:
> >
> > > Now I know list is a bad name, but for the sake of arguement lets assume its
> > > not a built in sequence>
> >
> > > >>>list = ['this', 'is', 'an', 'example']
> > > >>>list.pop()
> > > 'example'
> > > >>>list
> >
> > > ['this', 'is', 'an']
> >
> > > I understand all that.  What I don't understand is why all the documentation
> > > I see says, "When removing a specific element from a list using pop() it
> > > must be in this format: list.pop([i]).
> > > At first I took that to mean that list.pop(i) would return some type of
> > > error, but it doesn't.
> >
> > It's understandable that the definition of pop() is confusing in that
> > way.  It looks like the argument should be a list.  As others have
> > said, that is not what the brackets mean when the documents show the
> > formal definition of a function.
>
> I wonder if the documentation could take advantage of Python 3000
> annotation syntax.  So
>
> pop([x])
>
> would be replaced in the docs by
>
> pop(x: OPTIONAL)
>
> Just a thought, probably not a good one.  The brackets are so
> pervasive that it's probably better to just let newbies be confused
> for a little bit.

Especially since [] are used for optional arguments in many non-Python
contexts, so sticking with [] helps those coming from a background
that uses them in such a manner.