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. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. moduleauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 9 | .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 10 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 11 | **Source code:** :source:`Lib/netrc.py` |
| 12 | |
| 13 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 15 | The :class:`~netrc.netrc` class parses and encapsulates the netrc file format used by |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | the Unix :program:`ftp` program and other FTP clients. |
| 17 | |
| 18 | |
| 19 | .. class:: netrc([file]) |
| 20 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 21 | A :class:`~netrc.netrc` instance or subclass instance encapsulates data from a netrc |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | file. The initialization argument, if present, specifies the file to parse. If |
Berker Peksag | 8d9bb11 | 2017-11-25 13:37:22 +0300 | [diff] [blame] | 23 | no argument is given, the file :file:`.netrc` in the user's home directory -- |
| 24 | as determined by :func:`os.path.expanduser` -- will be read. Otherwise, |
| 25 | a :exc:`FileNotFoundError` exception will be raised. |
| 26 | Parse errors will raise :exc:`NetrcParseError` with diagnostic |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | information including the file name, line number, and terminating token. |
R David Murray | 104aab9 | 2013-09-17 20:30:02 -0400 | [diff] [blame] | 28 | If no argument is specified on a POSIX system, the presence of passwords in |
| 29 | the :file:`.netrc` file will raise a :exc:`NetrcParseError` if the file |
| 30 | ownership or permissions are insecure (owned by a user other than the user |
| 31 | running the process, or accessible for read or write by any other user). |
| 32 | This implements security behavior equivalent to that of ftp and other |
| 33 | programs that use :file:`.netrc`. |
| 34 | |
R David Murray | 4750fa8 | 2013-09-17 21:28:17 -0400 | [diff] [blame] | 35 | .. versionchanged:: 3.4 Added the POSIX permission check. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Berker Peksag | 8d9bb11 | 2017-11-25 13:37:22 +0300 | [diff] [blame] | 37 | .. versionchanged:: 3.7 |
| 38 | :func:`os.path.expanduser` is used to find the location of the |
| 39 | :file:`.netrc` file when *file* is not passed as argument. |
| 40 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
| 42 | .. exception:: NetrcParseError |
| 43 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 44 | Exception raised by the :class:`~netrc.netrc` class when syntactical errors are |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | encountered in source text. Instances of this exception provide three |
| 46 | interesting attributes: :attr:`msg` is a textual explanation of the error, |
| 47 | :attr:`filename` is the name of the source file, and :attr:`lineno` gives the |
| 48 | line number on which the error was found. |
| 49 | |
| 50 | |
| 51 | .. _netrc-objects: |
| 52 | |
| 53 | netrc Objects |
| 54 | ------------- |
| 55 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 56 | A :class:`~netrc.netrc` instance has the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | |
| 59 | .. method:: netrc.authenticators(host) |
| 60 | |
| 61 | Return a 3-tuple ``(login, account, password)`` of authenticators for *host*. |
| 62 | If the netrc file did not contain an entry for the given host, return the tuple |
| 63 | associated with the 'default' entry. If neither matching host nor default entry |
| 64 | is available, return ``None``. |
| 65 | |
| 66 | |
| 67 | .. method:: netrc.__repr__() |
| 68 | |
| 69 | Dump the class data as a string in the format of a netrc file. (This discards |
| 70 | comments and may reorder the entries.) |
| 71 | |
Serhiy Storchaka | ee1b01a | 2016-12-02 23:13:53 +0200 | [diff] [blame] | 72 | Instances of :class:`~netrc.netrc` have public instance variables: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | |
| 75 | .. attribute:: netrc.hosts |
| 76 | |
| 77 | Dictionary mapping host names to ``(login, account, password)`` tuples. The |
| 78 | 'default' entry, if any, is represented as a pseudo-host by that name. |
| 79 | |
| 80 | |
| 81 | .. attribute:: netrc.macros |
| 82 | |
| 83 | Dictionary mapping macro names to string lists. |
| 84 | |
| 85 | .. note:: |
| 86 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 87 | Passwords are limited to a subset of the ASCII character set. All ASCII |
| 88 | punctuation is allowed in passwords, however, note that whitespace and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | non-printable characters are not allowed in passwords. This is a limitation |
| 90 | of the way the .netrc file is parsed and may be removed in the future. |