documentation: what is "::="?

Anita Kean akean at paradise.net.nz
Mon Oct 13 23:33:38 CEST 2008


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?
Thanks 
Anita





More information about the Python-list mailing list