homepage

Pickle documentation [1] says:
""" Note: If __getstate__() returns a false value, the __setstate__() method will not be called upon unpickling. """
However, this isn't quite true. This depends on the version of pickle protocol. A small example:
>>> class Pockle(object):
	def __getstate__(self):
		return 0
	def __setstate__(self, state):
		sys.stdout.write('__setstate__ is called!\n')
>>> for p in range(4):
	sys.stdout.write('protocol %d: ' % p)
	pickle.loads(pickle.dumps(Pockle(), p))
protocol 0: <__main__.Pockle object at 0x0000000002EAE3C8>
protocol 1: <__main__.Pockle object at 0x0000000002EAE358>
protocol 2: __setstate__ is called!
<__main__.Pockle object at 0x0000000002EAE3C8>
protocol 3: __setstate__ is called!
<__main__.Pockle object at 0x0000000002EAE358>
So for protocols >= 2 setstate is called. This is caused by object.__reduce_ex__ returning different tuples for different protocol versions:
>>> for p in range(4):
	sys.stdout.write('protocol %d: %s\n' % (p, Pockle().__reduce_ex__(p)))
	
protocol 0: (<function _reconstructor at 0x0000000001F03048>, (<class '__main__.Pockle'>, <class 'object'>, None))
protocol 1: (<function _reconstructor at 0x0000000001F03048>, (<class '__main__.Pockle'>, <class 'object'>, None))
protocol 2: (<function __newobj__ at 0x0000000001F03148>, (<class '__main__.Pockle'>,), 0, None, None)
protocol 3: (<function __newobj__ at 0x0000000001F03148>, (<class '__main__.Pockle'>,), 0, None, None)
Implementation of reduce_ex for protos 0-1 in copy_reg.py contains the documented check: http://hg.python.org/cpython/file/f1509fc75435/Lib/copy_reg.py#l85
Implementation for proto 2+ in typeobject.c is happy with any value: http://hg.python.org/cpython/file/f1509fc75435/Objects/typeobject.c#l3205
Pickle itself only ignores None, not any false value: http://hg.python.org/cpython/file/f1509fc75435/Lib/pickle.py#l418
I think this is a documentation issue at this point.
[1] http://docs.python.org/py3k/library/pickle.html#pickle.object.__setstate__ 

See also #6827, just for some background on the current docs.

So how about this correction?

Well, this looks correct then.

Actually this wording is not quite correct. __setstate__() is called for any pickled state. It is not called only if the state is not pickled. The state is not pickled if reducing method (__reduce_ex__ or __reduce__) doesn't return state or returns None as a state. Default reducing method for protocol 0 and 1 doesn't return a state if __getstate__() returns false value.
There are many other details of pickle protocol that are not correctly documented in the documentation of the pickle module. PEP 307 documents pickle protocol more correctly.

See also issue26695.