documentation: what is "::="?

[George Sakkis]

On Oct 13, 5:33 pm, Anita Kean <ak... at paradise.net.nz> wrote:

> Hello
>
> I just downloaded the new python2.6 documentation,
> full of hopes it would solve some basic mysteries for me.
> I'm new to python, so please forgive my ignorance.
> I've two questions.
>
> 1) Everywhere in the old and new documentation, the
> string of characters "::=" is used in "explaining" things - but
> I can nowhere find any stated meaning of this string.
> I've had no luck searching on it on search engines -
> and even less if I don't quote it - the search engine returns an
> error.
>
> I couldn't find one occurrence of it in the new 2.6 tutorial,
> nor in the sphinx-generated index of symbols, where "==" and
> other character strings appear.
> But for example in the reference directory, a grep on "::="
> returns many many hits,
> and the first one in simple_stmts.html (which I sort of
> hoped _would_ be simple) was (quote):
>
>
>
> > Simple statements¶
>
> >    Simple statements are comprised within a single logical line. Several
> >    simple statements may occur on a single line separated by semicolons.
> >    The syntax for simple statements is:
> > simple_stmt ::=  expression_stmt
> >                  | assert_stmt
> >                  | assignment_stmt
> >                  | augmented_assignment_stmt
> >                  | pass_stmt
> >                  | del_stmt
> >                  | print_stmt
> >                  | return_stmt
> >                  | yield_stmt
> >                  | raise_stmt
> >                  | break_stmt
> >                  | continue_stmt
> >                  | import_stmt
> >                  | global_stmt
> >                  | exec_stmt
>
> > Expression statements¶
> > ...
>
> (unquote)
>
> So what's the relationship between the left and right hand sides of the "::="
> string here?
>
> 2) There is one other symbol the Python documentation seems to have appropriated
> but never documents which I also come up against constantly, but which is never
> defined - its use of "<==>"
>
> e.g. in the os module docs
>         __str__(...)
>      |      x.__str__() <==> str(x)
>
> (and that's all there is on __str__ in os)
>
> I'm guessing something like "if and only if" is implicated here?
> But for example, if I import the sys module and perform the following three
> commands,
>         print sys.path
>         sys.path.__str__()
>         str(sys.path)
>
> the first two give me the python path, and the last reports an error:
>
> > >>> str(sys.path)
> > Traceback (most recent call last):
> >   File "<stdin>", line 1, in <module>
> >   File "/usr/lib/python2.5/locale.py", line 244, in str
> >     return format("%.12g", val)
> >   File "/usr/lib/python2.5/locale.py", line 147, in format
> >     formatted = percent % value
> > TypeError: float argument required
>
> What is it I'm not understanding here?
>
> Are "::=" and "<==>" documented anywhere in the python docs?

Neither of these is a valid Python operator. '::=' is Backus-Naur Form
(BNF) metasyntax [1]; it's a general syntax to express context free
grammars. "<==>" typically denotes mathematical equivalence; it is
used informally in the docs to express that two expression are
equivalent.

I can't tell why you get an error on str(sys.path); it works fine
here. Something is probably wrong with your installation or locale
configuration.

George

[1] http://en.wikipedia.org/wiki/Backus-Naur_form