[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,1.5,1.6

anthonybaxter@users.sourceforge.net anthonybaxter@users.sourceforge.net
Mon, 19 May 2003 19:54:22 -0700


Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv15099

Modified Files:
	distref.tex 
Log Message:
dep_util and file_util done.


Index: distref.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/distutilsref/distref.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** distref.tex	19 May 2003 03:12:27 -0000	1.5
--- distref.tex	20 May 2003 02:54:20 -0000	1.6
***************
*** 224,232 ****
  \modulesynopsis{Abstract CCompiler class}
  
! This module provides the abstract base class for the CCompiler classes.
! A CCompiler instance can be used for all the compile and link steps needed
! to build a single project. Methods are provided to set options for the
! compiler -- macro definitions, include directories, link path, libraries 
! and the like.
  
  This module provides the following functions.
--- 224,232 ----
  \modulesynopsis{Abstract CCompiler class}
  
! This module provides the abstract base class for the \class{CCompiler} 
! classes.  A \class{CCompiler} instance can be used for all the compile 
! and link steps needed to build a single project. Methods are provided to 
! set options for the compiler -- macro definitions, include directories, 
! link path, libraries and the like.
  
  This module provides the following functions.
***************
*** 258,262 ****
  returned by \var{sys.platform} for the platform in question.
      
! The default values are \var{os.name} and \var{sys.platform} in case the
  parameters are not given.
  \end{funcdesc}
--- 258,262 ----
  returned by \var{sys.platform} for the platform in question.
      
! The default values are \code{os.name} and \code{sys.platform} in case the
  parameters are not given.
  \end{funcdesc}
***************
*** 265,275 ****
  Factory function to generate an instance of some CCompiler subclass
  for the supplied platform/compiler combination. \var{plat} defaults
! to \var{os.name} (eg. \var{posix}, \var{nt}), and \var{compiler} 
! defaults to the default compiler for that platform. Currently only \var{posix} 
! and \var{nt} are supported, and the default compilers are "traditional
  \UNIX interface" (\class{UnixCCompiler} class) and Visual C++ 
  (\class{MSVCCompiler} class). Note that it's perfectly possible to ask 
  for a \UNIX compiler object under Windows, and a Microsoft compiler object 
  under \UNIX -- if you supply a value for \var{compiler}, \var{plat} is ignored.
  \end{funcdesc}
  
--- 265,277 ----
  Factory function to generate an instance of some CCompiler subclass
  for the supplied platform/compiler combination. \var{plat} defaults
! to \code{os.name} (eg. \code{posix}, \code{nt}), and \var{compiler} 
! defaults to the default compiler for that platform. Currently only \code{posix} 
! and \code{nt} are supported, and the default compilers are "traditional
  \UNIX interface" (\class{UnixCCompiler} class) and Visual C++ 
  (\class{MSVCCompiler} class). Note that it's perfectly possible to ask 
  for a \UNIX compiler object under Windows, and a Microsoft compiler object 
  under \UNIX -- if you supply a value for \var{compiler}, \var{plat} is ignored.
+ % Is the posix/nt only thing still true? MacOS X seems to work, and returns
+ % a UnixCCompiler instance. How to document this... hmm.
  \end{funcdesc}
  
***************
*** 797,800 ****
--- 799,832 ----
  on such timestamp dependency analysis.
  
+ \begin{funcdesc}{newer}{source, target}
+ Return true if \var{source} exists and is more recently modified than
+ \var{target}, or if \var{source} exists and \var{target} doesn't.
+ Return false if both exist and \var{target} is the same age or newer 
+ than \var{source}.
+ Raise \exception{DistutilsFileError} if \var{source} does not exist.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{newer_pairwise}{sources, targets}
+ Walk two filename lists in parallel, testing if each source is newer
+ than its corresponding target.  Return a pair of lists (\var{sources},
+ \var{targets}) where source is newer than target, according to the semantics
+ of \function{newer()}
+ %% equivalent to a listcomp...
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{newer_group}{sources, target\optional{, missing=\code{'error'}}}
+ Return true if \var{target} is out-of-date with respect to any file
+ listed in \var{sources}  In other words, if \var{target} exists and is newer
+ than every file in \var{sources}, return false; otherwise return true.
+ \var{missing} controls what we do when a source file is missing; the
+ default (\code{"error"}) is to blow up with an \exception{OSError} from 
+ inside \function{os.stat()};
+ if it is \code{"ignore"}, we silently drop any missing source files; if it is
+ \code{"newer"}, any missing source files make us assume that \var{target} is
+ out-of-date (this is handy in "dry-run" mode: it'll make you pretend to
+ carry out commands that wouldn't work because inputs are missing, but
+ that doesn't matter because you're not actually going to run the
+ commands).
+ \end{funcdesc}
  
  \subsubsection{\module{distutils.dir_util} -- Directory tree operations}
***************
*** 861,866 ****
  This module contains some utility functions for operating on individual files.
  
! \begin{funcdesc}{copy_file}{src, dst\optional{preserve_mode, preserve_times, update, link, verbose, dry_run}}
! Copy file \var{src} to \var{dst}. XXX todo
  \end{funcdesc}
  
--- 893,926 ----
  This module contains some utility functions for operating on individual files.
  
! \begin{funcdesc}{copy_file}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, update=\code{0}, link=\code{None}, verbose=\code{0}, dry_run=\code{0}}}
! Copy file \var{src} to \var{dst}. If \var{dst} is a directory, then
! \var{src} is copied there with the same name; otherwise, it must be a
! filename. (If the file exists, it will be ruthlessly clobbered.) If
! \var{preserve_mode} is true (the default), the file's mode (type and
! permission bits, or whatever is analogous on the current platform) is
! copied. If \var{preserve_times} is true (the default), the last-modified
! and last-access times are copied as well. If \var{update} is true,
! \var{src} will only be copied if \var{dst} does not exist, or if
! \var{dst} does exist but is older than \var{src}.
! 
! \var{link} allows you to make hard links (using \function{os.link}) or
! symbolic links (using \function{os.symlink}) instead of copying: set it
! to \code{"hard"} or \code{"sym"}; if it is \code{None} (the default),
! files are copied. Don't set \var{link} on systems that don't support
! it: \function{copy_file()} doesn't check if hard or symbolic linking is
! available.
! 
! Under Mac OS 9, uses the native file copy function in \module{macostools}; 
! on other systems, uses \var{_copy_file_contents()} to copy file contents.
! 
! Return a tuple \samp{(dest_name, copied)}: \var{dest_name} is the actual 
! name of the output file, and \var{copied} is true if the file was copied 
! (or would have been copied, if \var{dry_run} true).
! % XXX if the destination file already exists, we clobber it if
! % copying, but blow up if linking.  Hmmm.  And I don't know what
! % macostools.copyfile() does.  Should definitely be consistent, and
! % should probably blow up if destination exists and we would be
! % changing it (ie. it's not already a hard/soft link to src OR
! % (not update) and (src newer than dst)).
  \end{funcdesc}
  
***************
*** 868,876 ****
  Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will
  be moved into it with the same name; otherwise, \var{src} is just renamed
! to 'dst'.  Return the new full name of the file.
! XXX todo    Handles cross-device moves on Unix using 'copy_file()'.  What about
! other systems???
  \end{funcdesc}
  
  
  \subsubsection{\module{distutils.utils} -- Miscellaneous other utility functions}
--- 928,940 ----
  Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will
  be moved into it with the same name; otherwise, \var{src} is just renamed
! to \var{dst}.  Returns the new full name of the file.
! \warning{Handles cross-device moves on Unix using \function{copy_file()}.  
! What about other systems???}
  \end{funcdesc}
  
+ \begin{funcdesc}{write_file}{filename, contents}
+ Create a file called \var{filename} and write \var{contents} (a
+ sequence of strings without line terminators) to it.
+ \end{funcdesc}
  
  \subsubsection{\module{distutils.utils} -- Miscellaneous other utility functions}