| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`netrc` --- netrc file processing |
| 3 | ====================================== |
| 4 | |
| 5 | .. module:: netrc |
| 6 | :synopsis: Loading of .netrc files. |
| 7 | .. moduleauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 8 | .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 9 | |
| 10 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | The :class:`netrc` class parses and encapsulates the netrc file format used by |
| 12 | the Unix :program:`ftp` program and other FTP clients. |
| 13 | |
| 14 | |
| 15 | .. class:: netrc([file]) |
| 16 | |
| 17 | A :class:`netrc` instance or subclass instance encapsulates data from a netrc |
| 18 | file. The initialization argument, if present, specifies the file to parse. If |
| 19 | no argument is given, the file :file:`.netrc` in the user's home directory will |
| 20 | be read. Parse errors will raise :exc:`NetrcParseError` with diagnostic |
| 21 | information including the file name, line number, and terminating token. |
| 22 | |
| 23 | |
| 24 | .. exception:: NetrcParseError |
| 25 | |
| 26 | Exception raised by the :class:`netrc` class when syntactical errors are |
| 27 | encountered in source text. Instances of this exception provide three |
| 28 | interesting attributes: :attr:`msg` is a textual explanation of the error, |
| 29 | :attr:`filename` is the name of the source file, and :attr:`lineno` gives the |
| 30 | line number on which the error was found. |
| 31 | |
| 32 | |
| 33 | .. _netrc-objects: |
| 34 | |
| 35 | netrc Objects |
| 36 | ------------- |
| 37 | |
| 38 | A :class:`netrc` instance has the following methods: |
| 39 | |
| 40 | |
| 41 | .. method:: netrc.authenticators(host) |
| 42 | |
| 43 | Return a 3-tuple ``(login, account, password)`` of authenticators for *host*. |
| 44 | If the netrc file did not contain an entry for the given host, return the tuple |
| 45 | associated with the 'default' entry. If neither matching host nor default entry |
| 46 | is available, return ``None``. |
| 47 | |
| 48 | |
| 49 | .. method:: netrc.__repr__() |
| 50 | |
| 51 | Dump the class data as a string in the format of a netrc file. (This discards |
| 52 | comments and may reorder the entries.) |
| 53 | |
| 54 | Instances of :class:`netrc` have public instance variables: |
| 55 | |
| 56 | |
| 57 | .. attribute:: netrc.hosts |
| 58 | |
| 59 | Dictionary mapping host names to ``(login, account, password)`` tuples. The |
| 60 | 'default' entry, if any, is represented as a pseudo-host by that name. |
| 61 | |
| 62 | |
| 63 | .. attribute:: netrc.macros |
| 64 | |
| 65 | Dictionary mapping macro names to string lists. |
| 66 | |
| 67 | .. note:: |
| 68 | |
| 69 | Passwords are limited to a subset of the ASCII character set. Versions of |
| 70 | this module prior to 2.3 were extremely limited. Starting with 2.3, all |
| 71 | ASCII punctuation is allowed in passwords. However, note that whitespace and |
| 72 | non-printable characters are not allowed in passwords. This is a limitation |
| 73 | of the way the .netrc file is parsed and may be removed in the future. |
| 74 | |