From 0f5e51cb185fedaf5aa34862a7d545fdcd7a70e6 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 4 Feb 2000 15:10:34 +0000 Subject: More trivial comment -> docstring transformations by Ka-Ping Yee, who writes: Here is batch 2, as a big collection of CVS context diffs. Along with moving comments into docstrings, i've added a couple of missing docstrings and attempted to make sure more module docstrings begin with a one-line summary. I did not add docstrings to the methods in profile.py for fear of upsetting any careful optimizations there, though i did move class documentation into class docstrings. The convention i'm using is to leave credits/version/copyright type of stuff in # comments, and move the rest of the descriptive stuff about module usage into module docstrings. Hope this is okay. --- Lib/posixfile.py | 120 +++++++++++++++++++++++++++---------------------------- 1 file changed, 58 insertions(+), 62 deletions(-) (limited to 'Lib/posixfile.py') diff --git a/Lib/posixfile.py b/Lib/posixfile.py index ba83b0adfc..2db37e04ee 100644 --- a/Lib/posixfile.py +++ b/Lib/posixfile.py @@ -1,64 +1,61 @@ -# -# Start of posixfile.py -# - -# -# Extended file operations -# -# f = posixfile.open(filename, [mode, [bufsize]]) -# will create a new posixfile object -# -# f = posixfile.fileopen(fileobject) -# will create a posixfile object from a builtin file object -# -# f.file() -# will return the original builtin file object -# -# f.dup() -# will return a new file object based on a new filedescriptor -# -# f.dup2(fd) -# will return a new file object based on the given filedescriptor -# -# f.flags(mode) -# will turn on the associated flag (merge) -# mode can contain the following characters: -# -# (character representing a flag) -# a append only flag -# c close on exec flag -# n no delay flag -# s synchronization flag -# (modifiers) -# ! turn flags 'off' instead of default 'on' -# = copy flags 'as is' instead of default 'merge' -# ? return a string in which the characters represent the flags -# that are set -# -# note: - the '!' and '=' modifiers are mutually exclusive. -# - the '?' modifier will return the status of the flags after they -# have been changed by other characters in the mode string -# -# f.lock(mode [, len [, start [, whence]]]) -# will (un)lock a region -# mode can contain the following characters: -# -# (character representing type of lock) -# u unlock -# r read lock -# w write lock -# (modifiers) -# | wait until the lock can be granted -# ? return the first lock conflicting with the requested lock -# or 'None' if there is no conflict. The lock returned is in the -# format (mode, len, start, whence, pid) where mode is a -# character representing the type of lock ('r' or 'w') -# -# note: - the '?' modifier prevents a region from being locked; it is -# query only -# +"""Extended file operations available in POSIX. + +f = posixfile.open(filename, [mode, [bufsize]]) + will create a new posixfile object + +f = posixfile.fileopen(fileobject) + will create a posixfile object from a builtin file object + +f.file() + will return the original builtin file object + +f.dup() + will return a new file object based on a new filedescriptor + +f.dup2(fd) + will return a new file object based on the given filedescriptor + +f.flags(mode) + will turn on the associated flag (merge) + mode can contain the following characters: + + (character representing a flag) + a append only flag + c close on exec flag + n no delay flag + s synchronization flag + (modifiers) + ! turn flags 'off' instead of default 'on' + = copy flags 'as is' instead of default 'merge' + ? return a string in which the characters represent the flags + that are set + + note: - the '!' and '=' modifiers are mutually exclusive. + - the '?' modifier will return the status of the flags after they + have been changed by other characters in the mode string + +f.lock(mode [, len [, start [, whence]]]) + will (un)lock a region + mode can contain the following characters: + + (character representing type of lock) + u unlock + r read lock + w write lock + (modifiers) + | wait until the lock can be granted + ? return the first lock conflicting with the requested lock + or 'None' if there is no conflict. The lock returned is in the + format (mode, len, start, whence, pid) where mode is a + character representing the type of lock ('r' or 'w') + + note: - the '?' modifier prevents a region from being locked; it is + query only +""" class _posixfile_: + """File wrapper class that provides extra POSIX file routines.""" + states = ['open', 'closed'] # @@ -215,13 +212,12 @@ class _posixfile_: else: return 'w', l_len, l_start, l_whence, l_pid -# -# Public routine to obtain a posixfile object -# def open(name, mode='r', bufsize=-1): + """Public routine to open a file as a posixfile object.""" return _posixfile_().open(name, mode, bufsize) def fileopen(file): + """Public routine to get a posixfile object from a Python file object.""" return _posixfile_().fileopen(file) # -- cgit v1.2.1