New PEP: The directive statement

[Martin von Loewis]

Please have a look at the PEP below. It is intended to replace the
__future__ import suggested in PEP 236.

Regards,
Martin

PEP: XXX
Title: The directive statement
Version: $Revision$
Author: Martin v. Löwis
Python-Version: 2.1
Status: Active
Type: Standards Track
Created: 20-Mar-2001


Motivation

    From time to time, Python makes an incompatible change to the
    advertised semantics of core language constructs, or changes their
    accidental (implementation-dependent) behavior in some way.  While this
    is never done capriciously, and is always done with the aim of
    improving the language over the long term, over the short term it's
    contentious and disrupting.

    The "Guidelines for Language Evolution" PEP [1] suggests ways to ease
    the pain, and this PEP introduces some machinery in support of that.

    The "Statically Nested Scopes" PEP [2] is the first application, and
    will be used as an example here.

    When a new, potentially incompatible language feature is added,
    some modules and libraries may chose to use it, while others may
    not. This specification introduces a syntax where a module author
    can denote whether a certain language feature shall is used in the
    module or not.

    In discussion of this PEP, readers commented that there are two
    kinds of "settable" language features:

    a) those that are designed to eventually become the only option,
       at which time specifying use of them is not necessary anymore.
       The features for which the syntax of the "Back to the
       __future__" PEP [3] was proposed fall into this category.  This
       PEP supports declaring such features, and supports phasing out
       the "old" meaning of constructs whose semantics has changed
       under the new feature. However, it defines no policy as to what
       features must be phased out eventually.

    b) those which are designed to stay optional forever, e.g. if they
       change some default setting in the interpreter. An example for
       such settings might be the request to always emit line-number
       instructions for a certain module; no specific flags of that
       kind are proposed in this specification.

    Since a primary goal of this PEP is to support new language
    constructs without immediately breaking old libraries, special
    care was taken not to break old libraries by introducing the new
    syntax.

Syntax

    A directive_statement is a statement of the form

        directive_statement: 'directive' NAME [atom] [';'] NEWLINE

    The name in the directive indicates the kind of the directive; it
    defines whether the optional atom can be present, and whether
    there are further syntactical or semantical restrictions to the
    atom. In addition, depending on the name of the directive, certain
    additional syntactical or semantical restrictions may be placed on
    the directive (e.g. placement of the directive in the module may be
    restricted to the top of the module).

    In the directive_statement, 'directive' is a new
    keyword. According to [1], this keyword is initially considered as
    a keyword only when used in a directive statement, see "Backwards
    Compatibility" below.

Semantics

    A directive statement instructs the Python interpreter to process
    a source file in a different way; the specific details of that
    processing depend on the directive name. The optional atom is
    typically interpreted when the source code is processed; details
    of that interpretation again depend on the directive.

Specific Directives: transitional

    If a syntactical or semantical change is added to Python which is
    incompatible, [1] mandates a transitional evolution of the
    language, where the new feature is initially available alongside
    with the old one. Such a transition is possible by means of the
    transitional directive.

    In a transitional directive, the NAME is 'transitional'. The atom
    MUST be present, and it MUST be a NAME. The possible values for
    that name are defined when the language change is defined. One
    example for such a directive is

    directive transitional nested_scopes

    The transitional directive MUST occur at before any other
    statement in a module, except for the documentation string
    (i.e. it may appear as the second statement of a module only if
    the first statement is a STRING+).

Backwards Compatibility

    Introducing 'directive' as a new keyword might cause
    incompatibilities with existing code. Following the guideline in
    [1], in the initial implementation of this specification,
    directive is a new keyword only if it was used in a valid
    directive_statement (i.e. if it appeared as the first non-string
    token in a module).

Unresolved Problems:  directive as the first identifier

    Using directive in a module as

    directive = 1

    (i.e. the name directive appears as the first thing in a module)
    will treat it as keyword, not as identifier. It would be possible
    to classify it as a NAME with an additional look-ahead token, but
    such look-ahead is not available in the Python tokenizer.


Questions and Answers

    Q:  It looks like this PEP was written to allow definition of source
        code charactersets. Is that true?

    A:  No. Even though the directive facility can be extended to allow
        source code encodings, no specific directive is proposed.

    Q:  Then why was this PEP written at all?

    A:  It acts as a counter-proposal to [3], which proposes to
        overload the import statement with a new meaning. This PEP
        allows to solve the problem in a more general way.

    Q:  But isn't mixing source encodings and language changes like
        mixing apples and oranges?

    A:  Perhaps. To address the difference, the predefined
        "transitional" directive has been defined.

Copyright

    This document has been placed in the public domain.


References and Footnotes

    [1] http://python.sourceforge.net/peps/pep-0005.html

    [2] http://python.sourceforge.net/peps/pep-0227.html

    [3] http://python.sourceforge.net/peps/pep-0236.html



Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: