diff options
| -rw-r--r-- | Doc/using/cmdline.rst | 409 | ||||
| -rw-r--r-- | Doc/using/index.rst | 17 | ||||
| -rw-r--r-- | Doc/using/mac.rst | 202 |
3 files changed, 628 insertions, 0 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst new file mode 100644 index 0000000..7ee9c04 --- /dev/null +++ b/Doc/using/cmdline.rst @@ -0,0 +1,409 @@ +.. highlightlang:: none + +Command line and environment +============================ + +The CPython interpreter scans the command line and the environment for various +settings. + +.. note:: + + Other implementation's command line schemes may differ. See + :ref:`implementations` for further resources. + + +Command line +------------ + +When invoking Python, you may specify any of these options:: + + python [-dEiOQStuUvxX?] [-c command | -m module-name | script | - ] [args] + +The most common use case is, of course, a simple invocation of a script:: + + python myscript.py + + +Interface options +~~~~~~~~~~~~~~~~~ + +The interpreter interface resembles that of the UNIX shell: + +* When called with standard input connected to a tty device, it prompts for + commands and executes them until an EOF (an end-of-file character, you can + produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read. +* When called with a file name argument or with a file as standard input, it + reads and executes a script from that file. +* When called with ``-c command``, it executes the Python statement(s) given as + *command*. Here *command* may contain multiple statements separated by + newlines. Leading whitespace is significant in Python statements! +* When called with ``-m module-name``, the given module is searched on the + Python module path and executed as a script. + +In non-interactive mode, the entire input is parsed before it is executed. + +An interface option terminates the list of options consumed by the interpreter, +all consecutive arguments will end up in :data:`sys.argv` -- note that the first +element, subscript zero (``sys.argv[0]``), is a string reflecting the program's +source. + +.. cmdoption:: -c <command> + + Execute the Python code in *command*. *command* can be one ore more + statements separated by newlines, with significant leading whitespace as in + normal module code. + + If this option is given, the first element of :data:`sys.argv` will be + ``"-c"``. + + +.. cmdoption:: -m <module-name> + + Search :data:`sys.path` for the named module and run the corresponding module + file as if it were executed with ``python modulefile.py`` as a script. + + Since the argument is a *module* name, you must not give a file extension + (``.py``). However, the ``module-name`` does not have to be a valid Python + identifer (e.g. you can use a file name including a hyphen). + + .. note:: + + This option cannot be used with builtin modules and extension modules + written in C, since they do not have Python module files. + + If this option is given, the first element of :data:`sys.argv` will be the + full path to the module file. + + Many standard library modules contain code that is invoked on their execution + as a script. An example is the :mod:`timeit` module:: + + python -mtimeit -s 'setup here' 'benchmarked code here' + python -mtimeit -h # for details + + .. seealso:: + :func:`runpy.run_module` + The actual implementation of this feature. + + :pep:`338` -- Executing modules as scripts + + +.. describe:: <script> + + Execute the Python code contained in *script*, which must be an (absolute or + relative) file name. + + If this option is given, the first element of :data:`sys.argv` will be the + script file name as given on the command line. + + +.. describe:: - + + Read commands from standard input (:data:`sys.stdin`). If standard input is + a terminal, :option:`-i` is implied. + + If this option is given, the first element of :data:`sys.argv` will be + ``"-"``. + + .. seealso:: + :ref:`tut-invoking` + + +If no script name is given, ``sys.argv[0]`` is an empty string (``""``). + + +Generic options +~~~~~~~~~~~~~~~ + +.. cmdoption:: -? + -h + --help + + Print a short description of all command line options. + + +.. cmdoption:: -V + --version + + Print the Python version number and exit. Example output could be:: + + Python 2.5.1 + + +Miscellaneous options +~~~~~~~~~~~~~~~~~~~~~ + +.. cmdoption:: -d + + Turn on parser debugging output (for wizards only, depending on compilation + options). See also :envvar:`PYTHONDEBUG`. + + +.. cmdoption:: -E + + Ignore all :envvar:`PYTHON*` environment variables, e.g. + :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set. + + +.. cmdoption:: -i + + When a script is passed as first argument or the :option:`-c` option is used, + enter interactive mode after executing the script or the command, even when + :data:`sys.stdin` does not appear to be a terminal. The + :envvar:`PYTHONSTARTUP` file is not read. + + This can be useful to inspect global variables or a stack trace when a script + raises an exception. See also :envvar:`PYTHONINSPECT`. + + +.. cmdoption:: -O + + Turn on basic optimizations. This changes the filename extension for + compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also + :envvar:`PYTHONOPTIMIZE`. + + +.. cmdoption:: -OO + + Discard docstrings in addition to the :option:`-O` optimizations. + + +.. cmdoption:: -Q <arg> + + Division control. The argument must be one of the following: + + ``old`` + division of int/int and long/long return an int or long (*default*) + ``new`` + new division semantics, i.e. division of int/int and long/long returns a + float + ``warn`` + old division semantics with a warning for int/int and long/long + ``warnall`` + old division semantics with a warning for all uses of the division operator + + .. seealso:: + :file:`Tools/scripts/fixdiv.py` + for a use of ``warnall`` + + :pep:`238` -- Changing the division operator + + +.. cmdoption:: -S + + Disable the import of the module :mod:`site` and the site-dependent + manipulations of :data:`sys.path` that it entails. + + +.. cmdoption:: -t + + Issue a warning when a source file mixes tabs and spaces for indentation in a + way that makes it depend on the worth of a tab expressed in spaces. Issue an + error when the option is given twice (:option:`-tt`). + + +.. cmdoption:: -u + + Force stdin, stdout and stderr to be totally unbuffered. On systems where it + matters, also put stdin, stdout and stderr in binary mode. + + Note that there is internal buffering in :meth:`file.readlines` and + :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced + by this option. To work around this, you will want to use + :meth:`file.readline` inside a ``while 1:`` loop. + + See also :envvar:`PYTHONUNBUFFERED`. + + +.. XXX should the -U option be documented? + +.. cmdoption:: -v + + Print a message each time a module is initialized, showing the place + (filename or built-in module) from which it is loaded. When given twice + (:option:`-vv`), print a message for each file that is checked for when + searching for a module. Also provides information on module cleanup at exit. + See also :envvar:`PYTHONVERBOSE`. + + +.. cmdoption:: -W arg + + Warning control. Python's warning machinery by default prints warning + messages to :data:`sys.stderr`. A typical warning message has the following + form:: + + file:line: category: message + + By default, each warning is printed once for each source line where it + occurs. This option controls how often warnings are printed. + + Multiple :option:`-W` options may be given; when a warning matches more than + one option, the action for the last matching option is performed. Invalid + :option:`-W` options are ignored (though, a warning message is printed about + invalid options when the first warning is issued). + + Warnings can also be controlled from within a Python program using the + :mod:`warnings` module. + + The simplest form of argument is one of the following action strings (or a + unique abbreviation): + + ``ignore`` + Ignore all warnings. + ``default`` + Explicitly request the default behavior (printing each warning once per + source line). + ``all`` + Print a warning each time it occurs (this may generate many messages if a + warning is triggered repeatedly for the same source line, such as inside a + loop). + ``module`` + Print each warning only only the first time it occurs in each module. + ``once`` + Print each warning only the first time it occurs in the program. + ``error`` + Raise an exception instead of printing a warning message. + + The full form of argument is:: + + action:message:category:module:line + + Here, *action* is as explained above but only applies to messages that match + the remaining fields. Empty fields match all values; trailing empty fields + may be omitted. The *message* field matches the start of the warning message + printed; this match is case-insensitive. The *category* field matches the + warning category. This must be a class name; the match test whether the + actual warning category of the message is a subclass of the specified warning + category. The full class name must be given. The *module* field matches the + (fully-qualified) module name; this match is case-sensitive. The *line* + field matches the line number, where zero matches all line numbers and is + thus equivalent to an omitted line number. + + .. seealso:: + + :pep:`230` -- Warning framework + + +.. cmdoption:: -x + + Skip the first line of the source, allowing use of non-Unix forms of + ``#!cmd``. This is intended for a DOS specific hack only. + + .. warning:: The line numbers in error messages will be off by one! + + +Related files -- UNIX +--------------------- + +These are subject to difference depending on local installation conventions; +:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``) +are installation-dependent and should be interpreted as for GNU software; they +may be the same. + +For example, on most Linux systems, the default for both is :file:`/usr`. + ++-----------------------------------------------+------------------------------------------+ +| File/directory | Meaning | ++===============================================+==========================================+ +| :file:`{exec_prefix}/bin/python` | Recommended location of the interpreter. | ++-----------------------------------------------+------------------------------------------+ +| :file:`{prefix}/lib/python{version}`, | Recommended locations of the directories | +| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. | ++-----------------------------------------------+------------------------------------------+ +| :file:`{prefix}/include/python{version}`, | Recommended locations of the directories | +| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for | +| | developing Python extensions and | +| | embedding the interpreter. | ++-----------------------------------------------+------------------------------------------+ +| :file:`~/.pythonrc.py` | User-specific initialization file loaded | +| | by the user module; not used by default | +| | or by most applications. | ++-----------------------------------------------+------------------------------------------+ + + +Environment variables +--------------------- + +.. envvar:: PYTHONHOME + + Change the location of the standard Python libraries. By default, the + libraries are searched in :file:`{prefix}/lib/python<version>` and + :file:`{exec_prefix}/lib/python<version>`, where :file:`{prefix}` and + :file:`{exec_prefix}` are installation-dependent directories, both defaulting + to :file:`/usr/local`. + + When :envvar:`PYTHONHOME` is set to a single directory, its value replaces + both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values + for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}``. + + +.. envvar:: PYTHONPATH + + Augments the default search path for module files. The format is the same as + the shell's :envvar:`PATH`: one or more directory pathnames separated by + colons. Non-existent directories are silently ignored. + + The default search path is installation dependent, but generally begins with + :file:`{prefix}/lib/python<version>`` (see :envvar:`PYTHONHOME` above). It + is *always* appended to :envvar:`PYTHONPATH`. + + If a script argument is given, the directory containing the script is + inserted in the path in front of :envvar:`PYTHONPATH`. The search path can + be manipulated from within a Python program as the variable :data:`sys.path`. + + +.. envvar:: PYTHONSTARTUP + + If this is the name of a readable file, the Python commands in that file are + executed before the first prompt is displayed in interactive mode. The file + is executed in the same namespace where interactive commands are executed so + that objects defined or imported in it can be used without qualification in + the interactive session. You can also change the prompts :data:`sys.ps1` and + :data:`sys.ps2` in this file. + + +.. envvar:: PYTHONY2K + + Set this to a non-empty string to cause the :mod:`time` module to require + dates specified as strings to include 4-digit years, otherwise 2-digit years + are converted based on rules described in the :mod:`time` module + documentation. + + +.. envvar:: PYTHONOPTIMIZE + + If this is set to a non-empty string it is equivalent to specifying the + :option:`-O` option. If set to an integer, it is equivalent to specifying + :option:`-O` multiple times. + + +.. envvar:: PYTHONDEBUG + + If this is set to a non-empty string it is equivalent to specifying the + :option:`-d` option. If set to an integer, it is equivalent to specifying + :option:`-d` multiple times. + + +.. envvar:: PYTHONINSPECT + + If this is set to a non-empty string it is equivalent to specifying the + :option:`-i` option. + + +.. envvar:: PYTHONUNBUFFERED + + If this is set to a non-empty string it is equivalent to specifying the + :option:`-u` option. + + +.. envvar:: PYTHONVERBOSE + + If this is set to a non-empty string it is equivalent to specifying the + :option:`-v` option. If set to an integer, it is equivalent to specifying + :option:`-v` multiple times. + + +.. envvar:: PYTHONCASEOK + + If this is set, Python ignores case in :keyword:`import` statements. This + only works on Windows. + diff --git a/Doc/using/index.rst b/Doc/using/index.rst new file mode 100644 index 0000000..f8d8ce4 --- /dev/null +++ b/Doc/using/index.rst @@ -0,0 +1,17 @@ +.. _using-index: + +################ + Using Python +################ + + +This part of the documentation is devoted to general information on the setup +of the Python environment on different platform, the invocation of the +interpreter and things that make working with Python easier. + + +.. toctree:: + + cmdline.rst + mac.rst + diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst new file mode 100644 index 0000000..7811f37 --- /dev/null +++ b/Doc/using/mac.rst @@ -0,0 +1,202 @@ + +.. _using-on-mac: + +*************************** +Using Python on a Macintosh +*************************** + +:Author: Bob Savage <bobsavage@mac.com> + + +Python on a Macintosh running Mac OS X is in principle very similar to Python on +any other Unix platform, but there are a number of additional features such as +the IDE and the Package Manager that are worth pointing out. + +The Mac-specific modules are documented in :ref:`mac-specific-services`. + +Python on Mac OS 9 or earlier can be quite different from Python on Unix or +Windows, but is beyond the scope of this manual, as that platform is no longer +supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for +installers for the latest 2.3 release for Mac OS 9 and related documentation. + + +.. _getting-osx: + +Getting and Installing MacPython +================================ + +Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are +encouraged to install the most recent version of Python from the Python website +(http://www.python.org). A "universal binary" build of Python 2.5, which runs +natively on the Mac's new Intel and legacy PPC CPU's, is available there. + +What you get after installing is a number of things: + +* A :file:`MacPython 2.5` folder in your :file:`Applications` folder. In here + you find IDLE, the development environment that is a standard part of official + Python distributions; PythonLauncher, which handles double-clicking Python + scripts from the Finder; and the "Build Applet" tool, which allows you to + package Python scripts as standalone applications on your system. + +* A framework :file:`/Library/Frameworks/Python.framework`, which includes the + Python executable and libraries. The installer adds this location to your shell + path. To uninstall MacPython, you can simply remove these three things. A + symlink to the Python executable is placed in /usr/local/bin/. + +The Apple-provided build of Python is installed in +:file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`, +respectively. You should never modify or delete these, as they are +Apple-controlled and are used by Apple- or third-party software. + +IDLE includes a help menu that allows you to access Python documentation. If you +are completely new to Python you should start reading the tutorial introduction +in that document. + +If you are familiar with Python on other Unix platforms you should read the +section on running Python scripts from the Unix shell. + + +How to run a Python script +-------------------------- + +Your best way to get started with Python on Mac OS X is through the IDLE +integrated development environment, see section :ref:`ide` and use the Help menu +when the IDE is running. + +If you want to run Python scripts from the Terminal window command line or from +the Finder you first need an editor to create your script. Mac OS X comes with a +number of standard Unix command line editors, :program:`vim` and +:program:`emacs` among them. If you want a more Mac-like editor, +:program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see +http://www.barebones.com/products/bbedit/index.shtml) are good choices, as is +:program:`TextMate` (see http://macromates.com/). Other editors include +:program:`Gvim` (http://macvim.org) and :program:`Aquamacs` +(http://aquamacs.org). + +To run your script from the Terminal window you must make sure that +:file:`/usr/local/bin` is in your shell search path. + +To run your script from the Finder you have two options: + +* Drag it to :program:`PythonLauncher` + +* Select :program:`PythonLauncher` as the default application to open your + script (or any .py script) through the finder Info window and double-click it. + :program:`PythonLauncher` has various preferences to control how your script is + launched. Option-dragging allows you to change these for one invocation, or use + its Preferences menu to change things globally. + + +.. _osx-gui-scripts: + +Running scripts with a GUI +-------------------------- + +With older versions of Python, there is one Mac OS X quirk that you need to be +aware of: programs that talk to the Aqua window manager (in other words, +anything that has a GUI) need to be run in a special way. Use :program:`pythonw` +instead of :program:`python` to start such scripts. + +With Python 2.5, you can use either :program:`python` or :program:`pythonw`. + + +Configuration +------------- + +Python on OS X honors all standard Unix environment variables such as +:envvar:`PYTHONPATH`, but setting these variables for programs started from the +Finder is non-standard as the Finder does not read your :file:`.profile` or +:file:`.cshrc` at startup. You need to create a file :file:`~ +/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details. + +For more information on installation Python packages in MacPython, see section +:ref:`mac-package-manager`. + + +.. _ide: + +The IDE +======= + +MacPython ships with the standard IDLE development environment. A good +introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/ +dyoo/python/idle_intro/index.html. + + +.. _mac-package-manager: + +Installing Additional Python Packages +===================================== + +There are several methods to install additional Python packages: + +* http://pythonmac.org/packages/ contains selected compiled packages for Python + 2.5, 2.4, and 2.3. + +* Packages can be installed via the standard Python distutils mode (``python + setup.py install``). + +* Many packages can also be installed via the :program:`setuptools` extension. + + +GUI Programming on the Mac +========================== + +There are several options for building GUI applications on the Mac with Python. + +*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is +the foundation of most modern Mac development. Information on PyObjC is +available from http://pyobjc.sourceforge.net. + +The standard Python GUI toolkit is :mod:`Tkinter`, based on the cross-platform +Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS +X by Apple, and the latest version can be downloaded and installed from +http://www.activestate.com; it can also be built from source. + +*wxPython* is another popular cross-platform GUI toolkit that runs natively on +Mac OS X. Packages and documentation are available from http://www.wxpython.org. + +*PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac +OS X. More information can be found at +http://www.riverbankcomputing.co.uk/pyqt/. + + +Distributing Python Applications on the Mac +=========================================== + +The "Build Applet" tool that is placed in the MacPython 2.5 folder is fine for +packaging small Python scripts on your own machine to run as a standard Mac +application. This tool, however, is not robust enough to distribute Python +applications to other users. + +The standard tool for deploying standalone Python applications on the Mac is +:program:`py2app`. More information on installing and using py2app can be found +at http://undefined.org/python/#py2app. + + +Application Scripting +===================== + +Python can also be used to script other Mac applications via Apple's Open +Scripting Architecture (OSA); see http://appscript.sourceforge.net. Appscript is +a high-level, user-friendly Apple event bridge that allows you to control +scriptable Mac OS X applications using ordinary Python scripts. Appscript makes +Python a serious alternative to Apple's own *AppleScript* language for +automating your Mac. A related package, *PyOSA*, is an OSA language component +for the Python scripting language, allowing Python code to be executed by any +OSA-enabled application (Script Editor, Mail, iTunes, etc.). PyOSA makes Python +a full peer to AppleScript. + + +Other Resources +=============== + +The MacPython mailing list is an excellent support resource for Python users and +developers on the Mac: + +http://www.python.org/community/sigs/current/pythonmac-sig/ + +Another useful resource is the MacPython wiki: + +http://wiki.python.org/moin/MacPython + |