U dS@sdZddlmZddlmZddlmZmZmZm Z m Z m Z ddl m Z ddlmZddlmZmZerddlmZdd lmZdZd Zd Zd Zd ZdZe eefZe e eefZdddddZdddddZ dddddZ!dddddZ"Gdd d Z#Gd!d"d"e#Z$Gd#d$d$e#Z%Gd%d&d&e#Z&Gd'd(d(e#Z'Gd)d*d*e#Z(Gd+d,d,Z)e$e%e&e'e(fZ*d:dddd d.d/d0Z+d1Z,Gd2d3d3Z-ddd4d5d6Z.Gd7d8d8Z/d9S);zBUtilities for choosing which member of a replica set to read from.) annotations)abc) TYPE_CHECKINGAnyDictMappingOptionalSequence)max_staleness_selectors)ConfigurationError) member_with_tags_server_selector#secondary_with_tags_server_selector) Selection)TopologyDescription)primaryZprimaryPreferredZ secondaryZsecondaryPreferredZnearestOptional[_TagSets])tag_setsreturncCsr|dkr |St|ttfs*td|dt|dkrFtd|d|D]}t|tjsJtd|qJt|S)z$Validate tag sets for a MongoClient.Nz Tag sets z invalid, must be a sequencerz: invalid, must be None or contain at least one set of tagszsTag set {!r} invalid, must be an instance of dict, bson.son.SON or other type that inherits from collection.Mapping) isinstancelisttuple TypeErrorlen ValueErrorrrformat)rtagsr `_ )r5rr=r r r!rsz_ServerMode.tag_setscCs|jS)zThe maximum estimated length of time (in seconds) a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations, or -1 for no maximum. r6r=r r r!r$sz_ServerMode.max_stalenesscCs|jS)aThe read preference ``hedge`` parameter. A dictionary that configures how the server will perform hedged reads. It consists of the following keys: - ``enabled``: Enables or disables hedged reads in sharded clusters. Hedged reads are automatically enabled in MongoDB 4.4+ when using a ``nearest`` read preference. To explicitly enable hedged reads, set the ``enabled`` key to ``true``:: >>> Nearest(hedge={'enabled': True}) To explicitly disable hedged reads, set the ``enabled`` key to ``False``:: >>> Nearest(hedge={'enabled': False}) .. versionadded:: 3.11 )r7r=r r r!r+sz_ServerMode.hedgecCs|jdkrdSdS)aThe wire protocol version the server must support. Some read preferences impose version requirements on all servers (e.g. maxStalenessSeconds requires MongoDB 3.4 / maxWireVersion 5). All servers' maxWireVersion must be at least this read preference's `min_wire_version`, or the driver raises :exc:`~pymongo.errors.ConfigurationError`. r(rrCr=r r r!min_wire_versions z_ServerMode.min_wire_versioncCsd|j|j|j|jS)Nz1{}(tag_sets={!r}, max_staleness={!r}, hedge={!r}))rr>r5r6r7r=r r r!__repr__s z_ServerMode.__repr__rboolotherrcCs>t|tr:|j|jko8|j|jko8|j|jko8|j|jkStSr1)rr.r0rr$r+NotImplementedr8rIr r r!__eq__s     z_ServerMode.__eq__cCs ||k Sr1r rKr r r!__ne__sz_ServerMode.__ne__cCs|j|j|j|jdS)zeReturn value of object for pickling. Needed explicitly because __slots__() defined. )r0rr$r+)r4r5r6r7r=r r r! __getstate__s z_ServerMode.__getstate__zMapping[str, Any])valuercCsD|d|_t|j|_t|d|_t|d|_t|d|_dS)zRestore from pickling.r0rr$r+N) r4r2r3r"r5r)r6r-r7)r8rOr r r! __setstate__s   z_ServerMode.__setstate__r selectionrcCs|Sr1r r8rRr r r!__call__sz_ServerMode.__call__)Nr(N)r< __module__ __qualname____doc__ __slots__r9propertyr>r?rAr0rr$r+rErFrLrMrNrPrTr r r r!r.is8     r.csXeZdZdZdZddfdd Zdddd d Zd dd d ZdddddZZ S)PrimaryaGPrimary read preference. * When directly connected to one mongod queries are allowed if the server is standalone or a replica set primary. * When connected to a mongos queries are sent to the primary of a shard. * When connected to a replica set queries are sent to the primary of the replica set. r r/r:csttdSr1)superr9_PRIMARYr=r;r r!r9szPrimary.__init__rrQcCs|jSz*Apply this read preference to a Selection.)primary_selectionrSr r r!rTszPrimary.__call__r#cCsdS)Nz Primary()r r=r r r!rFszPrimary.__repr__rrGrHcCst|tr|jtkStSr1)rr.r0r\rJrKr r r!rLs  zPrimary.__eq__) r<rUrVrWrXr9rTrFrL __classcell__r r r]r!rZs  rZcsBeZdZdZdZdddddd fd d Zd d d ddZZS)PrimaryPreferredaPrimaryPreferred read preference. * When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries. * When connected to a mongos queries are sent to the primary of a shard if available, otherwise a shard secondary. * When connected to a replica set queries are sent to the primary if available, otherwise a secondary. .. note:: When a :class:`~pymongo.mongo_client.MongoClient` is first created reads will be routed to an available secondary until the primary of the replica set is discovered. :Parameters: - `tag_sets`: The :attr:`~tag_sets` to use if the primary is not available. - `max_staleness`: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds. - `hedge`: The :attr:`~hedge` to use if the primary is not available. .. versionchanged:: 3.11 Added ``hedge`` parameter. r Nr(rr'r*r/rr$r+rcstt|||dSr1)r[r9_PRIMARY_PREFERREDr8rr$r+r]r r!r9@szPrimaryPreferred.__init__rrQcCs&|jr |jSt|jt|j|SdS(Apply this read preference to Selection.N)rr_r rr selectr$rSr r r!rTHs  zPrimaryPreferred.__call__)Nr(Nr<rUrVrWrXr9rTr`r r r]r!ra"sracsBeZdZdZdZdddddd fd d Zd d d ddZZS) SecondaryaSecondary read preference. * When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries. * When connected to a mongos queries are distributed among shard secondaries. An error is raised if no secondaries are available. * When connected to a replica set queries are distributed among secondaries. An error is raised if no secondaries are available. :Parameters: - `tag_sets`: The :attr:`~tag_sets` for this read preference. - `max_staleness`: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds. - `hedge`: The :attr:`~hedge` for this read preference. .. versionchanged:: 3.11 Added ``hedge`` parameter. r Nr(rr'r*r/rbcstt|||dSr1)r[r9 _SECONDARYrdr]r r!r9kszSecondary.__init__rrQcCst|jt|j|Srf)r rr rgr$rSr r r!rTss zSecondary.__call__)Nr(Nrhr r r]r!riRsricsBeZdZdZdZdddddd fd d Zd d d ddZZS)SecondaryPreferredaSecondaryPreferred read preference. * When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries. * When connected to a mongos queries are distributed among shard secondaries, or the shard primary if no secondary is available. * When connected to a replica set queries are distributed among secondaries, or the primary if no secondary is available. .. note:: When a :class:`~pymongo.mongo_client.MongoClient` is first created reads will be routed to the primary of the replica set until an available secondary is discovered. :Parameters: - `tag_sets`: The :attr:`~tag_sets` for this read preference. - `max_staleness`: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds. - `hedge`: The :attr:`~hedge` for this read preference. .. versionchanged:: 3.11 Added ``hedge`` parameter. r Nr(rr'r*r/rbcstt|||dSr1)r[r9_SECONDARY_PREFERREDrdr]r r!r9szSecondaryPreferred.__init__rrQcCs(t|jt|j|}|r|S|jSdSre)r rr rgr$r_)r8rRZ secondariesr r r!rTs zSecondaryPreferred.__call__)Nr(Nrhr r r]r!rlzsrlcsBeZdZdZdZdddddd fd d Zd d d ddZZS)NearestavNearest read preference. * When directly connected to one mongod queries are allowed to standalone servers, to a replica set primary, or to replica set secondaries. * When connected to a mongos queries are distributed among all members of a shard. * When connected to a replica set queries are distributed among all members. :Parameters: - `tag_sets`: The :attr:`~tag_sets` for this read preference. - `max_staleness`: (integer, in seconds) The maximum estimated length of time a replica set secondary can fall behind the primary in replication before it will no longer be selected for operations. Default -1, meaning no maximum. If it is set, it must be at least 90 seconds. - `hedge`: The :attr:`~hedge` for this read preference. .. versionchanged:: 3.11 Added ``hedge`` parameter. r Nr(rr'r*r/rbcstt|||dSr1)r[r9_NEARESTrdr]r r!r9szNearest.__init__rrQcCst|jt|j|Srk)r rr rgr$rSr r r!rTs zNearest.__call__)Nr(Nrhr r r]r!rnsrnc@s`eZdZdZdZddddZddd d d Zd d d ddZddddZdddddZ dS) _AggWritePrefa Agg $out/$merge write preference. * If there are readable servers and there is any pre-5.0 server, use primary read preference. * Otherwise use `pref` read preference. :Parameters: - `pref`: The read preference to use on MongoDB 5.0+. )prefeffective_prefr.rqcCs||_tj|_dSr1)rqReadPreferencePRIMARYrr)r8rqr r r!r9sz_AggWritePref.__init__rr/)topology_descriptionrcCs4|j}|tjr(|r(|dkr(tj|_n|j|_dS)N )Zcommon_wire_versionZhas_readable_serverrtPRIMARY_PREFERREDrurrrq)r8rvZ common_wvr r r!selection_hooks  z_AggWritePref.selection_hookrrQcCs ||Sr^)rrrSr r r!rTsz_AggWritePref.__call__r#r:cCsd|jdS)Nz_AggWritePref(pref=)rsr=r r r!rFsz_AggWritePref.__repr__rr>rcCs t|j|Sr1)getattrrr)r8r>r r r! __getattr__sz_AggWritePref.__getattr__N) r<rUrVrWrXr9ryrTrFr}r r r r!rps  rpr()r0rr$rcCsB|tkr4|digfkrtd|dkr.tdtSt|||S)Nz4Read preference primary cannot be combined with tagsr(zCRead preference primary cannot be combined with maxStalenessSeconds)r\r rZ_ALL_READ_PREFERENCES)r0rr$r r r!make_read_preferencesr)rurx SECONDARYSECONDARY_PREFERREDNEARESTc@s.eZdZdZeZeZeZ e Z e Z dS)rtaAn enum that defines some commonly used read preference modes. Apps can also create a custom read preference, for example:: Nearest(tag_sets=[{"node":"analytics"}]) See :doc:`/examples/high_availability` for code examples. A read preference is used in three cases: :class:`~pymongo.mongo_client.MongoClient` connected to a single mongod: - ``PRIMARY``: Queries are allowed if the server is standalone or a replica set primary. - All other modes allow queries to standalone servers, to a replica set primary, or to replica set secondaries. :class:`~pymongo.mongo_client.MongoClient` initialized with the ``replicaSet`` option: - ``PRIMARY``: Read from the primary. This is the default, and provides the strongest consistency. If no primary is available, raise :class:`~pymongo.errors.AutoReconnect`. - ``PRIMARY_PREFERRED``: Read from the primary if available, or if there is none, read from a secondary. - ``SECONDARY``: Read from a secondary. If no secondary is available, raise :class:`~pymongo.errors.AutoReconnect`. - ``SECONDARY_PREFERRED``: Read from a secondary if available, otherwise from the primary. - ``NEAREST``: Read from any member. :class:`~pymongo.mongo_client.MongoClient` connected to a mongos, with a sharded cluster of replica sets: - ``PRIMARY``: Read from the primary of the shard, or raise :class:`~pymongo.errors.OperationFailure` if there is none. This is the default. - ``PRIMARY_PREFERRED``: Read from the primary of the shard, or if there is none, read from a secondary of the shard. - ``SECONDARY``: Read from a secondary of the shard, or raise :class:`~pymongo.errors.OperationFailure` if there is none. - ``SECONDARY_PREFERRED``: Read from a secondary of the shard if available, otherwise from the shard primary. - ``NEAREST``: Read from any shard member. N)r<rUrVrWrZrurarxrirrlrrnrr r r r!rts 6rtr{cCs t|S)z2Get the read preference mode from mongos/uri name.)r2index)r>r r r!read_pref_mode_from_nameTsrc@sTeZdZUdZded<ddddZddd d d Zddd d ZddddZdS) MovingAveragez0Tracks an exponentially-weighted moving average.zOptional[float]averager/r:cCs d|_dSr1rr=r r r!r9^szMovingAverage.__init__float)samplercCs6|dkr dS|jdkr||_nd|jd||_dS)Nrg?g?r)r8rr r r! add_sampleas  zMovingAverage.add_samplecCs|jS)z6Get the calculated average, or None if no samples yet.rr=r r r!getnszMovingAverage.getcCs d|_dSr1rr=r r r!resetrszMovingAverage.resetN) r<rUrVrW__annotations__r9rrrr r r r!rYs  rN)r()0rW __future__r collectionsrtypingrrrrrr Zpymongor Zpymongo.errorsr Zpymongo.server_selectorsr r rZpymongo.topology_descriptionrr\rcrjrmror2r#Z_HedgerBr"r&r)r-r.rZrarirlrnrpr~rZ_MODESrtrrr r r r!sH         0(1() >