pymongo 3.0 presents a major API departure (possibly for the better) from 2.8.

Unfortunately transitioning a large code-base is hard because the API breakage means code will work against the 2.x driver or the 3.x driver, but not both. 2.x is currently incompatible with 3.x which makes it difficult to incrementally transition a large code-base.

A handful of the issues I've encountered in a small part of our codebase:

• find parameters renamed: spec and fields
• find_and_modify now rejects read_preference=PRIMARY
• aggregate() return value default changed (now always returns a CommandCursor)
• disconnect() removed (without being deprecated)
• rewriting code not to use start_request and friends
• max_pool_size renamed maxPoolSize not bwds compatible
• read_preference write_preference read-only
• son_manipulator broken
• tailable removed

None of these are insurmountable. However they're fairly fundamental. Nearly 25 commits later and my code still doesn't work...

The changelog is helpful:
http://api.mongodb.org/python/current/changelog.html

However the changes are so wide-ranging I don't see how it's possible to transition from a large code-base from 2.x to 3.x without suffering days of breakage.

Ideally 2.x would be forward compatible, or 3.x would be more backwards compatible (+ less arbitrarily API broken).

Currently the two versions are so far apart, I'd say it's nearly impossible to port an existing code base to the new driver.