Skip to content

Commit d50f188

Browse files
authored
Various updates to README.rst (#21)
These include spelling/grammar fixes, removing some outdated prose, updating some superseded prose, and adding/cleaning up some links. Also rewraps the entire file at 79 columns.
1 parent b692dc8 commit d50f188

File tree

1 file changed

+77
-83
lines changed

1 file changed

+77
-83
lines changed

README.rst

Lines changed: 77 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,8 @@ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
1313
2012, 2013, 2014, 2015, 2016, 2017 Python Software Foundation. All rights
1414
reserved.
1515

16-
Python 3.x is a new version of the language, which is incompatible with the
17-
2.x line of releases. The language is mostly the same, but many details,
18-
especially how built-in objects like dictionaries and strings work,
19-
have changed considerably, and a lot of deprecated features have finally
20-
been removed.
16+
See the end of this file for further copyright and license information.
17+
2118

2219
Using Python
2320
------------
@@ -40,16 +37,17 @@ On Unix, Linux, BSD, OSX, and Cygwin::
4037

4138
This will install Python as python3.
4239

43-
You can pass many options to the configure script; run ``./configure --help`` to
44-
find out more. On OSX and Cygwin, the executable is called ``python.exe``;
40+
You can pass many options to the configure script; run ``./configure --help``
41+
to find out more. On OSX and Cygwin, the executable is called ``python.exe``;
4542
elsewhere it's just ``python``.
4643

47-
On Mac OS X, if you have configured Python with ``--enable-framework``, you should
48-
use ``make frameworkinstall`` to do the installation. Note that this installs the
49-
Python executable in a place that is not normally on your PATH, you may want to
50-
set up a symlink in ``/usr/local/bin``.
44+
On Mac OS X, if you have configured Python with ``--enable-framework``, you
45+
should use ``make frameworkinstall`` to do the installation. Note that this
46+
installs the Python executable in a place that is not normally on your PATH,
47+
you may want to set up a symlink in ``/usr/local/bin``.
5148

52-
On Windows, see PCbuild/readme.txt.
49+
On Windows, see `PCbuild/readme.txt
50+
<https://github.com/python/cpython/blob/master/PCbuild/readme.txt>`_.
5351

5452
If you wish, you can create a subdirectory and invoke configure from there.
5553
For example::
@@ -60,57 +58,58 @@ For example::
6058
make
6159
make test
6260

63-
(This will fail if you *also* built at the top-level directory.
64-
You should do a ``make clean`` at the toplevel first.)
61+
(This will fail if you *also* built at the top-level directory. You should do
62+
a ``make clean`` at the toplevel first.)
6563

66-
To get an optimized build of Python, ``configure --enable-optimizations`` before
67-
you run ``make``. This sets the default make targets up to enable Profile Guided
68-
Optimization (PGO) and may be used to auto-enable Link Time Optimization (LTO)
69-
on some platforms. For more details, see the sections bellow.
64+
To get an optimized build of Python, ``configure --enable-optimizations``
65+
before you run ``make``. This sets the default make targets up to enable
66+
Profile Guided Optimization (PGO) and may be used to auto-enable Link Time
67+
Optimization (LTO) on some platforms. For more details, see the sections
68+
below.
7069

7170

7271
Profile Guided Optimization
7372
---------------------------
7473

75-
PGO takes advantage of recent versions of the GCC or Clang compilers.
76-
If ran, ``make profile-opt`` will do several steps.
74+
PGO takes advantage of recent versions of the GCC or Clang compilers. If ran,
75+
``make profile-opt`` will do several steps.
7776

78-
First, the entire Python directory is cleaned of temporary files that
79-
may have resulted in a previous compilation.
77+
First, the entire Python directory is cleaned of temporary files that may have
78+
resulted in a previous compilation.
8079

8180
Then, an instrumented version of the interpreter is built, using suitable
82-
compiler flags for each flavour. Note that this is just an intermediary
83-
step and the binary resulted after this step is not good for real life
84-
workloads, as it has profiling instructions embedded inside.
81+
compiler flags for each flavour. Note that this is just an intermediary step
82+
and the binary resulted after this step is not good for real life workloads, as
83+
it has profiling instructions embedded inside.
8584

86-
After this instrumented version of the interpreter is built, the Makefile
87-
will automatically run a training workload. This is necessary in order to
88-
profile the interpreter execution. Note also that any output, both stdout
89-
and stderr, that may appear at this step is suppressed.
85+
After this instrumented version of the interpreter is built, the Makefile will
86+
automatically run a training workload. This is necessary in order to profile
87+
the interpreter execution. Note also that any output, both stdout and stderr,
88+
that may appear at this step is suppressed.
9089

9190
Finally, the last step is to rebuild the interpreter, using the information
92-
collected in the previous one. The end result will be a Python binary
93-
that is optimized and suitable for distribution or production installation.
91+
collected in the previous one. The end result will be a Python binary that is
92+
optimized and suitable for distribution or production installation.
9493

9594

9695
Link Time Optimization
9796
----------------------
9897

99-
Enabled via configure's ``--with-lto`` flag. LTO takes advantages of recent
100-
compiler toolchains ability to optimize across the otherwise arbitrary ``.o`` file
101-
boundary when building final executables or shared libraries for additional
102-
performance gains.
98+
Enabled via configure's ``--with-lto`` flag. LTO takes advantage of the
99+
ability of recent compiler toolchains to optimize across the otherwise
100+
arbitrary ``.o`` file boundary when building final executables or shared
101+
libraries for additional performance gains.
103102

104103

105104
What's New
106105
----------
107106

108-
We have a comprehensive overview of the changes in the `What's New in
109-
Python 3.7 <https://docs.python.org/3.7/whatsnew/3.7.html>`_ document.
110-
111-
For a more detailed change log, read Misc/NEWS (though this file, too,
112-
is incomplete, and also doesn't list anything merged in from the 2.7
113-
release under development).
107+
We have a comprehensive overview of the changes in the `What's New in Python
108+
3.7 <https://docs.python.org/3.7/whatsnew/3.7.html>`_ document. For a more
109+
detailed change log, read `Misc/NEWS
110+
<https://github.com/python/cpython/blob/master/Misc/NEWS>`_, but a full
111+
accounting of changes can only be gleaned from the `commit history
112+
<https://github.com/python/cpython/commits/master>`_.
114113

115114
If you want to install multiple versions of Python see the section below
116115
entitled "Installing multiple versions".
@@ -128,61 +127,56 @@ is primarily for documentation authors, translators, and people with special
128127
formatting requirements.
129128

130129
If you would like to contribute to the development of Python, relevant
131-
documentation is available at: `Python Developer's Guide
130+
documentation is available in the `Python Developer's Guide
132131
<https://docs.python.org/devguide/>`_.
133132

134-
For information about building Python's documentation, refer to Doc/README.txt.
133+
For information about building Python's documentation, refer to `Doc/README.txt
134+
<https://github.com/python/cpython/blob/master/Doc/README.txt>`_.
135135

136136

137137
Converting From Python 2.x to 3.x
138138
---------------------------------
139139

140-
Python starting with 2.6 contains features to help locating code that needs to
141-
be changed, such as optional warnings when deprecated features are used, and
142-
backported versions of certain key Python 3.x features.
143-
144-
A source-to-source translation tool, ``2to3``, can take care of the mundane task
145-
of converting large amounts of source code. It is not a complete solution but
146-
is complemented by the deprecation warnings in 2.6. See
147-
`2to3 documentation <https://docs.python.org/3.7/library/2to3.html>`_ for more
148-
information.
140+
Significant backward incompatible changes were made for the release of Python
141+
3.0, which may cause programs written for Python 2 to fail when run with Python
142+
3. For more information about porting your code from Python 2 to Python 3, see
143+
the `Porting HOWTO <https://docs.python.org/3/howto/pyporting.html>`_.
149144

150145

151146
Testing
152147
-------
153148

154-
To test the interpreter, type ``make test`` in the top-level directory.
155-
The test set produces some output. You can generally ignore the messages
156-
about skipped tests due to optional features which can't be imported.
157-
If a message is printed about a failed test or a traceback or core dump
158-
is produced, something is wrong.
149+
To test the interpreter, type ``make test`` in the top-level directory. The
150+
test set produces some output. You can generally ignore the messages about
151+
skipped tests due to optional features which can't be imported. If a message
152+
is printed about a failed test or a traceback or core dump is produced,
153+
something is wrong.
159154

160155
By default, tests are prevented from overusing resources like disk space and
161156
memory. To enable these tests, run ``make testall``.
162157

163-
IMPORTANT: If the tests fail and you decide to mail a bug report, *don't*
164-
include the output of ``make test``. It is useless. Run the failing test
165-
manually, as follows::
158+
If any tests fail, you can re-run the failing test(s) in verbose mode::
166159

167-
./python -m test -v test_whatever
160+
make test TESTOPTS="-v test_that_failed"
168161

169-
(substituting the top of the source tree for '.' if you built in a different
170-
directory). This runs the test in verbose mode.
162+
If the failure persists and appears to be a problem with Python rather than
163+
your environment, you can `file a bug report <https://bugs.python.org>`_ and
164+
include relevant output from that command to show the issue.
171165

172166

173167
Installing multiple versions
174168
----------------------------
175169

176170
On Unix and Mac systems if you intend to install multiple versions of Python
177-
using the same installation prefix (``--prefix`` argument to the configure script)
178-
you must take care that your primary python executable is not overwritten by the
179-
installation of a different version. All files and directories installed using
180-
``make altinstall`` contain the major and minor version and can thus live
181-
side-by-side. ``make install`` also creates ``${prefix}/bin/python3`` which refers to
182-
``${prefix}/bin/pythonX.Y``. If you intend to install multiple versions using the
183-
same prefix you must decide which version (if any) is your "primary" version.
184-
Install that version using ``make install``. Install all other versions using
185-
``make altinstall``.
171+
using the same installation prefix (``--prefix`` argument to the configure
172+
script) you must take care that your primary python executable is not
173+
overwritten by the installation of a different version. All files and
174+
directories installed using ``make altinstall`` contain the major and minor
175+
version and can thus live side-by-side. ``make install`` also creates
176+
``${prefix}/bin/python3`` which refers to ``${prefix}/bin/pythonX.Y``. If you
177+
intend to install multiple versions using the same prefix you must decide which
178+
version (if any) is your "primary" version. Install that version using ``make
179+
install``. Install all other versions using ``make altinstall``.
186180

187181
For example, if you want to install Python 2.7, 3.6, and 3.7 with 3.7 being the
188182
primary version, you would execute ``make install`` in your 3.7 build directory
@@ -192,26 +186,26 @@ and ``make altinstall`` in the others.
192186
Issue Tracker and Mailing List
193187
------------------------------
194188

195-
We're soliciting bug reports about all aspects of the language. Fixes are also
196-
welcome, preferably in unified diff format. Please use the issue tracker:
197-
`bugs.python.org <https://bugs.python.org/>`_.
189+
Bug reports are welcome! You can use the `issue tracker
190+
<https://bugs.python.org>`_ to report bugs, and/or submit pull requests `on
191+
GitHub <https://github.com/python/cpython>`_.
198192

199-
If you're not sure whether you're dealing with a bug or a feature, use the
200-
mailing list: [email protected]. To subscribe to the list, use the mailman
201-
form: `python-dev <https://mail.python.org/mailman/listinfo/python-dev/>`_
193+
You can also follow development discussion on the `python-dev mailing list
194+
<https://mail.python.org/mailman/listinfo/python-dev/>`_.
202195

203196

204197
Proposals for enhancement
205198
-------------------------
206199

207200
If you have a proposal to change Python, you may want to send an email to the
208-
comp.lang.python or `python-ideas`_ mailing lists for initial feedback. A Python
209-
Enhancement Proposal (PEP) may be submitted if your idea gains ground. All
210-
current PEPs, as well as guidelines for submitting a new PEP, are listed at
201+
comp.lang.python or `python-ideas`_ mailing lists for initial feedback. A
202+
Python Enhancement Proposal (PEP) may be submitted if your idea gains ground.
203+
All current PEPs, as well as guidelines for submitting a new PEP, are listed at
211204
`python.org/dev/peps/ <https://www.python.org/dev/peps/>`_.
212205

213206
.. _python-ideas: https://mail.python.org/mailman/listinfo/python-ideas/
214207

208+
215209
Release Schedule
216210
----------------
217211

@@ -231,8 +225,8 @@ rights reserved.
231225

232226
Copyright (c) 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
233227

234-
See the file "LICENSE" for information on the history of this software,
235-
terms & conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
228+
See the file "LICENSE" for information on the history of this software, terms &
229+
conditions for usage, and a DISCLAIMER OF ALL WARRANTIES.
236230

237231
This Python distribution contains *no* GNU General Public License (GPL) code,
238232
so it may be used in proprietary projects. There are interfaces to some GNU

0 commit comments

Comments
 (0)