CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 244 – The directive statement | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0244/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 244 – The directive statement | peps.python.org'> <meta property="og:description" content="Python Enhancement Proposals (PEPs)"> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0244/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Python Enhancement Proposals (PEPs)"> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 244</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 244 – The <code class="docutils literal notranslate"><span class="pre">directive</span></code> statement</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Martin von Löwis <martin at v.loewis.de></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">20-Mar-2001</dd> <dt class="field-odd">Python-Version<span class="colon">:</span></dt> <dd class="field-odd">2.1</dd> <dt class="field-even">Post-History<span class="colon">:</span></dt> <dd class="field-even"><p></p></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#syntax">Syntax</a></li> <li><a class="reference internal" href="#semantics">Semantics</a></li> <li><a class="reference internal" href="#specific-directives-transitional">Specific Directives: transitional</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#unresolved-problems-directive-as-the-first-identifier">Unresolved Problems: directive as the first identifier</a></li> <li><a class="reference internal" href="#questions-and-answers">Questions and Answers</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <p>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.</p> <p><a class="pep reference internal" href="../pep-0005/" title="PEP 5 – Guidelines for Language Evolution">PEP 5</a>, Guidelines for Language Evolution suggests ways to ease the pain, and this PEP introduces some machinery in support of that.</p> <p><a class="pep reference internal" href="../pep-0227/" title="PEP 227 – Statically Nested Scopes">PEP 227</a>, Statically Nested Scopes is the first application, and will be used as an example here.</p> <p>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 is used in the module or not.</p> <p>In discussion of this PEP, readers commented that there are two kinds of “settable” language features:</p> <ul class="simple"> <li>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 <code class="docutils literal notranslate"><span class="pre">__future__</span></code>” <a class="pep reference internal" href="../pep-0236/" title="PEP 236 – Back to the __future__">PEP 236</a>, Back to the <code class="docutils literal notranslate"><span class="pre">__future__</span></code> 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.</li> <li>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.</li> </ul> <p>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.</p> </section> <section id="syntax"> <h2><a class="toc-backref" href="#syntax" role="doc-backlink">Syntax</a></h2> <p>A directive_statement is a statement of the form:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>directive_statement: 'directive' ``NAME`` [atom] [';'] NEWLINE </pre></div> </div> <p>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).</p> <p>In the directive_statement, <code class="docutils literal notranslate"><span class="pre">directive</span></code> is a new keyword. According to <a class="pep reference internal" href="../pep-0005/" title="PEP 5 – Guidelines for Language Evolution">PEP 5</a>, this keyword is initially considered as a keyword only when used in a directive statement, see “Backwards Compatibility” below.</p> </section> <section id="semantics"> <h2><a class="toc-backref" href="#semantics" role="doc-backlink">Semantics</a></h2> <p>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 depend on the directive.</p> </section> <section id="specific-directives-transitional"> <h2><a class="toc-backref" href="#specific-directives-transitional" role="doc-backlink">Specific Directives: transitional</a></h2> <p>If a syntactical or semantical change is added to Python which is incompatible, <a class="pep reference internal" href="../pep-0005/" title="PEP 5 – Guidelines for Language Evolution">PEP 5</a> 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.</p> <p>In a transitional directive, the <code class="docutils literal notranslate"><span class="pre">NAME</span></code> is ‘transitional’. The atom MUST be present, and it MUST be a <code class="docutils literal notranslate"><span class="pre">NAME</span></code>. The possible values for that name are defined when the language change is defined. One example for such a directive is:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">directive</span> <span class="n">transitional</span> <span class="n">nested_scopes</span> </pre></div> </div> <p>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 <code class="docutils literal notranslate"><span class="pre">STRING+</span></code>).</p> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> <p>Introducing <code class="docutils literal notranslate"><span class="pre">directive</span></code> as a new keyword might cause incompatibilities with existing code. Following the guideline in <a class="pep reference internal" href="../pep-0005/" title="PEP 5 – Guidelines for Language Evolution">PEP 5</a>, 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).</p> </section> <section id="unresolved-problems-directive-as-the-first-identifier"> <h2><a class="toc-backref" href="#unresolved-problems-directive-as-the-first-identifier" role="doc-backlink">Unresolved Problems: directive as the first identifier</a></h2> <p>Using directive in a module as:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">directive</span> <span class="o">=</span> <span class="mi">1</span> </pre></div> </div> <p>(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 <code class="docutils literal notranslate"><span class="pre">NAME</span></code> with an additional look-ahead token, but such look-ahead is not available in the Python tokenizer.</p> </section> <section id="questions-and-answers"> <h2><a class="toc-backref" href="#questions-and-answers" role="doc-backlink">Questions and Answers</a></h2> <p><strong>Q:</strong> It looks like this PEP was written to allow definition of source code character sets. Is that true?</p> <p><strong>A:</strong> No. Even though the directive facility can be extended to allow source code encodings, no specific directive is proposed.</p> <p><strong>Q:</strong> Then why was this PEP written at all?</p> <p><strong>A:</strong> It acts as a counter-proposal to <a class="pep reference internal" href="../pep-0236/" title="PEP 236 – Back to the __future__">PEP 236</a>, which proposes to overload the import statement with a new meaning. This PEP allows to solve the problem in a more general way.</p> <p><strong>Q:</strong> But isn’t mixing source encodings and language changes like mixing apples and oranges?</p> <p><strong>A:</strong> Perhaps. To address the difference, the predefined “transitional” directive has been defined.</p> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0244.rst">https://github.com/python/peps/blob/main/peps/pep-0244.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0244.rst">2025-02-01 08:55:40 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#syntax">Syntax</a></li> <li><a class="reference internal" href="#semantics">Semantics</a></li> <li><a class="reference internal" href="#specific-directives-transitional">Specific Directives: transitional</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#unresolved-problems-directive-as-the-first-identifier">Unresolved Problems: directive as the first identifier</a></li> <li><a class="reference internal" href="#questions-and-answers">Questions and Answers</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0244.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>