A bit of history is required to explain this ticket. The Java, .net, and Python drivers all support language native UUID types. Each driver provides support for serializing these types to BSON binary, originally subtype 3. Sadly the original implementations were all incompatible. The .net driver stored UUIDs in Microsoft's GUID byte order (UUID.bytes_le in python), PyMongo used RFC-4122 byte order (UUID.bytes in python), and the Java driver stored the bytes in network byte order.

To solve this problem a new BSON binary subtype was added, subtype 4. A URI syntax was devised to specify which format you wanted to use (standard, pythonLegacy, javaLegacy, csharpLegacy). At the time the python driver added a uuid_subtype attribute to Connection (now MongoClient), Database, and Collection, and a uuid_subtype parameter to various methods and functions.

The name uuid_subtype is very misleading. The attribute/parameter does not determine the subtype used in bson.binary.Binary instances, but the byte order the binary data should be stored in along with the subtype. To solve this confusion uuid_subtype will be renamed uuid_representation to match the URI option. STANDARD and PYTHON_LEGACY constants will also be added to bson.binary, set to UUID_SUBTYPE and OLD_UUID_SUBTYPE respectively.

This is a breaking change for any applications that are using this option by passing uuid_subtype=<int> to various functions or methods in PyMongo's API.