| 1 |
:mod:`!netrc` --- netrc file processing |
| 2 |
======================================= |
| 3 |
|
| 4 |
.. module:: netrc |
| 5 |
:synopsis: Loading of .netrc files. |
| 6 |
|
| 7 |
.. moduleauthor:: Eric S. Raymond <[email protected]> |
| 8 |
.. sectionauthor:: Eric S. Raymond <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/netrc.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 14 |
The :class:`~netrc.netrc` class parses and encapsulates the netrc file format used by |
| 15 |
the Unix :program:`ftp` program and other FTP clients. |
| 16 |
|
| 17 |
|
| 18 |
.. class:: netrc([file]) |
| 19 |
|
| 20 |
A :class:`~netrc.netrc` instance or subclass instance encapsulates data from a netrc |
| 21 |
file. The initialization argument, if present, specifies the file to parse. If |
| 22 |
no argument is given, the file :file:`.netrc` in the user's home directory -- |
| 23 |
as determined by :func:`os.path.expanduser` -- will be read. Otherwise, |
| 24 |
a :exc:`FileNotFoundError` exception will be raised. |
| 25 |
Parse errors will raise :exc:`NetrcParseError` with diagnostic |
| 26 |
information including the file name, line number, and terminating token. |
| 27 |
|
| 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`. Such security checks are not available |
| 34 |
on platforms that do not support :func:`os.getuid`. |
| 35 |
|
| 36 |
.. versionchanged:: 3.4 Added the POSIX permission check. |
| 37 |
|
| 38 |
.. versionchanged:: 3.7 |
| 39 |
:func:`os.path.expanduser` is used to find the location of the |
| 40 |
:file:`.netrc` file when *file* is not passed as argument. |
| 41 |
|
| 42 |
.. versionchanged:: 3.10 |
| 43 |
:class:`netrc` try UTF-8 encoding before using locale specific |
| 44 |
encoding. |
| 45 |
The entry in the netrc file no longer needs to contain all tokens. The missing |
| 46 |
tokens' value default to an empty string. All the tokens and their values now |
| 47 |
can contain arbitrary characters, like whitespace and non-ASCII characters. |
| 48 |
If the login name is anonymous, it won't trigger the security check. |
| 49 |
|
| 50 |
|
| 51 |
.. exception:: NetrcParseError |
| 52 |
|
| 53 |
Exception raised by the :class:`~netrc.netrc` class when syntactical errors are |
| 54 |
encountered in source text. Instances of this exception provide three |
| 55 |
interesting attributes: |
| 56 |
|
| 57 |
.. attribute:: msg |
| 58 |
|
| 59 |
Textual explanation of the error. |
| 60 |
|
| 61 |
.. attribute:: filename |
| 62 |
|
| 63 |
The name of the source file. |
| 64 |
|
| 65 |
.. attribute:: lineno |
| 66 |
|
| 67 |
The line number on which the error was found. |
| 68 |
|
| 69 |
|
| 70 |
.. _netrc-objects: |
| 71 |
|
| 72 |
netrc Objects |
| 73 |
------------- |
| 74 |
|
| 75 |
A :class:`~netrc.netrc` instance has the following methods: |
| 76 |
|
| 77 |
|
| 78 |
.. method:: netrc.authenticators(host) |
| 79 |
|
| 80 |
Return a 3-tuple ``(login, account, password)`` of authenticators for *host*. |
| 81 |
If the netrc file did not contain an entry for the given host, return the tuple |
| 82 |
associated with the 'default' entry. If neither matching host nor default entry |
| 83 |
is available, return ``None``. |
| 84 |
|
| 85 |
|
| 86 |
.. method:: netrc.__repr__() |
| 87 |
|
| 88 |
Dump the class data as a string in the format of a netrc file. (This discards |
| 89 |
comments and may reorder the entries.) |
| 90 |
|
| 91 |
Instances of :class:`~netrc.netrc` have public instance variables: |
| 92 |
|
| 93 |
|
| 94 |
.. attribute:: netrc.hosts |
| 95 |
|
| 96 |
Dictionary mapping host names to ``(login, account, password)`` tuples. The |
| 97 |
'default' entry, if any, is represented as a pseudo-host by that name. |
| 98 |
|
| 99 |
|
| 100 |
.. attribute:: netrc.macros |
| 101 |
|
| 102 |
Dictionary mapping macro names to string lists. |