Source code: Lib/nntplib.py
This module defines the class NNTP which implements the client side of the Network News Transfer Protocol. It can be used to implement a news reader or poster, or automated news processors. It is compatible with RFC 3977 as well as the older RFC 977 and RFC 2980.
Here are two small examples of how it can be used. To list some statistics about a newsgroup and print the subjects of the last 10 articles:
To post an article from a binary file (this assumes that the article has valid headers, and that you have right to post on the particular newsgroup):
The module itself defines the following classes:
Return a new NNTP object, representing a connection to the NNTP server running on host host, listening at port port. An optional timeout can be specified for the socket connection. If the optional user and password are provided, or if suitable credentials are present in /.netrc and the optional flag usenetrc is true, the AUTHINFO USER and AUTHINFO PASS commands are used to identify and authenticate the user to the server. If the optional flag readermode is true, then a mode reader command is sent before authentication is performed. Reader mode is sometimes necessary if you are connecting to an NNTP server on the local machine and intend to call reader-specific commands, such as group. If you get unexpected NNTPPermanentErrors, you might need to set readermode. The NNTP class supports the with statement to unconditionally consume OSError exceptions and to close the NNTP connection when done, e.g.:
Raises an auditing event nntplib.connect with arguments self, host, port.
All commands will raise an auditing event nntplib.putline with arguments self and line, where line is the bytes about to be sent to the remote host.
Changed in version 3.2: usenetrc is now False by default.
Changed in version 3.3: Support for the with statement was added.
Changed in version 3.9: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.
Return a new NNTP_SSL object, representing an encrypted connection to the NNTP server running on host host, listening at port port. NNTP_SSL objects have the same methods as NNTP objects. If port is omitted, port 563 (NNTPS) is used. ssl_context is also optional, and is a SSLContext object. Please read Security considerations for best practices. All other parameters behave the same as for NNTP.
Note that SSL-on-563 is discouraged per RFC 4642, in favor of STARTTLS as described below. However, some servers only support the former.
Raises an auditing event nntplib.connect with arguments self, host, port.
All commands will raise an auditing event nntplib.putline with arguments self and line, where line is the bytes about to be sent to the remote host.
New in version 3.2.
Changed in version 3.4: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).
Changed in version 3.9: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.
Derived from the standard exception Exception, this is the base class for all exceptions raised by the nntplib module. Instances of this class have the following attribute:
The response of the server if available, as a str object.
Exception raised when an unexpected reply is received from the server.
Exception raised when a response code in the range 400–499 is received.
Exception raised when a response code in the range 500–599 is received.
Exception raised when a reply is received from the server that does not begin with a digit in the range 1–5.
Exception raised when there is some error in the response data.
When connected, NNTP and NNTP_SSL objects support the following methods and attributes.
An integer representing the version of the NNTP protocol supported by the server. In practice, this should be 2 for servers advertising RFC 3977 compliance and 1 for others.
New in version 3.2.
A string describing the software name and version of the NNTP server, or None if not advertised by the server.
New in version 3.2.
The response that is returned as the first item in the return tuple of almost all methods is the server’s response: a string beginning with a three-digit code. If the server’s response indicates an error, the method raises one of the above exceptions.
Many of the following methods take an optional keyword-only argument file. When the file argument is supplied, it must be either a file object opened for binary writing, or the name of an on-disk file to be written to. The method will then write any data returned by the server (except for the response line and the terminating dot) to the file; any list of lines, tuples or objects that the method normally returns will be empty.
Changed in version 3.2: Many of the following methods have been reworked and fixed, which makes them incompatible with their 3.1 counterparts.
Send a QUIT command and close the connection. Once this method has been called, no other methods of the NNTP object should be called.
Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.)
Return the RFC 3977 capabilities advertised by the server, as a dict instance mapping capability names to (possibly empty) lists of values. On legacy servers which don’t understand the CAPABILITIES command, an empty dictionary is returned instead.
New in version 3.2.
Send AUTHINFO commands with the user name and password. If user and password are None and usenetrc is true, credentials from ~/.netrc will be used if possible.
Unless intentionally delayed, login is normally performed during the NNTP object initialization and separately calling this function is unnecessary. To force authentication to be delayed, you must not set user or password when creating the object, and must set usenetrc to False.
New in version 3.2.
Send a STARTTLS command. This will enable encryption on the NNTP connection. The context argument is optional and should be a ssl.SSLContext object. Please read Security considerations for best practices.
Note that this may not be done after authentication information has been transmitted, and authentication occurs by default if possible during a NNTP object initialization. See NNTP.login() for information on suppressing this behavior.
New in version 3.2.
Changed in version 3.4: The method now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).
Send a NEWGROUPS command. The date argument should be a datetime.date or datetime.datetime object. Return a pair (response, groups) where groups is a list representing the groups that are new since the given date. If file is supplied, though, then groups will be empty.
Send a NEWNEWS command. Here, group is a group name or '*', and date has the same meaning as for newgroups(). Return a pair (response, articles) where articles is a list of message ids.
This command is frequently disabled by NNTP server administrators.
Send a LIST or LIST ACTIVE command. Return a pair (response, list) where list is a list of tuples representing all the groups available from this NNTP server, optionally matching the pattern string group_pattern. Each tuple has the form (group, last, first, flag), where group is a group name, last and first are the last and first article numbers, and flag usually takes one of these values:
If flag has another value, then the status of the newsgroup should be considered unknown.
This command can return very large results, especially if group_pattern is not specified. It is best to cache the results offline unless you really need to refresh them.
Changed in version 3.2: group_pattern was added.
Send a LIST NEWSGROUPS command, where grouppattern is a wildmat string as specified in RFC 3977 (it’s essentially the same as DOS or UNIX shell wildcard strings). Return a pair (response, descriptions), where descriptions is a dictionary mapping group names to textual descriptions.
Get a description for a single group group. If more than one group matches (if ‘group’ is a real wildmat string), return the first match. If no group matches, return an empty string.
This elides the response code from the server. If the response code is needed, use descriptions().
Send a GROUP command, where name is the group name. The group is selected as the current group, if it exists. Return a tuple (response, count, first, last, name) where count is the (estimated) number of articles in the group, first is the first article number in the group, last is the last article number in the group, and name is the group name.
Send an OVER command, or an XOVER command on legacy servers. message_spec can be either a string representing a message id, or a (first, last) tuple of numbers indicating a range of articles in the current group, or a (first, None) tuple indicating a range of articles starting from first to the last article in the current group, or None to select the current article in the current group.
Return a pair (response, overviews). overviews is a list of (article_number, overview) tuples, one for each article selected by message_spec. Each overview is a dictionary with the same number of items, but this number depends on the server. These items are either message headers (the key is then the lower-cased header name) or metadata items (the key is then the metadata name prepended with ":"). The following items are guaranteed to be present by the NNTP specification:
The value of each item is either a string, or None if not present.
It is advisable to use the decode_header() function on header values when they may contain non-ASCII characters:
New in version 3.2.
Send a HELP command. Return a pair (response, list) where list is a list of help strings.
Send a STAT command, where message_spec is either a message id (enclosed in '<' and '>') or an article number in the current group. If message_spec is omitted or None, the current article in the current group is considered. Return a triple (response, number, id) where number is the article number and id is the message id.
Send a NEXT command. Return as for stat().
Send a LAST command. Return as for stat().
Send an ARTICLE command, where message_spec has the same meaning as for stat(). Return a tuple (response, info) where info is a namedtuple with three attributes number, message_id and lines (in that order). number is the article number in the group (or 0 if the information is not available), message_id the message id as a string, and lines a list of lines (without terminating newlines) comprising the raw message including headers and body.
Same as article(), but sends a HEAD command. The lines returned (or written to file) will only contain the message headers, not the body.
Same as article(), but sends a BODY command. The lines returned (or written to file) will only contain the message body, not the headers.
Post an article using the POST command. The data argument is either a file object opened for binary reading, or any iterable of bytes objects (representing raw lines of the article to be posted). It should represent a well-formed news article, including the required headers. The post() method automatically escapes lines beginning with . and appends the termination line.
If the method succeeds, the server’s response is returned. If the server refuses posting, a NNTPReplyError is raised.
Send an IHAVE command. message_id is the id of the message to send to the server (enclosed in '<' and '>'). The data parameter and the return value are the same as for post().
Return a pair (response, date). date is a datetime object containing the current date and time of the server.
Send a SLAVE command. Return the server’s response.
Set the instance’s debugging level. This controls the amount of debugging output printed. The default, 0, produces no debugging output. A value of 1 produces a moderate amount of debugging output, generally a single line per request or response. A value of 2 or higher produces the maximum amount of debugging output, logging each line sent and received on the connection (including message text).
The following are optional NNTP extensions defined in RFC 2980. Some of them have been superseded by newer commands in RFC 3977.
Send an XHDR command. The hdr argument is a header keyword, e.g. 'subject'. The str argument should have the form 'first-last' where first and last are the first and last article numbers to search. Return a pair (response, list), where list is a list of pairs (id,
text), where id is an article number (as a string) and text is the text of the requested header for that article. If the file parameter is supplied, then the output of the XHDR command is stored in a file. If file is a string, then the method will open a file with that name, write to it then close it. If file is a file object, then it will start calling write() on it to store the lines of the command output. If file is supplied, then the returned list is an empty list.
Send an XOVER command. start and end are article numbers delimiting the range of articles to select. The return value is the same of for over(). It is recommended to use over() instead, since it will automatically use the newer OVER command if available.
The module also defines the following utility function:
Decode a header value, un-escaping any escaped non-ASCII characters. header_str must be a str object. The unescaped value is returned. Using this function is recommended to display some headers in a human readable form:


Decode a header value, un-escaping any escaped non-ASCII characters. header_str must be a str object. The unescaped value is returned. Using this function is recommended to display some headers in a human readable form:


Return a new NNTP object, representing a connection to the NNTP server running on host host, listening at port port. An optional timeout can be specified for the socket connection. If the optional user and password are provided, or if suitable credentials are present in /.netrc and the optional flag usenetrc is true, the AUTHINFO USER and AUTHINFO PASS commands are used to identify and authenticate the user to the server. If the optional flag readermode is true, then a mode reader command is sent before authentication is performed. Reader mode is sometimes necessary if you are connecting to an NNTP server on the local machine and intend to call reader-specific commands, such as group. If you get unexpected NNTPPermanentErrors, you might need to set readermode. The NNTP class supports the with statement to unconditionally consume OSError exceptions and to close the NNTP connection when done, e.g.:
Raises an auditing event nntplib.connect with arguments self, host, port.
All commands will raise an auditing event nntplib.putline with arguments self and line, where line is the bytes about to be sent to the remote host.
Changed in version 3.2: usenetrc is now False by default.
Changed in version 3.3: Support for the with statement was added.
Changed in version 3.9: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.


Send an ARTICLE command, where message_spec has the same meaning as for stat(). Return a tuple (response, info) where info is a namedtuple with three attributes number, message_id and lines (in that order). number is the article number in the group (or 0 if the information is not available), message_id the message id as a string, and lines a list of lines (without terminating newlines) comprising the raw message including headers and body.


Same as article(), but sends a BODY command. The lines returned (or written to file) will only contain the message body, not the headers.


Return a pair (response, date). date is a datetime object containing the current date and time of the server.


Get a description for a single group group. If more than one group matches (if ‘group’ is a real wildmat string), return the first match. If no group matches, return an empty string.
This elides the response code from the server. If the response code is needed, use descriptions().


Send a LIST NEWSGROUPS command, where grouppattern is a wildmat string as specified in RFC 3977 (it’s essentially the same as DOS or UNIX shell wildcard strings). Return a pair (response, descriptions), where descriptions is a dictionary mapping group names to textual descriptions.


Return the RFC 3977 capabilities advertised by the server, as a dict instance mapping capability names to (possibly empty) lists of values. On legacy servers which don’t understand the CAPABILITIES command, an empty dictionary is returned instead.
New in version 3.2.


Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.)


Send a GROUP command, where name is the group name. The group is selected as the current group, if it exists. Return a tuple (response, count, first, last, name) where count is the (estimated) number of articles in the group, first is the first article number in the group, last is the last article number in the group, and name is the group name.


Same as article(), but sends a HEAD command. The lines returned (or written to file) will only contain the message headers, not the body.


Send a HELP command. Return a pair (response, list) where list is a list of help strings.


Send an IHAVE command. message_id is the id of the message to send to the server (enclosed in '<' and '>'). The data parameter and the return value are the same as for post().


Send a LAST command. Return as for stat().


Send a LIST or LIST ACTIVE command. Return a pair (response, list) where list is a list of tuples representing all the groups available from this NNTP server, optionally matching the pattern string group_pattern. Each tuple has the form (group, last, first, flag), where group is a group name, last and first are the last and first article numbers, and flag usually takes one of these values:
If flag has another value, then the status of the newsgroup should be considered unknown.
This command can return very large results, especially if group_pattern is not specified. It is best to cache the results offline unless you really need to refresh them.
Changed in version 3.2: group_pattern was added.


Send AUTHINFO commands with the user name and password. If user and password are None and usenetrc is true, credentials from ~/.netrc will be used if possible.
Unless intentionally delayed, login is normally performed during the NNTP object initialization and separately calling this function is unnecessary. To force authentication to be delayed, you must not set user or password when creating the object, and must set usenetrc to False.
New in version 3.2.


Send a NEWGROUPS command. The date argument should be a datetime.date or datetime.datetime object. Return a pair (response, groups) where groups is a list representing the groups that are new since the given date. If file is supplied, though, then groups will be empty.


Send a NEWNEWS command. Here, group is a group name or '*', and date has the same meaning as for newgroups(). Return a pair (response, articles) where articles is a list of message ids.
This command is frequently disabled by NNTP server administrators.


Send a NEXT command. Return as for stat().


A string describing the software name and version of the NNTP server, or None if not advertised by the server.
New in version 3.2.


An integer representing the version of the NNTP protocol supported by the server. In practice, this should be 2 for servers advertising RFC 3977 compliance and 1 for others.
New in version 3.2.


Send an OVER command, or an XOVER command on legacy servers. message_spec can be either a string representing a message id, or a (first, last) tuple of numbers indicating a range of articles in the current group, or a (first, None) tuple indicating a range of articles starting from first to the last article in the current group, or None to select the current article in the current group.
Return a pair (response, overviews). overviews is a list of (article_number, overview) tuples, one for each article selected by message_spec. Each overview is a dictionary with the same number of items, but this number depends on the server. These items are either message headers (the key is then the lower-cased header name) or metadata items (the key is then the metadata name prepended with ":"). The following items are guaranteed to be present by the NNTP specification:
The value of each item is either a string, or None if not present.
It is advisable to use the decode_header() function on header values when they may contain non-ASCII characters:
New in version 3.2.


Post an article using the POST command. The data argument is either a file object opened for binary reading, or any iterable of bytes objects (representing raw lines of the article to be posted). It should represent a well-formed news article, including the required headers. The post() method automatically escapes lines beginning with . and appends the termination line.
If the method succeeds, the server’s response is returned. If the server refuses posting, a NNTPReplyError is raised.


Send a QUIT command and close the connection. Once this method has been called, no other methods of the NNTP object should be called.


Set the instance’s debugging level. This controls the amount of debugging output printed. The default, 0, produces no debugging output. A value of 1 produces a moderate amount of debugging output, generally a single line per request or response. A value of 2 or higher produces the maximum amount of debugging output, logging each line sent and received on the connection (including message text).


Send a SLAVE command. Return the server’s response.


Send a STARTTLS command. This will enable encryption on the NNTP connection. The context argument is optional and should be a ssl.SSLContext object. Please read Security considerations for best practices.
Note that this may not be done after authentication information has been transmitted, and authentication occurs by default if possible during a NNTP object initialization. See NNTP.login() for information on suppressing this behavior.
New in version 3.2.
Changed in version 3.4: The method now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).


Send a STAT command, where message_spec is either a message id (enclosed in '<' and '>') or an article number in the current group. If message_spec is omitted or None, the current article in the current group is considered. Return a triple (response, number, id) where number is the article number and id is the message id.


Send an XHDR command. The hdr argument is a header keyword, e.g. 'subject'. The str argument should have the form 'first-last' where first and last are the first and last article numbers to search. Return a pair (response, list), where list is a list of pairs (id,
text), where id is an article number (as a string) and text is the text of the requested header for that article. If the file parameter is supplied, then the output of the XHDR command is stored in a file. If file is a string, then the method will open a file with that name, write to it then close it. If file is a file object, then it will start calling write() on it to store the lines of the command output. If file is supplied, then the returned list is an empty list.


Send an XOVER command. start and end are article numbers delimiting the range of articles to select. The return value is the same of for over(). It is recommended to use over() instead, since it will automatically use the newer OVER command if available.


Exception raised when there is some error in the response data.


Derived from the standard exception Exception, this is the base class for all exceptions raised by the nntplib module. Instances of this class have the following attribute:
The response of the server if available, as a str object.


The response of the server if available, as a str object.


Exception raised when a response code in the range 500–599 is received.


Exception raised when a reply is received from the server that does not begin with a digit in the range 1–5.


Exception raised when an unexpected reply is received from the server.


Exception raised when a response code in the range 400–499 is received.


Return a new NNTP_SSL object, representing an encrypted connection to the NNTP server running on host host, listening at port port. NNTP_SSL objects have the same methods as NNTP objects. If port is omitted, port 563 (NNTPS) is used. ssl_context is also optional, and is a SSLContext object. Please read Security considerations for best practices. All other parameters behave the same as for NNTP.
Note that SSL-on-563 is discouraged per RFC 4642, in favor of STARTTLS as described below. However, some servers only support the former.
Raises an auditing event nntplib.connect with arguments self, host, port.
All commands will raise an auditing event nntplib.putline with arguments self and line, where line is the bytes about to be sent to the remote host.
New in version 3.2.
Changed in version 3.4: The class now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.HAS_SNI).
Changed in version 3.9: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.


The sole value of the type NoneType. None is frequently used to represent the absence of a value, as when default arguments are not passed to a function. Assignments to None are illegal and raise a SyntaxError.


Raised when a directory operation (such as os.listdir()) is requested on something which is not a directory. Corresponds to errno ENOTDIR.


Special value which should be returned by the binary special methods (e.g. __eq__(), __lt__(), __add__(), __rsub__(), etc.) to indicate that the operation is not implemented with respect to the other type; may be returned by the in-place binary special methods (e.g. __imul__(), __iand__(), etc.) for the same purpose. It should not be evaluated in a boolean context.
Note
When a binary (or in-place) method returns NotImplemented the interpreter will try the reflected operation on the other type (or some other fallback, depending on the operator). If all attempts return NotImplemented, the interpreter will raise an appropriate exception. Incorrectly returning NotImplemented will result in a misleading error message or the NotImplemented value being returned to Python code.
See Implementing the arithmetic operations for examples.
Note
NotImplementedError and NotImplemented are not interchangeable, even though they have similar names and purposes. See NotImplementedError for details on when to use it.
Changed in version 3.9: Evaluating NotImplemented in a boolean context is deprecated. While it currently evaluates as true, it will emit a DeprecationWarning. It will raise a TypeError in a future version of Python.


This exception is derived from RuntimeError. In user defined base classes, abstract methods should raise this exception when they require derived classes to override the method, or while the class is being developed to indicate that the real implementation still needs to be added.
Note
It should not be used to indicate that an operator or method is not meant to be supported at all – in that case either leave the operator / method undefined or, if a subclass, set it to None.
Note
NotImplementedError and NotImplemented are not interchangeable, even though they have similar names and purposes. See NotImplemented for details on when to use it.


Source code: Lib/numbers.py
The numbers module (PEP 3141) defines a hierarchy of numeric abstract base classes which progressively define more operations. None of the types defined in this module can be instantiated.
The root of the numeric hierarchy. If you just want to check if an argument x is a number, without caring what kind, use isinstance(x, Number).
Subclasses of this type describe complex numbers and include the operations that work on the built-in complex type. These are: conversions to complex and bool, real, imag, +, -, *, /, abs(), conjugate(), ==, and !=. All except - and != are abstract.
Abstract. Retrieves the real component of this number.
Abstract. Retrieves the imaginary component of this number.
Abstract. Returns the complex conjugate. For example, (1+3j).conjugate()
== (1-3j).
To Complex, Real adds the operations that work on real numbers.
In short, those are: a conversion to float, math.trunc(), round(), math.floor(), math.ceil(), divmod(), //, %, <, <=, >, and >=.
Real also provides defaults for complex(), real, imag, and conjugate().
Subtypes Real and adds numerator and denominator properties, which should be in lowest terms. With these, it provides a default for float().
Abstract.
Abstract.
Subtypes Rational and adds a conversion to int. Provides defaults for float(), numerator, and denominator. Adds abstract methods for ** and bit-string operations: <<, >>, &, ^, |, ~.
Implementors should be careful to make equal numbers equal and hash them to the same values. This may be subtle if there are two different extensions of the real numbers. For example, fractions.Fraction implements hash() as follows:
There are, of course, more possible ABCs for numbers, and this would be a poor hierarchy if it precluded the possibility of adding those. You can add MyFoo between Complex and Real with:
We want to implement the arithmetic operations so that mixed-mode operations either call an implementation whose author knew about the types of both arguments, or convert both to the nearest built in type and do the operation there. For subtypes of Integral, this means that __add__() and __radd__() should be defined as:
There are 5 different cases for a mixed-type operation on subclasses of Complex. I’ll refer to all of the above code that doesn’t refer to MyIntegral and OtherTypeIKnowAbout as “boilerplate”. a will be an instance of A, which is a subtype of Complex (a : A <: Complex), and b : B <:
Complex. I’ll consider a + b:
If A <: Complex and B <: Real without sharing any other knowledge, then the appropriate shared operation is the one involving the built in complex, and both __radd__() s land there, so a+b
== b+a.
Because most of the operations on any given type will be very similar, it can be useful to define a helper function which generates the forward and reverse instances of any given operator. For example, fractions.Fraction uses:


Subclasses of this type describe complex numbers and include the operations that work on the built-in complex type. These are: conversions to complex and bool, real, imag, +, -, *, /, abs(), conjugate(), ==, and !=. All except - and != are abstract.
Abstract. Retrieves the real component of this number.
Abstract. Retrieves the imaginary component of this number.
Abstract. Returns the complex conjugate. For example, (1+3j).conjugate()
== (1-3j).


Abstract. Returns the complex conjugate. For example, (1+3j).conjugate()
== (1-3j).


Abstract. Retrieves the imaginary component of this number.


Abstract. Retrieves the real component of this number.


Subtypes Rational and adds a conversion to int. Provides defaults for float(), numerator, and denominator. Adds abstract methods for ** and bit-string operations: <<, >>, &, ^, |, ~.


The root of the numeric hierarchy. If you just want to check if an argument x is a number, without caring what kind, use isinstance(x, Number).


Subtypes Real and adds numerator and denominator properties, which should be in lowest terms. With these, it provides a default for float().
Abstract.
Abstract.


To Complex, Real adds the operations that work on real numbers.
In short, those are: a conversion to float, math.trunc(), round(), math.floor(), math.ceil(), divmod(), //, %, <, <=, >, and >=.
Real also provides defaults for complex(), real, imag, and conjugate().


Return a new featureless object. object is a base for all classes. It has the methods that are common to all instances of Python classes. This function does not accept any arguments.
Note
object does not have a __dict__, so you can’t assign arbitrary attributes to an instance of the object class.


A dictionary or other mapping object used to store an object’s (writable) attributes.


In protocols 2 and newer, classes that implements the __getnewargs_ex__() method can dictate the values passed to the __new__() method upon unpickling. The method must return a pair (args, kwargs) where args is a tuple of positional arguments and kwargs a dictionary of named arguments for constructing the object. Those will be passed to the __new__() method upon unpickling.
You should implement this method if the __new__() method of your class requires keyword-only arguments. Otherwise, it is recommended for compatibility to implement __getnewargs__().
Changed in version 3.6: __getnewargs_ex__() is now used in protocols 2 and 3.


This method serves a similar purpose as __getnewargs_ex__(), but supports only positional arguments. It must return a tuple of arguments args which will be passed to the __new__() method upon unpickling.
__getnewargs__() will not be called if __getnewargs_ex__() is defined.
Changed in version 3.6: Before Python 3.6, __getnewargs__() was called instead of __getnewargs_ex__() in protocols 2 and 3.


Classes can further influence how their instances are pickled; if the class defines the method __getstate__(), it is called and the returned object is pickled as the contents for the instance, instead of the contents of the instance’s dictionary. If the __getstate__() method is absent, the instance’s __dict__ is pickled as usual.


Alternatively, a __reduce_ex__() method may be defined. The only difference is this method should take a single integer argument, the protocol version. When defined, pickle will prefer it over the __reduce__() method. In addition, __reduce__() automatically becomes a synonym for the extended version. The main use for this method is to provide backwards-compatible reduce values for older Python releases.


The interface is currently defined as follows. The __reduce__() method takes no argument and shall return either a string or preferably a tuple (the returned object is often referred to as the “reduce value”).
If a string is returned, the string should be interpreted as the name of a global variable. It should be the object’s local name relative to its module; the pickle module searches the module namespace to determine the object’s module. This behaviour is typically useful for singletons.
When a tuple is returned, it must be between two and six items long. Optional items can either be omitted, or None can be provided as their value. The semantics of each item are in order:
Optionally, a callable with a (obj, state) signature. This callable allows the user to programmatically control the state-updating behavior of a specific object, instead of using obj’s static __setstate__() method. If not None, this callable will have priority over obj’s __setstate__().
New in version 3.8: The optional sixth tuple item, (obj, state), was added.


Upon unpickling, if the class defines __setstate__(), it is called with the unpickled state. In that case, there is no requirement for the state object to be a dictionary. Otherwise, the pickled state must be a dictionary and its items are assigned to the new instance’s dictionary.
Note
If __getstate__() returns a false value, the __setstate__() method will not be called upon unpickling.


Convert an integer number to an octal string prefixed with “0o”. The result is a valid Python expression. If x is not a Python int object, it has to define an __index__() method that returns an integer. For example:
If you want to convert an integer number to octal string either with prefix “0o” or not, you can use either of the following ways.
See also format() for more information.


Open file and return a corresponding file object. If the file cannot be opened, an OSError is raised. See Reading and Writing Files for more examples of how to use this function.
file is a path-like object giving the pathname (absolute or relative to the current working directory) of the file to be opened or an integer file descriptor of the file to be wrapped. (If a file descriptor is given, it is closed when the returned I/O object is closed, unless closefd is set to False.)
mode is an optional string that specifies the mode in which the file is opened. It defaults to 'r' which means open for reading in text mode. Other common values are 'w' for writing (truncating the file if it already exists), 'x' for exclusive creation and 'a' for appending (which on some Unix systems, means that all writes append to the end of the file regardless of the current seek position). In text mode, if encoding is not specified the encoding used is platform dependent: locale.getpreferredencoding(False) is called to get the current locale encoding. (For reading and writing raw bytes use binary mode and leave encoding unspecified.) The available modes are:
Character
Meaning
'r'
open for reading (default)
'w'
open for writing, truncating the file first
'x'
open for exclusive creation, failing if the file already exists
'a'
open for writing, appending to the end of the file if it exists
'b'
binary mode
't'
text mode (default)
'+'
open for updating (reading and writing)
The default mode is 'r' (open for reading text, synonym of 'rt'). Modes 'w+' and 'w+b' open and truncate the file. Modes 'r+' and 'r+b' open the file with no truncation.
As mentioned in the Overview, Python distinguishes between binary and text I/O. Files opened in binary mode (including 'b' in the mode argument) return contents as bytes objects without any decoding. In text mode (the default, or when 't' is included in the mode argument), the contents of the file are returned as str, the bytes having been first decoded using a platform-dependent encoding or using the specified encoding if given.
There is an additional mode character permitted, 'U', which no longer has any effect, and is considered deprecated. It previously enabled universal newlines in text mode, which became the default behaviour in Python 3.0. Refer to the documentation of the newline parameter for further details.
Note
Python doesn’t depend on the underlying operating system’s notion of text files; all the processing is done by Python itself, and is therefore platform-independent.
buffering is an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer. When no buffering argument is given, the default buffering policy works as follows:
encoding is the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is platform dependent (whatever locale.getpreferredencoding() returns), but any text encoding supported by Python can be used. See the codecs module for the list of supported encodings.
errors is an optional string that specifies how encoding and decoding errors are to be handled—this cannot be used in binary mode. A variety of standard error handlers are available (listed under Error Handlers), though any error handling name that has been registered with codecs.register_error() is also valid. The standard names include:
newline controls how universal newlines mode works (it only applies to text mode). It can be None, '', '\n', '\r', and '\r\n'. It works as follows:
If closefd is False and a file descriptor rather than a filename was given, the underlying file descriptor will be kept open when the file is closed. If a filename is given closefd must be True (the default) otherwise an error will be raised.
A custom opener can be used by passing a callable as opener. The underlying file descriptor for the file object is then obtained by calling opener with (file, flags). opener must return an open file descriptor (passing os.open as opener results in functionality similar to passing None).
The newly created file is non-inheritable.
The following example uses the dir_fd parameter of the os.open() function to open a file relative to a given directory:
The type of file object returned by the open() function depends on the mode. When open() is used to open a file in a text mode ('w', 'r', 'wt', 'rt', etc.), it returns a subclass of io.TextIOBase (specifically io.TextIOWrapper). When used to open a file in a binary mode with buffering, the returned class is a subclass of io.BufferedIOBase. The exact class varies: in read binary mode, it returns an io.BufferedReader; in write binary and append binary modes, it returns an io.BufferedWriter, and in read/write mode, it returns an io.BufferedRandom. When buffering is disabled, the raw stream, a subclass of io.RawIOBase, io.FileIO, is returned.
See also the file handling modules, such as, fileinput, io (where open() is declared), os, os.path, tempfile, and shutil.
Raises an auditing event open with arguments file, mode, flags.
The mode and flags arguments may have been modified or inferred from the original call.
Deprecated since version 3.4, will be removed in version 3.10: The 'U' mode.


This method is not defined in BaseHandler, but subclasses should define it if they want to handle URLs with the given protocol.
This method, if defined, will be called by the parent OpenerDirector. Return values should be the same as for default_open().


Source code: Lib/operator.py
The operator module exports a set of efficient functions corresponding to the intrinsic operators of Python. For example, operator.add(x, y) is equivalent to the expression x+y. Many function names are those used for special methods, without the double underscores. For backward compatibility, many of these have a variant with the double underscores kept. The variants without the double underscores are preferred for clarity.
The functions fall into categories that perform object comparisons, logical operations, mathematical operations and sequence operations.
The object comparison functions are useful for all objects, and are named after the rich comparison operators they support:
Perform “rich comparisons” between a and b. Specifically, lt(a, b) is equivalent to a < b, le(a, b) is equivalent to a <= b, eq(a,
b) is equivalent to a == b, ne(a, b) is equivalent to a != b, gt(a, b) is equivalent to a > b and ge(a, b) is equivalent to a
>= b. Note that these functions can return any value, which may or may not be interpretable as a Boolean value. See Comparisons for more information about rich comparisons.
The logical operations are also generally applicable to all objects, and support truth tests, identity tests, and boolean operations:
Return the outcome of not obj. (Note that there is no __not__() method for object instances; only the interpreter core defines this operation. The result is affected by the __bool__() and __len__() methods.)
Return True if obj is true, and False otherwise. This is equivalent to using the bool constructor.
Return a is b. Tests object identity.
Return a is not b. Tests object identity.
The mathematical and bitwise operations are the most numerous:
Return the absolute value of obj.
Return a + b, for a and b numbers.
Return the bitwise and of a and b.
Return a // b.
Return a converted to an integer. Equivalent to a.__index__().
Return the bitwise inverse of the number obj. This is equivalent to ~obj.
Return a shifted left by b.
Return a % b.
Return a * b, for a and b numbers.
Return a @ b.
New in version 3.5.
Return obj negated (-obj).
Return the bitwise or of a and b.
Return obj positive (+obj).
Return a ** b, for a and b numbers.
Return a shifted right by b.
Return a - b.
Return a / b where 2/3 is .66 rather than 0. This is also known as “true” division.
Return the bitwise exclusive or of a and b.
Operations which work with sequences (some of them with mappings too) include:
Return a + b for a and b sequences.
Return the outcome of the test b in a. Note the reversed operands.
Return the number of occurrences of b in a.
Remove the value of a at index b.
Return the value of a at index b.
Return the index of the first of occurrence of b in a.
Set the value of a at index b to c.
Return an estimated length for the object o. First try to return its actual length, then an estimate using object.__length_hint__(), and finally return the default value.
New in version 3.4.
The operator module also defines tools for generalized attribute and item lookups. These are useful for making fast field extractors as arguments for map(), sorted(), itertools.groupby(), or other functions that expect a function argument.
Return a callable object that fetches attr from its operand. If more than one attribute is requested, returns a tuple of attributes. The attribute names can also contain dots. For example:
Equivalent to:
Return a callable object that fetches item from its operand using the operand’s __getitem__() method. If multiple items are specified, returns a tuple of lookup values. For example:
Equivalent to:
The items can be any type accepted by the operand’s __getitem__() method. Dictionaries accept any hashable value. Lists, tuples, and strings accept an index or a slice:
Example of using itemgetter() to retrieve specific fields from a tuple record:
Return a callable object that calls the method name on its operand. If additional arguments and/or keyword arguments are given, they will be given to the method as well. For example:
Equivalent to:
This table shows how abstract operations correspond to operator symbols in the Python syntax and the functions in the operator module.
Operation
Syntax
Function
Addition
a + b
add(a, b)
Concatenation
seq1 + seq2
concat(seq1, seq2)
Containment Test
obj in seq
contains(seq, obj)
Division
a / b
truediv(a, b)
Division
a // b
floordiv(a, b)
Bitwise And
a & b
and_(a, b)
Bitwise Exclusive Or
a ^ b
xor(a, b)
Bitwise Inversion
~ a
invert(a)
Bitwise Or
a | b
or_(a, b)
Exponentiation
a ** b
pow(a, b)
Identity
a is b
is_(a, b)
Identity
a is not b
is_not(a, b)
Indexed Assignment
obj[k] = v
setitem(obj, k, v)
Indexed Deletion
del obj[k]
delitem(obj, k)
Indexing
obj[k]
getitem(obj, k)
Left Shift
a << b
lshift(a, b)
Modulo
a % b
mod(a, b)
Multiplication
a * b
mul(a, b)
Matrix Multiplication
a @ b
matmul(a, b)
Negation (Arithmetic)
- a
neg(a)
Negation (Logical)
not a
not_(a)
Positive
+ a
pos(a)
Right Shift
a >> b
rshift(a, b)
Slice Assignment
seq[i:j] = values
setitem(seq, slice(i, j), values)
Slice Deletion
del seq[i:j]
delitem(seq, slice(i, j))
Slicing
seq[i:j]
getitem(seq, slice(i, j))
String Formatting
s % obj
mod(s, obj)
Subtraction
a - b
sub(a, b)
Truth Test
obj
truth(obj)
Ordering
a < b
lt(a, b)
Ordering
a <= b
le(a, b)
Equality
a == b
eq(a, b)
Difference
a != b
ne(a, b)
Ordering
a >= b
ge(a, b)
Ordering
a > b
gt(a, b)
Many operations have an “in-place” version. Listed below are functions providing a more primitive access to in-place operators than the usual syntax does; for example, the statement x += y is equivalent to x = operator.iadd(x, y). Another way to put it is to say that z = operator.iadd(x, y) is equivalent to the compound statement z = x; z += y.
In those examples, note that when an in-place method is called, the computation and assignment are performed in two separate steps. The in-place functions listed below only do the first step, calling the in-place method. The second step, assignment, is not handled.
For immutable targets such as strings, numbers, and tuples, the updated value is computed, but not assigned back to the input variable:
For mutable targets such as lists and dictionaries, the in-place method will perform the update, so no subsequent assignment is necessary:
a = iadd(a, b) is equivalent to a += b.
a = iand(a, b) is equivalent to a &= b.
a = iconcat(a, b) is equivalent to a += b for a and b sequences.
a = ifloordiv(a, b) is equivalent to a //= b.
a = ilshift(a, b) is equivalent to a <<= b.
a = imod(a, b) is equivalent to a %= b.
a = imul(a, b) is equivalent to a *= b.
a = imatmul(a, b) is equivalent to a @= b.
New in version 3.5.
a = ior(a, b) is equivalent to a |= b.
a = ipow(a, b) is equivalent to a **= b.
a = irshift(a, b) is equivalent to a >>= b.
a = isub(a, b) is equivalent to a -= b.
a = itruediv(a, b) is equivalent to a /= b.
a = ixor(a, b) is equivalent to a ^= b.


Return a callable object that fetches attr from its operand. If more than one attribute is requested, returns a tuple of attributes. The attribute names can also contain dots. For example:
Equivalent to:


Return the outcome of the test b in a. Note the reversed operands.


Return the number of occurrences of b in a.


Perform “rich comparisons” between a and b. Specifically, lt(a, b) is equivalent to a < b, le(a, b) is equivalent to a <= b, eq(a,
b) is equivalent to a == b, ne(a, b) is equivalent to a != b, gt(a, b) is equivalent to a > b and ge(a, b) is equivalent to a
>= b. Note that these functions can return any value, which may or may not be interpretable as a Boolean value. See Comparisons for more information about rich comparisons.


a = iconcat(a, b) is equivalent to a += b for a and b sequences.


a = ifloordiv(a, b) is equivalent to a //= b.


a = ilshift(a, b) is equivalent to a <<= b.


a = imatmul(a, b) is equivalent to a @= b.
New in version 3.5.


Return a converted to an integer. Equivalent to a.__index__().


Return the index of the first of occurrence of b in a.


Return the bitwise inverse of the number obj. This is equivalent to ~obj.


a = ipow(a, b) is equivalent to a **= b.


a = irshift(a, b) is equivalent to a >>= b.


Return a is not b. Tests object identity.


Return a callable object that fetches item from its operand using the operand’s __getitem__() method. If multiple items are specified, returns a tuple of lookup values. For example:
Equivalent to:
The items can be any type accepted by the operand’s __getitem__() method. Dictionaries accept any hashable value. Lists, tuples, and strings accept an index or a slice:
Example of using itemgetter() to retrieve specific fields from a tuple record:


a = itruediv(a, b) is equivalent to a /= b.


Return an estimated length for the object o. First try to return its actual length, then an estimate using object.__length_hint__(), and finally return the default value.
New in version 3.4.


Return a callable object that calls the method name on its operand. If additional arguments and/or keyword arguments are given, they will be given to the method as well. For example:
Equivalent to:


Return the outcome of not obj. (Note that there is no __not__() method for object instances; only the interpreter core defines this operation. The result is affected by the __bool__() and __len__() methods.)


Return a / b where 2/3 is .66 rather than 0. This is also known as “true” division.


Return True if obj is true, and False otherwise. This is equivalent to using the bool constructor.


Return the bitwise exclusive or of a and b.


Return the outcome of the test b in a. Note the reversed operands.


Perform “rich comparisons” between a and b. Specifically, lt(a, b) is equivalent to a < b, le(a, b) is equivalent to a <= b, eq(a,
b) is equivalent to a == b, ne(a, b) is equivalent to a != b, gt(a, b) is equivalent to a > b and ge(a, b) is equivalent to a
>= b. Note that these functions can return any value, which may or may not be interpretable as a Boolean value. See Comparisons for more information about rich comparisons.


a = iconcat(a, b) is equivalent to a += b for a and b sequences.


a = ifloordiv(a, b) is equivalent to a //= b.


a = ilshift(a, b) is equivalent to a <<= b.


a = imatmul(a, b) is equivalent to a @= b.
New in version 3.5.


Return a converted to an integer. Equivalent to a.__index__().


Return the bitwise inverse of the number obj. This is equivalent to ~obj.


a = ipow(a, b) is equivalent to a **= b.


a = irshift(a, b) is equivalent to a >>= b.


a = itruediv(a, b) is equivalent to a /= b.


Given a string representing one Unicode character, return an integer representing the Unicode code point of that character. For example, ord('a') returns the integer 97 and ord('€') (Euro sign) returns 8364. This is the inverse of chr().