summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/data/refcounts.dat2
-rw-r--r--Doc/distutils/examples.rst5
-rw-r--r--Doc/library/datetime.rst82
-rw-r--r--Doc/library/ftplib.rst46
-rw-r--r--Doc/library/profile.rst2
-rw-r--r--Doc/library/unittest.rst6
-rw-r--r--Doc/library/xmlrpc.client.rst4
-rw-r--r--Doc/reference/datamodel.rst21
-rw-r--r--Doc/whatsnew/2.7.rst4
9 files changed, 86 insertions, 86 deletions
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 06e0705..721ea8c 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -1637,7 +1637,7 @@ PyUnicode_Join:PyObject*::+1:
PyUnicode_Join:PyObject*:separator:0:
PyUnicode_Join:PyObject*:seq:0:
-PyUnicode_Tailmatch:PyObject*::+1:
+PyUnicode_Tailmatch:int:::
PyUnicode_Tailmatch:PyObject*:str:0:
PyUnicode_Tailmatch:PyObject*:substr:0:
PyUnicode_Tailmatch:int:start::
diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst
index 35de57e..60656e7 100644
--- a/Doc/distutils/examples.rst
+++ b/Doc/distutils/examples.rst
@@ -285,8 +285,11 @@ by using the `docutils` parser::
warning: check: Title underline too short. (line 2)
warning: check: Could not finish the parsing.
+
+.. _reading-metadata:
+
Reading the metadata
-=====================
+====================
The :func:`distutils.core.setup` function provides a command-line interface
that allows you to query the metadata fields of a project through the
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 5126821..edcd1f1 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -36,7 +36,6 @@ than rational, and there is no standard suitable for every application.
The :mod:`datetime` module exports the following constants:
-
.. data:: MINYEAR
The smallest year number allowed in a :class:`date` or :class:`datetime` object.
@@ -61,7 +60,6 @@ The :mod:`datetime` module exports the following constants:
Available Types
---------------
-
.. class:: date
:noindex:
@@ -131,7 +129,6 @@ Subclass relationships::
A :class:`timedelta` object represents a duration, the difference between two
dates or times.
-
.. class:: timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
All arguments are optional and default to ``0``. Arguments may be integers
@@ -168,8 +165,8 @@ dates or times.
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
-Class attributes are:
+Class attributes are:
.. attribute:: timedelta.min
@@ -326,16 +323,16 @@ systems.
If an argument outside those ranges is given, :exc:`ValueError` is raised.
-Other constructors, all class methods:
+Other constructors, all class methods:
-.. method:: date.today()
+.. classmethod:: date.today()
Return the current local date. This is equivalent to
``date.fromtimestamp(time.time())``.
-.. method:: date.fromtimestamp(timestamp)
+.. classmethod:: date.fromtimestamp(timestamp)
Return the local date corresponding to the POSIX timestamp, such as is returned
by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out
@@ -345,15 +342,15 @@ Other constructors, all class methods:
timestamp, leap seconds are ignored by :meth:`fromtimestamp`.
-.. method:: date.fromordinal(ordinal)
+.. classmethod:: date.fromordinal(ordinal)
Return the date corresponding to the proleptic Gregorian ordinal, where January
1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <=
date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==
d``.
-Class attributes:
+Class attributes:
.. attribute:: date.min
@@ -370,8 +367,8 @@ Class attributes:
The smallest possible difference between non-equal date objects,
``timedelta(days=1)``.
-Instance attributes (read-only):
+Instance attributes (read-only):
.. attribute:: date.year
@@ -387,6 +384,7 @@ Instance attributes (read-only):
Between 1 and the number of days in the given month of the given year.
+
Supported operations:
+-------------------------------+----------------------------------------------+
@@ -439,7 +437,6 @@ objects are considered to be true.
Instance methods:
-
.. method:: date.replace(year, month, day)
Return a date with the same value, except for those members given new values by
@@ -519,7 +516,8 @@ Instance methods:
Return a string representing the date, controlled by an explicit format string.
Format codes referring to hours, minutes or seconds will see 0 values. See
- section :ref:`strftime-behavior`.
+ section :ref:`strftime-strptime-behavior`.
+
Example of counting days to an event::
@@ -586,7 +584,6 @@ both directions; like a time object, :class:`datetime` assumes there are exactly
Constructor:
-
.. class:: datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
The year, month and day arguments are required. *tzinfo* may be ``None``, or an
@@ -605,15 +602,14 @@ Constructor:
Other constructors, all class methods:
-
-.. method:: datetime.today()
+.. classmethod:: datetime.today()
Return the current local datetime, with :attr:`tzinfo` ``None``. This is
equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
:meth:`fromtimestamp`.
-.. method:: datetime.now(tz=None)
+.. classmethod:: datetime.now(tz=None)
Return the current local date and time. If optional argument *tz* is ``None``
or not specified, this is like :meth:`today`, but, if possible, supplies more
@@ -627,14 +623,14 @@ Other constructors, all class methods:
See also :meth:`today`, :meth:`utcnow`.
-.. method:: datetime.utcnow()
+.. classmethod:: datetime.utcnow()
Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like
:meth:`now`, but returns the current UTC date and time, as a naive
:class:`datetime` object. See also :meth:`now`.
-.. method:: datetime.fromtimestamp(timestamp, tz=None)
+.. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
Return the local date and time corresponding to the POSIX timestamp, such as is
returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
@@ -655,7 +651,7 @@ Other constructors, all class methods:
identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`.
-.. method:: datetime.utcfromtimestamp(timestamp)
+.. classmethod:: datetime.utcfromtimestamp(timestamp)
Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with
:attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
@@ -664,7 +660,7 @@ Other constructors, all class methods:
:meth:`fromtimestamp`.
-.. method:: datetime.fromordinal(ordinal)
+.. classmethod:: datetime.fromordinal(ordinal)
Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
@@ -672,7 +668,7 @@ Other constructors, all class methods:
microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
-.. method:: datetime.combine(date, time)
+.. classmethod:: datetime.combine(date, time)
Return a new :class:`datetime` object whose date members are equal to the given
:class:`date` object's, and whose time and :attr:`tzinfo` members are equal to
@@ -681,17 +677,17 @@ Other constructors, all class methods:
object, its time and :attr:`tzinfo` members are ignored.
-.. method:: datetime.strptime(date_string, format)
+.. classmethod:: datetime.strptime(date_string, format)
Return a :class:`datetime` corresponding to *date_string*, parsed according to
*format*. This is equivalent to ``datetime(*(time.strptime(date_string,
format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
- time tuple.
+ time tuple. See section :ref:`strftime-strptime-behavior`.
-Class attributes:
+Class attributes:
.. attribute:: datetime.min
@@ -710,8 +706,8 @@ Class attributes:
The smallest possible difference between non-equal :class:`datetime` objects,
``timedelta(microseconds=1)``.
-Instance attributes (read-only):
+Instance attributes (read-only):
.. attribute:: datetime.year
@@ -753,6 +749,7 @@ Instance attributes (read-only):
The object passed as the *tzinfo* argument to the :class:`datetime` constructor,
or ``None`` if none was passed.
+
Supported operations:
+---------------------------------------+-------------------------------+
@@ -826,7 +823,6 @@ all :class:`datetime` objects are considered to be true.
Instance methods:
-
.. method:: datetime.date()
Return :class:`date` object with same year, month and day.
@@ -1004,7 +1000,8 @@ Instance methods:
.. method:: datetime.strftime(format)
Return a string representing the date and time, controlled by an explicit format
- string. See section :ref:`strftime-behavior`.
+ string. See section :ref:`strftime-strptime-behavior`.
+
Examples of working with datetime objects:
@@ -1117,7 +1114,6 @@ Using datetime with tzinfo:
A time object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a :class:`tzinfo` object.
-
.. class:: time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None)
All arguments are optional. *tzinfo* may be ``None``, or an instance of a
@@ -1151,8 +1147,8 @@ Class attributes:
``timedelta(microseconds=1)``, although note that arithmetic on :class:`time`
objects is not supported.
-Instance attributes (read-only):
+Instance attributes (read-only):
.. attribute:: time.hour
@@ -1179,6 +1175,7 @@ Instance attributes (read-only):
The object passed as the tzinfo argument to the :class:`time` constructor, or
``None`` if none was passed.
+
Supported operations:
* comparison of :class:`time` to :class:`time`, where *a* is considered less
@@ -1201,8 +1198,8 @@ Supported operations:
only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
``0`` if that's ``None``), the result is non-zero.
-Instance methods:
+Instance methods:
.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
@@ -1228,7 +1225,7 @@ Instance methods:
.. method:: time.strftime(format)
Return a string representing the time, controlled by an explicit format string.
- See section :ref:`strftime-behavior`.
+ See section :ref:`strftime-strptime-behavior`.
.. method:: time.utcoffset()
@@ -1253,6 +1250,7 @@ Instance methods:
``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
return ``None`` or a string object.
+
Example:
>>> from datetime import time, tzinfo
@@ -1389,6 +1387,7 @@ methods. Exactly which methods are needed depends on the uses made of aware
The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
+
These methods are called by a :class:`datetime` or :class:`time` object, in
response to their methods of the same names. A :class:`datetime` object passes
itself as the argument, and a :class:`time` object passes ``None`` as the
@@ -1492,10 +1491,10 @@ other fixed-offset :class:`tzinfo` subclass (such as a class representing only
EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
-.. _strftime-behavior:
+.. _strftime-strptime-behavior:
-:meth:`strftime` Behavior
--------------------------
+:meth:`strftime` and :meth:`strptime` Behavior
+----------------------------------------------
:class:`date`, :class:`datetime`, and :class:`time` objects all support a
``strftime(format)`` method, to create a string representing the time under the
@@ -1503,9 +1502,14 @@ control of an explicit format string. Broadly speaking, ``d.strftime(fmt)``
acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
although not all objects support a :meth:`timetuple` method.
+Conversely, the :meth:`datetime.strptime` class method creates a
+:class:`datetime` object from a string representing a date and time and a
+corresponding format string. ``datetime.strptime(date_string, format)`` is
+equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``.
+
For :class:`time` objects, the format codes for year, month, and day should not
be used, as time objects have no such values. If they're used anyway, ``1900``
-is substituted for the year, and ``0`` for the month and day.
+is substituted for the year, and ``1`` for the month and day.
For :class:`date` objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as :class:`date` objects have no such
@@ -1627,14 +1631,14 @@ platforms. Regardless of platform, years before 1900 cannot be used.
Notes:
(1)
- When used with the :func:`strptime` function, the ``%f`` directive
+ When used with the :meth:`strptime` method, the ``%f`` directive
accepts from one to six digits and zero pads on the right. ``%f`` is
an extension to the set of format characters in the C standard (but
implemented separately in datetime objects, and therefore always
available).
(2)
- When used with the :func:`strptime` function, the ``%p`` directive only affects
+ When used with the :meth:`strptime` method, the ``%p`` directive only affects
the output hour field if the ``%I`` directive is used to parse the hour.
(3)
@@ -1642,11 +1646,11 @@ Notes:
accounts for leap seconds and the (very rare) double leap seconds.
The :mod:`time` module may produce and does accept leap seconds since
it is based on the Posix standard, but the :mod:`datetime` module
- does not accept leap seconds in :func:`strptime` input nor will it
+ does not accept leap seconds in :meth:`strptime` input nor will it
produce them in :func:`strftime` output.
(4)
- When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
+ When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in
calculations when the day of the week and the year are specified.
(5)
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 59d5b3c..02edef7 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -33,8 +33,8 @@ Here's a sample session using the :mod:`ftplib` module::
'226 Transfer complete.'
>>> ftp.quit()
-The module defines the following items:
+The module defines the following items:
.. class:: FTP(host='', user='', passwd='', acct=''[, timeout])
@@ -51,21 +51,20 @@ The module defines the following items:
A :class:`FTP` subclass which adds TLS support to FTP as described in
:rfc:`4217`.
Connect as usual to port 21 implicitly securing the FTP control connection
- before authenticating. Securing the data connection requires user to
- explicitly ask for it by calling :exc:`prot_p()` method.
- *keyfile* and *certfile* are optional - they can contain a PEM formatted
- private key and certificate chain file for the SSL connection.
-
- .. versionadded:: 3.2 Contributed by Giampaolo Rodola'
+ before authenticating. Securing the data connection requires the user to
+ explicitly ask for it by calling the :meth:`prot_p` method.
+ *keyfile* and *certfile* are optional -- they can contain a PEM formatted
+ private key and certificate chain file name for the SSL connection.
+ .. versionadded:: 3.2
- Here's a sample session using :class:`FTP_TLS` class:
+ Here's a sample session using the :class:`FTP_TLS` class:
>>> from ftplib import FTP_TLS
>>> ftps = FTP_TLS('ftp.python.org')
- >>> ftps.login() # login anonimously previously securing control channel
- >>> ftps.prot_p() # switch to secure data connection
- >>> ftps.retrlines('LIST') # list directory content securely
+ >>> ftps.login() # login anonymously before securing control channel
+ >>> ftps.prot_p() # switch to secure data connection
+ >>> ftps.retrlines('LIST') # list directory content securely
total 9
drwxr-xr-x 8 root wheel 1024 Jan 3 1994 .
drwxr-xr-x 8 root wheel 1024 Jan 3 1994 ..
@@ -81,16 +80,6 @@ The module defines the following items:
>>>
-
- .. attribute:: all_errors
-
- The set of all exceptions (as a tuple) that methods of :class:`FTP`
- instances may raise as a result of problems with the FTP connection (as
- opposed to programming errors made by the caller). This set includes the
- four exceptions listed below as well as :exc:`socket.error` and
- :exc:`IOError`.
-
-
.. exception:: error_reply
Exception raised when an unexpected reply is received from the server.
@@ -98,19 +87,24 @@ The module defines the following items:
.. exception:: error_temp
- Exception raised when an error code in the range 400--499 is received.
-
+ Exception raised when an unexpected reply is received from the server.
.. exception:: error_perm
Exception raised when an error code in the range 500--599 is received.
-
.. exception:: error_proto
- Exception raised when a reply is received from the server that does not begin
- with a digit in the range 1--5.
+ Exception raised when a reply is received from the server that does not
+ begin with a digit in the range 1--5.
+
+.. data:: all_errors
+ The set of all exceptions (as a tuple) that methods of :class:`FTP`
+ instances may raise as a result of problems with the FTP connection (as
+ opposed to programming errors made by the caller). This set includes the
+ four exceptions listed below as well as :exc:`socket.error` and
+ :exc:`IOError`.
.. seealso::
diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index f7df0b5..c3632f9 100644
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -107,7 +107,7 @@ script. For example::
cProfile.py [-o output_file] [-s sort_order]
-:option:`-s` only applies to standard output (:option:`-o` is not supplied).
+``-s`` only applies to standard output (``-o`` is not supplied).
Look in the :class:`Stats` documentation for valid sort values.
When you wish to review the profile, you should use the methods in the
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index adfd539..bd88310 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -803,9 +803,9 @@ Test cases
.. method:: assertSameElements(expected, actual, msg=None)
- Test that sequence *expected* contains the same elements as *actual*.
- When they don't an error message listing the differences between the
- sequences will be generated.
+ Test that sequence *expected* contains the same elements as *actual*,
+ regardless of their order. When they don't, an error message listing
+ the differences between the sequences will be generated.
If specified *msg* will be used as the error message on failure.
diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst
index 1bcc423..d25cbaf 100644
--- a/Doc/library/xmlrpc.client.rst
+++ b/Doc/library/xmlrpc.client.rst
@@ -383,8 +383,8 @@ by providing an invalid URI::
import xmlrpc.client
- # create a ServerProxy with an invalid URI
- proxy = xmlrpc.client.ServerProxy("http://invalidaddress/")
+ # create a ServerProxy with an URI that doesn't respond to XMLRPC requests
+ proxy = xmlrpc.client.ServerProxy("http://google.com/")
try:
proxy.some_method()
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 78f96df..d2f8c16 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1413,11 +1413,17 @@ Super Binding
``A.__dict__['m'].__get__(obj, A)``.
For instance bindings, the precedence of descriptor invocation depends on the
-which descriptor methods are defined. Normally, data descriptors define both
-:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the
-:meth:`__get__` method. Data descriptors always override a redefinition in an
+which descriptor methods are defined. A descriptor can define any combination
+of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not
+define :meth:`__get__`, then accessing the attribute will return the descriptor
+object itself unless there is a value in the object's instance dictionary. If
+the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data
+descriptor; if it defines neither, it is a non-data descriptor. Normally, data
+descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data
+descriptors have just the :meth:`__get__` method. Data descriptors with
+:meth:`__set__` and :meth:`__get__` defined always override a redefinition in an
instance dictionary. In contrast, non-data descriptors can be overridden by
-instances. [#]_
+instances.
Python methods (including :func:`staticmethod` and :func:`classmethod`) are
implemented as non-data descriptors. Accordingly, instances can redefine and
@@ -2006,13 +2012,6 @@ object itself in order to be consistently invoked by the interpreter).
controlled conditions. It generally isn't a good idea though, since it can
lead to some very strange behaviour if it is handled incorrectly.
-.. [#] A descriptor can define any combination of :meth:`__get__`,
- :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`,
- then accessing the attribute even on an instance will return the descriptor
- object itself. If the descriptor defines :meth:`__set__` and/or
- :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a
- non-data descriptor.
-
.. [#] For operands of the same type, it is assumed that if the non-reflected method
(such as :meth:`__add__`) fails the operation is not supported, which is why the
reflected method is not called.
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index 68315bd..279c49a 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -612,8 +612,8 @@ changes, or look through the Subversion logs for all the details.
The :class:`distutils.dist.DistributionMetadata` class'
:meth:`read_pkg_file` method will read the contents of a package's
- :file:`PKG-INFO` metadata file. For an example of its use,
- XXX link to file:///MacDev/svn.python.org/python-trunk/Doc/build/html/distutils/examples.html#reading-the-metadata
+ :file:`PKG-INFO` metadata file. For an example of its use, see
+ :ref:`reading-metadata`.
(Contributed by Tarek Ziade; :issue:`7457`.)
:file:`setup.py` files will now accept a :option:`--no-user-cfg` switch
generated by cgit v0.12 at 2024-11-29 16:53:56 (GMT)