| Commit message (Collapse) | Author | Age | Files | Lines |
|
|
|
| |
plain tuple to a collections.namedtuple.
|
|\
| |
| |
| | |
as the processor type on some Mac systems.
|
| |
| |
| |
| |
| | |
as the processor type on some Mac systems. Also fix NameError in fallback
_mac_ver_gestalt function. And remove out-of-date URL in docs.
|
| | |
|
| | |
|
|\ \
| |/ |
|
| |\ |
|
| | | |
|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | | |
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r86596 | ezio.melotti | 2010-11-20 21:04:17 +0200 (Sat, 20 Nov 2010) | 1 line
#9424: Replace deprecated assert* methods in the Python test suite.
........
|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | | |
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r83075 | ronald.oussoren | 2010-07-23 12:54:59 +0100 (Fri, 23 Jul 2010) | 5 lines
Fix for issue 7895. Avoid crashing the interpreter
when calling platform.mac_ver after calling os.fork by
reading from a system configuration file instead of
using OSX APIs.
........
|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | | |
svn+ssh://pythondev@svn.python.org/python/branches/py3k
................
r77737 | benjamin.peterson | 2010-01-24 21:37:42 -0600 (Sun, 24 Jan 2010) | 9 lines
Merged revisions 77735 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r77735 | benjamin.peterson | 2010-01-24 21:31:13 -0600 (Sun, 24 Jan 2010) | 1 line
fix an UnboundLocalError when the release file is empty #7773
........
................
|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | | |
svn+ssh://pythondev@svn.python.org/python/branches/py3k
................
r74641 | brett.cannon | 2009-09-03 14:29:20 -0700 (Thu, 03 Sep 2009) | 14 lines
Merged revisions 74640 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74640 | brett.cannon | 2009-09-03 14:25:21 -0700 (Thu, 03 Sep 2009) | 7 lines
test_platform fails on OS X Snow Leopard because the UNIX command to get the
canonical version, sw_vers, leaves off trailing zeros in the version number
(e.g. 10.6 instead of 10.6.0). Test now compensates by tacking on extra zeros
for the test comparison.
Fixes issue #6806.
........
................
|
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | | |
svn+ssh://svn.python.org/python/branches/py3k
........
r73715 | benjamin.peterson | 2009-07-01 01:06:06 +0200 (Mi, 01 Jul 2009) | 1 line
convert old fail* assertions to assert*
........
|
| | | |
|
|/ / |
|
| |
| |
| |
| | |
when the user doesn't hold the symbolic link privilege rather than hiding it.
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
In order to create symlinks on Windows, SeCreateSymbolicLinkPrivilege
is an account privilege that is required to be held by the user. Not only
must the privilege be enabled for the account, the activated privileges for
the currently running application must be adjusted to enable the requested
privilege.
Rather than exposing an additional function to be called prior to the user's
first os.symlink call, we handle the AdjustTokenPrivileges Windows API call
internally and only expose os.symlink when the privilege escalation was
successful.
Due to the change of only exposing os.symlink when it's available, we can
go back to the original test skipping methods of checking via `hasattr`.
|
| | |
|
| |
| |
| |
| |
| |
| | |
when calling platform.mac_ver after calling os.fork by
reading from a system configuration file instead of
using OSX APIs.
|
| | |
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
Added Windows support for os.symlink when run on Windows 6.0 or greater,
aka Vista. Previous Windows versions will raise NotImplementedError
when trying to symlink.
Includes numerous test updates and additions to test_os, including
a symlink_support module because of the fact that privilege escalation
is required in order to run the tests to ensure that the user is able
to create symlinks. By default, accounts do not have the required
privilege, so the escalation code will have to be exposed later (or
documented on how to do so). I'll be following up with that work next.
Note that the tests use ctypes, which was agreed on during the PyCon
language summit.
|
| | |
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
svn+ssh://pythondev@svn.python.org/python/trunk
........
r79294 | r.david.murray | 2010-03-22 11:55:09 -0400 (Mon, 22 Mar 2010) | 4 lines
Issue #7860: platform.uname now reports the correct 'machine' type
when Python is running in WOW64 mode on 64 bit Windows. Patch by
Brian Curtin.
........
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
78018,78035-78040,78042-78043,78046,78048-78052,78054,78059,78075-78080 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r78018 | georg.brandl | 2010-02-06 11:08:21 +0100 (Sa, 06 Feb 2010) | 1 line
#7864: make deprecation notices a bit clearer.
........
r78035 | georg.brandl | 2010-02-06 23:44:17 +0100 (Sa, 06 Feb 2010) | 1 line
Fix duplicate import.
........
r78036 | georg.brandl | 2010-02-06 23:49:47 +0100 (Sa, 06 Feb 2010) | 1 line
Remove unused import.
........
r78037 | georg.brandl | 2010-02-06 23:59:15 +0100 (Sa, 06 Feb 2010) | 1 line
No need to assign the results of expressions used only for side effects.
........
r78038 | georg.brandl | 2010-02-07 00:02:29 +0100 (So, 07 Feb 2010) | 1 line
Add a missing import.
........
r78039 | georg.brandl | 2010-02-07 00:06:24 +0100 (So, 07 Feb 2010) | 1 line
Add missing imports.
........
r78040 | georg.brandl | 2010-02-07 00:08:00 +0100 (So, 07 Feb 2010) | 1 line
Fix a few UnboundLocalErrors in test_long.
........
r78042 | georg.brandl | 2010-02-07 00:12:12 +0100 (So, 07 Feb 2010) | 1 line
Add missing import.
........
r78043 | georg.brandl | 2010-02-07 00:12:19 +0100 (So, 07 Feb 2010) | 1 line
Remove duplicate test method.
........
r78046 | georg.brandl | 2010-02-07 00:18:00 +0100 (So, 07 Feb 2010) | 1 line
Fix various missing import/unbound name errors.
........
r78048 | georg.brandl | 2010-02-07 00:23:45 +0100 (So, 07 Feb 2010) | 1 line
We heard you like test failures so we put unbound locals in your test so that you can fail while you fail.
........
r78049 | georg.brandl | 2010-02-07 00:33:33 +0100 (So, 07 Feb 2010) | 1 line
Fix import/access for some identifiers. _TestSharedCTypes does not seem to be executed?
........
r78050 | georg.brandl | 2010-02-07 00:34:10 +0100 (So, 07 Feb 2010) | 1 line
Fix more unbound locals in code paths that do not seem to be used.
........
r78051 | georg.brandl | 2010-02-07 00:53:52 +0100 (So, 07 Feb 2010) | 1 line
Add missing import when running these tests standalone.
........
r78052 | georg.brandl | 2010-02-07 00:54:04 +0100 (So, 07 Feb 2010) | 1 line
Add missing import when running these tests standalone.
........
r78054 | georg.brandl | 2010-02-07 00:58:25 +0100 (So, 07 Feb 2010) | 1 line
Add missing import.
........
r78059 | georg.brandl | 2010-02-07 12:34:15 +0100 (So, 07 Feb 2010) | 1 line
Use "regexp" consistently.
........
r78075 | georg.brandl | 2010-02-07 13:16:12 +0100 (So, 07 Feb 2010) | 1 line
Fix another duplicated test method.
........
r78076 | georg.brandl | 2010-02-07 13:19:43 +0100 (So, 07 Feb 2010) | 1 line
Fix wrong usage of "except X, Y:".
........
r78077 | georg.brandl | 2010-02-07 13:25:50 +0100 (So, 07 Feb 2010) | 1 line
Fix two redefined test methods.
........
r78078 | georg.brandl | 2010-02-07 13:27:06 +0100 (So, 07 Feb 2010) | 1 line
Fix a redefined test method.
........
r78079 | georg.brandl | 2010-02-07 13:34:26 +0100 (So, 07 Feb 2010) | 1 line
Add a minimal test for fnmatchcase().
........
r78080 | georg.brandl | 2010-02-07 13:55:12 +0100 (So, 07 Feb 2010) | 1 line
Remove duplicate test method.
........
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
svn+ssh://pythondev@svn.python.org/python/trunk
........
r77735 | benjamin.peterson | 2010-01-24 21:31:13 -0600 (Sun, 24 Jan 2010) | 1 line
fix an UnboundLocalError when the release file is empty #7773
........
|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74640 | brett.cannon | 2009-09-03 14:25:21 -0700 (Thu, 03 Sep 2009) | 7 lines
test_platform fails on OS X Snow Leopard because the UNIX command to get the
canonical version, sw_vers, leaves off trailing zeros in the version number
(e.g. 10.6 instead of 10.6.0). Test now compensates by tacking on extra zeros
for the test comparison.
Fixes issue #6806.
........
|
|/ |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
70554,70588-70589,70598,70605,70611-70621,70623-70624,70626-70627 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r70554 | benjamin.peterson | 2009-03-23 16:25:15 -0500 (Mon, 23 Mar 2009) | 1 line
complain when there's no last exception
........
r70588 | benjamin.peterson | 2009-03-24 17:56:32 -0500 (Tue, 24 Mar 2009) | 1 line
fix newline issue in test summary
........
r70589 | benjamin.peterson | 2009-03-24 18:07:07 -0500 (Tue, 24 Mar 2009) | 1 line
another style nit
........
r70598 | benjamin.peterson | 2009-03-25 16:24:04 -0500 (Wed, 25 Mar 2009) | 1 line
add shorthands for expected failures and unexpected success
........
r70605 | benjamin.peterson | 2009-03-26 11:32:23 -0500 (Thu, 26 Mar 2009) | 1 line
remove uneeded function
........
r70611 | benjamin.peterson | 2009-03-26 13:35:37 -0500 (Thu, 26 Mar 2009) | 1 line
add much better tests for python version information parsing
........
r70612 | benjamin.peterson | 2009-03-26 13:55:48 -0500 (Thu, 26 Mar 2009) | 1 line
more and more implementations now support sys.subversion
........
r70613 | benjamin.peterson | 2009-03-26 13:58:30 -0500 (Thu, 26 Mar 2009) | 1 line
roll old test in with new one
........
r70614 | benjamin.peterson | 2009-03-26 14:09:21 -0500 (Thu, 26 Mar 2009) | 1 line
add support for PyPy
........
r70615 | benjamin.peterson | 2009-03-26 14:58:18 -0500 (Thu, 26 Mar 2009) | 5 lines
add some useful utilities for skipping tests with unittest's new skipping ability
most significantly apply a modified portion of the patch from #4242 with
patches for skipping implementation details
........
r70616 | benjamin.peterson | 2009-03-26 15:05:50 -0500 (Thu, 26 Mar 2009) | 1 line
rename TestCase.skip() to skipTest() because it causes annoying problems with trial #5571
........
r70617 | benjamin.peterson | 2009-03-26 15:17:27 -0500 (Thu, 26 Mar 2009) | 1 line
apply the second part of #4242's patch; classify all the implementation details in test_descr
........
r70618 | benjamin.peterson | 2009-03-26 15:48:25 -0500 (Thu, 26 Mar 2009) | 1 line
remove test_support.TestSkipped and just use unittest.SkipTest
........
r70619 | benjamin.peterson | 2009-03-26 15:49:40 -0500 (Thu, 26 Mar 2009) | 1 line
fix naming
........
r70620 | benjamin.peterson | 2009-03-26 16:10:30 -0500 (Thu, 26 Mar 2009) | 1 line
fix incorrect auto-translation of TestSkipped -> unittest.SkipTest
........
r70621 | benjamin.peterson | 2009-03-26 16:11:16 -0500 (Thu, 26 Mar 2009) | 1 line
must pass argument to get expected behavior ;)
........
r70623 | benjamin.peterson | 2009-03-26 16:30:10 -0500 (Thu, 26 Mar 2009) | 1 line
add missing import
........
r70624 | benjamin.peterson | 2009-03-26 16:30:54 -0500 (Thu, 26 Mar 2009) | 1 line
** is required here
........
r70626 | benjamin.peterson | 2009-03-26 16:40:29 -0500 (Thu, 26 Mar 2009) | 1 line
update email tests to use SkipTest
........
r70627 | benjamin.peterson | 2009-03-26 16:44:43 -0500 (Thu, 26 Mar 2009) | 1 line
fix another name
........
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
svn+ssh://pythondev@svn.python.org/python/trunk
........
r70518 | matthias.klose | 2009-03-22 08:08:22 -0500 (Sun, 22 Mar 2009) | 2 lines
- Fix comment macro in python.man
........
r70521 | benjamin.peterson | 2009-03-22 12:45:11 -0500 (Sun, 22 Mar 2009) | 1 line
close the file even if an exception occurs #5536
........
r70590 | skip.montanaro | 2009-03-24 19:52:11 -0500 (Tue, 24 Mar 2009) | 1 line
clarify the type of data returned
........
r70594 | marc-andre.lemburg | 2009-03-25 14:44:58 -0500 (Wed, 25 Mar 2009) | 9 lines
Remove the sys.version_info shortcut, since they cause the APIs
to return different information than the _sys_version() output
used in previous Python versions.
This also fixes issue5561: platform.python_version_tuple returns tuple of ints, should be strings
Added more tests for the various platform functions.
........
r70595 | marc-andre.lemburg | 2009-03-25 14:45:33 -0500 (Wed, 25 Mar 2009) | 3 lines
News item for the platform.py fix (r70594).
........
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
66974,66977,66984,66989,66992,66994-66996,66998-67000,67007,67015 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r66974 | benjamin.peterson | 2008-10-19 08:59:01 -0500 (Sun, 19 Oct 2008) | 1 line
fix compiler warning
........
r66977 | benjamin.peterson | 2008-10-19 14:39:16 -0500 (Sun, 19 Oct 2008) | 1 line
mention -n
........
r66984 | armin.ronacher | 2008-10-20 16:29:08 -0500 (Mon, 20 Oct 2008) | 3 lines
Fixed #4062, added import for _ast.__version__ to ast to match the documented behavior.
........
r66989 | matthias.klose | 2008-10-21 04:12:25 -0500 (Tue, 21 Oct 2008) | 2 lines
- install versioned manpage
........
r66992 | benjamin.peterson | 2008-10-21 15:51:13 -0500 (Tue, 21 Oct 2008) | 1 line
make sure to call iteritems()
........
r66994 | amaury.forgeotdarc | 2008-10-21 17:01:38 -0500 (Tue, 21 Oct 2008) | 6 lines
#4157 move two test functions out of platform.py.
Turn them into unit tests, and correct an obvious typo:
(("a", "b") ("c", "d") ("e", "f"))
compiles even with the missing commas, but does not execute very well...
........
r66995 | benjamin.peterson | 2008-10-21 17:18:29 -0500 (Tue, 21 Oct 2008) | 1 line
return ArgInfo from inspect.getargvalues #4092
........
r66996 | benjamin.peterson | 2008-10-21 17:20:31 -0500 (Tue, 21 Oct 2008) | 1 line
add NEWs note for last change
........
r66998 | benjamin.peterson | 2008-10-22 15:57:43 -0500 (Wed, 22 Oct 2008) | 1 line
fix a few typos
........
r66999 | benjamin.peterson | 2008-10-22 16:05:30 -0500 (Wed, 22 Oct 2008) | 1 line
and another typo...
........
r67000 | benjamin.peterson | 2008-10-22 16:16:34 -0500 (Wed, 22 Oct 2008) | 1 line
fix #4150: pdb's up command didn't work for generators in post-mortem
........
r67007 | benjamin.peterson | 2008-10-23 16:43:48 -0500 (Thu, 23 Oct 2008) | 1 line
only nonempty __slots__ don't work
........
r67015 | georg.brandl | 2008-10-25 02:00:52 -0500 (Sat, 25 Oct 2008) | 2 lines
Typo fix.
........
|
| |
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
svn+ssh://pythondev@svn.python.org/python/trunk
........
r63460 | ronald.oussoren | 2008-05-18 15:54:47 -0500 (Sun, 18 May 2008) | 6 lines
- Add unittests for platform.mac_ver (or rather, ensure that the unittest for
that function actually tests something on OSX).
- Add documentation to platform.mac_ver that explains why the middle element
of the return value will not contain useful information.
........
r63464 | benjamin.peterson | 2008-05-18 17:07:42 -0500 (Sun, 18 May 2008) | 2 lines
fix test_platform (os was not imported)
........
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
63208-63209,63211-63212,63214-63217,63219-63224,63226-63227,63229-63232,63234-63235,63237-63239,63241,63243-63246,63250-63254,63256-63259,63261,63263-63264,63266-63267,63269-63270,63272-63273,63275-63276,63278,63280-63281,63283-63284,63286-63287,63289-63290,63292-63293,63295-63296,63298-63299,63301-63302,63304-63305,63307,63309-63314,63316-63322,63324-63325,63327-63335,63337-63338,63340-63342,63344-63346,63348 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r63208 | georg.brandl | 2008-05-13 15:04:54 -0400 (Tue, 13 May 2008) | 2 lines
#2831: add start argument to enumerate(). Patch by Scott Dial and me.
........
r63209 | marc-andre.lemburg | 2008-05-13 15:10:45 -0400 (Tue, 13 May 2008) | 3 lines
Remove leftovers from reverted setuptools checkin (they were added in r45525).
........
r63211 | georg.brandl | 2008-05-13 17:32:03 -0400 (Tue, 13 May 2008) | 2 lines
Fix a refleak in the _warnings module.
........
r63212 | andrew.kuchling | 2008-05-13 20:46:41 -0400 (Tue, 13 May 2008) | 1 line
List all the removes and renamed modules
........
r63214 | brett.cannon | 2008-05-13 21:09:40 -0400 (Tue, 13 May 2008) | 2 lines
Rewrap some lines in test_py3kwarn.
........
r63219 | georg.brandl | 2008-05-14 02:34:15 -0400 (Wed, 14 May 2008) | 2 lines
Add NEWS entry for #2831.
........
r63220 | neal.norwitz | 2008-05-14 02:47:56 -0400 (Wed, 14 May 2008) | 3 lines
Fix "refleak" by restoring the tearDown method removed by accident (AFAICT)
in r62788.
........
r63221 | georg.brandl | 2008-05-14 03:18:22 -0400 (Wed, 14 May 2008) | 2 lines
Fix another "refleak" by clearing the filters after test.
........
r63222 | neal.norwitz | 2008-05-14 03:21:42 -0400 (Wed, 14 May 2008) | 5 lines
Install the json package and tests as well as the lib2to3 tests
so the tests work when run from an install directory.
They are currently skipped on the daily runs (not from the buildbots)
for checking refleaks, etc.
........
r63256 | andrew.kuchling | 2008-05-14 21:10:24 -0400 (Wed, 14 May 2008) | 1 line
Note some removals and a rename
........
r63311 | brett.cannon | 2008-05-15 00:36:53 -0400 (Thu, 15 May 2008) | 2 lines
Add a snippet for the deprecation directive for docs.
........
r63313 | gregory.p.smith | 2008-05-15 00:56:18 -0400 (Thu, 15 May 2008) | 5 lines
disable the crashing test. I will also file a bug. This crash does
not appear to be a new bug, its just that the test coverage went up
recently exposing it. (I verified that by testing this test code on
an older Modules/_bsddb.c)
........
r63320 | georg.brandl | 2008-05-15 11:08:32 -0400 (Thu, 15 May 2008) | 2 lines
#2863: add gen.__name__ and add this name to generator repr().
........
r63324 | andrew.kuchling | 2008-05-15 16:07:39 -0400 (Thu, 15 May 2008) | 1 line
Import class from distutils.cmd, not .core, to avoid circular import
........
r63327 | alexandre.vassalotti | 2008-05-15 16:31:42 -0400 (Thu, 15 May 2008) | 2 lines
Fixed typo in a doctest of test_genexps.
........
r63332 | benjamin.peterson | 2008-05-15 18:34:33 -0400 (Thu, 15 May 2008) | 2 lines
add Mac modules to the list of deprecated ones
........
r63333 | benjamin.peterson | 2008-05-15 18:41:16 -0400 (Thu, 15 May 2008) | 2 lines
fix typos in whatsnew
........
r63348 | benjamin.peterson | 2008-05-15 22:24:49 -0400 (Thu, 15 May 2008) | 2 lines
make test_platform a bit more assertive (We'll see what the buildbots say.)
........
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
number of tests, all because of the codecs/_multibytecodecs issue described
here (it's not a Py3K issue, just something Py3K discovers):
http://mail.python.org/pipermail/python-dev/2006-April/064051.html
Hye-Shik Chang promised to look for a fix, so no need to fix it here. The
tests that are expected to break are:
test_codecencodings_cn
test_codecencodings_hk
test_codecencodings_jp
test_codecencodings_kr
test_codecencodings_tw
test_codecs
test_multibytecodec
This merge fixes an actual test failure (test_weakref) in this branch,
though, so I believe merging is the right thing to do anyway.
|
|
documented function once.
|