documentation: what is "::="?

Anita Kean

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

Oct 13 '08 #1

Diez B. Roggisch

Anita Kean schrieb:

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?

http://en.wikipedia.org/wiki/Extende...80%93Naur_Form

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?

It's equivalence, like in

x = 2 <==2*x = 4

Diez

Oct 13 '08 #2

George Sakkis

On Oct 13, 5:33 pm, Anita Kean <ak...@paradise.net.nzwrote:

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 isnever
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

Oct 13 '08 #3

Terry Reedy

Anita Kean wrote:

>
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.

Read Reference manual introductin notation:
The descriptions of lexical analysis and syntax use a modified BNF
grammar notation. This uses the following style of definition:

name ::= lc_letter (lc_letter | "_")*
lc_letter ::= "a"..."z"

The first line says that a name is an lc_letter followed by a sequence
of zero or more lc_letters and underscores. An lc_letter in turn is any
of the single characters 'a' through 'z'. (This rule is actually adhered
to for the names defined in lexical and grammar rules in this document.)

....

I'm guessing something like "if and only if" is implicated here?

yes

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?

You should include the data that gives you such puzzling output ;-).
What did print sys.path produce?
Just typing sys.path at >>should have the same effect as str(sys.path).

Oct 14 '08 #4

Peter Otten

Anita Kean wrote:

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?

Before these three commands you have probably executed

from locale import *

This has imported the locale.str() function that now shadows the builtin
str(). Had you imported locale with

import locale

(which is the recommended approach unless you're really know what you're
doing) you would have gained access to the functions in the module as, e.
g.

locale.str(...)

and still be able to access the built-ins in the usual way.

Peter

Oct 14 '08 #5

Lawrence D'Oliveiro

In message <gd*************@news.t-online.com>, Peter Otten wrote:

... you have probably executed

from locale import *

This has imported the locale.str() function that now shadows the builtin
str().

One of many reasons not to use wildcard imports. :)

Oct 14 '08 #6

Anita Kean

On 2008-10-14, Peter Otten <__*******@web.dewrote:

Anita Kean wrote:

>>...
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:

>>>
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

...
Before these three commands you have probably executed

from locale import *

This has imported the locale.str() function that now shadows the builtin
str(). Had you imported locale with

import locale

(which is the recommended approach unless you're really know what you're
doing) you would have gained access to the functions in the module as, e.
g.

locale.str(...)

and still be able to access the built-ins in the usual way.

That's correct.
I found that line in my .pystartup file yesterday and commenting it out
solved the problem.
I recall when I initially started using python, scrambling to find
some way to enable persistent history across sessions (something I
was used to in many other apis) and copying some suggested .pystartup
to enable this.
It solved the problem at the time, only to create others.

Thanks Peter.

And thanks everyone for the pointers on ::=
I'm still curious about why isn't it documented if it's used so much
in the documentation and is known by another name.
Obviously Wikipedia seems to think it's not totally obvious if they
have an entry.
It sure would have made the python docs easier to read!

Anita

Oct 14 '08 #7

Lawrence D'Oliveiro

In message <sl******************@localhost.localdomain>, Anita Kean wrote:

I'm still curious about why isn't ["::="] documented ...

It is <http://docs.python.org/reference/introduction.html#id2>.

Oct 15 '08 #8