Doc/lib/libnetrc.tex

\section{\module{netrc} ---
         netrc file processing}

\declaremodule{standard}{netrc}
% Note the \protect needed for \file... ;-(
\modulesynopsis{Loading of \protect\file{.netrc} files.}
\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}


\versionadded{1.5.2}

The \class{netrc} class parses and encapsulates the netrc file format
used by the \UNIX{} \program{ftp} program and other FTP clients.

\begin{classdesc}{netrc}{\optional{file}}
A \class{netrc} instance or subclass instance encapsulates data from 
a netrc file.  The initialization argument, if present, specifies the
file to parse.  If no argument is given, the file \file{.netrc} in the
user's home directory will be read.  Parse errors will raise
\exception{NetrcParseError} with diagnostic information including the
file name, line number, and terminating token.
\end{classdesc}

\begin{excdesc}{NetrcParseError}
Exception raised by the \class{netrc} class when syntactical errors
are encountered in source text.  Instances of this exception provide
three interesting attributes:  \member{msg} is a textual explanation
of the error, \member{filename} is the name of the source file, and
\member{lineno} gives the line number on which the error was found.
\end{excdesc}


\subsection{netrc Objects \label{netrc-objects}}

A \class{netrc} instance has the following methods:

\begin{methoddesc}{authenticators}{host}
Return a 3-tuple \code{(\var{login}, \var{account}, \var{password})}
of authenticators for \var{host}.  If the netrc file did not
contain an entry for the given host, return the tuple associated with
the `default' entry.  If neither matching host nor default entry is
available, return \code{None}.
\end{methoddesc}

\begin{methoddesc}{__repr__}{}
Dump the class data as a string in the format of a netrc file.
(This discards comments and may reorder the entries.)
\end{methoddesc}

Instances of \class{netrc} have public instance variables:

\begin{memberdesc}{hosts}
Dictionary mapping host names to \code{(\var{login}, \var{account},
\var{password})} tuples.  The `default' entry, if any, is represented
as a pseudo-host by that name.
\end{memberdesc}

\begin{memberdesc}{macros}
Dictionary mapping macro names to string lists.
\end{memberdesc}

\note{Versions of this module before 2.2.3 and 2.3 are very limited to a
subset of the ASCII character set for passwords.  Starting with 2.2.3 and
2.3, ASCII punctuation is allowed in passwords.  However, note that spaces
and non-printable characters are not allowed in passwords.  This is a
limitation of the way the .netrc file is parsed and should be removed in the
future.}