o
SbP @ s d Z ddlmZ ddlmZmZmZmZmZ ddl m
Z
ddl m Z ddl
mZmZ dZdZdZd Zd
Zd Zd d
Zdd Zdd Zdd Zeeef Zeeeef Z G dd de Z G dd de Z G dd de Z G dd de Z!G d d d e Z"G d d d e Z#G d d! d!Z$e e e!e"e#fZ% "d2d#e&d$ee d%e&d&e fd'd(Z'd)Z(G d*d+ d+e Z)d,ed&e&fd-d.Z*G d/d0 d0e Z+d1S )3zBUtilities for choosing which member of a replica set to read from. )abc)AnyDictMappingOptionalSequence)max_staleness_selectors)ConfigurationError) member_with_tags_server_selector#secondary_with_tags_server_selector )primaryZprimaryPreferredZ secondaryZsecondaryPreferredZnearestc C sn | du r| S t | ttfstd| f t| dkr!td| f | D ]}t |tjs2td|f q#t| S )z$Validate tag sets for a MongoClient.Nz'Tag sets %r invalid, must be a sequencer zETag sets %r invalid, must be None or contain at least one set of tagszqTag set %r invalid, must be an instance of dict, bson.son.SON or other type that inherits from collection.Mapping)
isinstancelisttuple TypeErrorlen
ValueErrorr r )tag_setstags r ?/tmp/pip-target-onvjaxws/lib/python/pymongo/read_preferences.py_validate_tag_sets+ s" r c C s d| S )Nz6maxStalenessSeconds must be a positive integer, not %sr
max_stalenessr r r _invalid_max_staleness_msgB s r c C s: | dkrdS t | tstt| | dkrtt| | S )zValidate max_staleness.r )r intr r r r r r r _validate_max_stalenessG s
r! c C s( | du rdS t | tstd| f | S )zValidate hedge.Nz"hedge must be a dictionary, not %r)r dictr )hedger r r _validate_hedgeU s
r$ c @ s e Zd ZdZdZ d'dedee dedee d df
d
d Z e
d e fd d
Z e
d e fddZ
e
d ee ef fddZe
d efddZe
d efddZe
d efddZe
d ee fddZe
d efddZd d Zd ed efd d Zd ed efd!d"Zd#d$ Zd%d& ZdS )( _ServerModez$Base class for all read preferences.)Z
__mongos_modeZ__modeZ
__tag_setsZ__max_stalenessZ__hedgeNr moder r r# returnc C s2 t | | _|| _t|| _t|| _t|| _d S N)
_MONGOS_MODES_ServerMode__mongos_mode_ServerMode__moder _ServerMode__tag_setsr! _ServerMode__max_stalenessr$ _ServerMode__hedge)selfr& r r r# r r r __init__i s
z_ServerMode.__init__c C s | j jS )z!The name of this read preference.) __class____name__r/ r r r namev s z_ServerMode.namec C | j S )z(The mongos mode of this read preference.)r* r3 r r r mongos_mode{ z_ServerMode.mongos_modec C sT d| j i}| jdi gfvr| j|d< | jdkr | j|d< | jdi fvr(| j|d< |S )z Read preference as a document.r& Nr r ZmaxStalenessSecondsr# )r* r, r- r. )r/ docr r r document s
z_ServerMode.documentc C r5 )z*The mode of this read preference instance.)r+ r3 r r r r& r7 z_ServerMode.modec C s | j rt| j S i gS )ar Set ``tag_sets`` to a list of dictionaries like [{'dc': 'ny'}] to
read only from members whose ``dc`` tag has the value ``"ny"``.
To specify a priority-order for tag sets, provide a list of
tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag
set, ``{}``, means "read from any member that matches the mode,
ignoring tags." MongoClient tries each set of tags in turn
until it finds a set of tags with at least one matching member.
.. seealso:: `Data-Center Awareness
`_
)r, r r3 r r r r s
z_ServerMode.tag_setsc C r5 )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.r- r3 r r r r s z_ServerMode.max_stalenessc C r5 )a The 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
)r. r3 r r r r# s z_ServerMode.hedgec C s | j dkrdS dS )a The 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 r r: r3 r r r min_wire_version s z _ServerMode.min_wire_versionc C s d| j | j| j| jf S )Nz+%s(tag_sets=%r, max_staleness=%r, hedge=%r))r4 r, r- r. r3 r r r __repr__ s z_ServerMode.__repr__otherc C s> t |tr | j|jko | j|jko | j|jko | j|jkS tS r( )r r% r& r r r# NotImplementedr/ r> r r r __eq__ s
z_ServerMode.__eq__c C s
| |k S r( r r@ r r r __ne__
z_ServerMode.__ne__c C s | j | j| j| jdS )zeReturn value of object for pickling.
Needed explicitly because __slots__() defined.
)r& r r r# )r+ r, r- r. r3 r r r __getstate__ s
z_ServerMode.__getstate__c C sD |d | _ t| j | _t|d | _t|d | _t|d | _dS )zRestore from pickling.r& r r r# N) r+ r) r* r r, r! r- r$ r. )r/ valuer r r __setstate__ s
z_ServerMode.__setstate__Nr N) r2
__module__ __qualname____doc__ __slots__r r _TagSets_Hedger0 propertystrr4 r6 r r r9 r& r r r# r< r= boolrA rB rD rF r r r r r% d sL
r% c sR e Zd ZdZdZd fdd Zdedefdd Zd
d Zd ede fd
dZ
Z S )PrimaryaG Primary 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' Nc s t t| t d S r( )superrQ r0 _PRIMARYr3 r1 r r r0 s zPrimary.__init__ selectionc C s |j S z*Apply this read preference to a Selection.)primary_selectionr/ rU r r r __call__ zPrimary.__call__c C s dS )Nz Primary()r r3 r r r r= s zPrimary.__repr__r> c C s t |tr
|jtkS tS r( )r r% r& rS r? r@ r r r rA s
zPrimary.__eq__r' N) r2 rH rI rJ rK r0 r rY r= rP rA
__classcell__r r rT r rQ s rQ c X e Zd ZdZdZ ddee dedee ddf fd d
Z d e
de
fd d
Z Z S )PrimaryPreferreda PrimaryPreferred 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 r r r# r' c t t| t||| d S r( )rR r^ r0 _PRIMARY_PREFERREDr/ r r r# rT r r r0 0 zPrimaryPreferred.__init__rU c C s" |j r|jS t| jt| j|S z(Apply this read preference to Selection.)r rW r r r selectr rX r r r rY 8 s
zPrimaryPreferred.__call__rG
r2 rH rI rJ rK r rL r rM r0 r rY r\ r r rT r r^ s r^ c r] ) Secondarya Secondary 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 r r r# r' c r_ r( )rR rf r0
_SECONDARYra rT r r r0 [ rb zSecondary.__init__rU c C t | jt| j|S rc )r r r rd r rX r r r rY c zSecondary.__call__rG re r r rT r rf B rf c r] )SecondaryPreferreda SecondaryPreferred 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 r r r# r' c r_ r( )rR rk r0 _SECONDARY_PREFERREDra rT r r r0 s
zSecondaryPreferred.__init__rU c C s$ t | jt| j|}|r|S |jS rc )r r r rd r rW )r/ rU Z secondariesr r r rY s zSecondaryPreferred.__call__rG re r r rT r rk j s
rk c r] )Nearestav Nearest 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 r r r# r' c r_ r( )rR rm r0 _NEARESTra rT r r r0 rb zNearest.__init__rU c C rh rc )r
r r rd r rX r r r rY ri zNearest.__call__rG re r r rT r rm rj rm c @ s< e Zd ZdZdZdd Zdd Zdd Zd d
Zd d Z d
S )
_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_prefc C s || _ tj| _d S r( )rp ReadPreferencePRIMARYrq )r/ rp r r r r0 s z_AggWritePref.__init__c C s6 |j }|tjr|r|dk rtj| _d S | j| _d S )N
)Zcommon_wire_versionZhas_readable_serverrr PRIMARY_PREFERREDrs rq rp )r/ Ztopology_descriptionZ common_wvr r r selection_hook s
z _AggWritePref.selection_hookc C s
| |S rV )rq rX r r r rY
z_AggWritePref.__call__c C s d| j f S )Nz_AggWritePref(pref=%r))rp r3 r r r r= z_AggWritePref.__repr__c C s t | j|S r( )getattrrq )r/ r4 r r r __getattr__ rx z_AggWritePref.__getattr__N)
r2 rH rI rJ rK r0 rv rY r= rz r r r r ro s
ro r r& r r r' c C sB | t kr|d i gfvrtd|dkrtdt S t| ||S )Nz4Read preference primary cannot be combined with tagsr zCRead preference primary cannot be combined with maxStalenessSeconds)rS r rQ _ALL_READ_PREFERENCES)r& r r r r r make_read_preference s r| )rs ru SECONDARYSECONDARY_PREFERREDNEARESTc @ s. e Zd ZdZe Ze Ze Z e
Z e Z
dS )rr aD An enum that defines the read preference modes supported by PyMongo.
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)r2 rH rI rJ rQ rs r^ ru rf r} rk r~ rm r r r r r rr s 2
rr r4 c C s
t | S )z2Get the read preference mode from mongos/uri name.)r) index)r4 r r r read_pref_mode_from_nameB rw r c @ sV e Zd ZU dZee ed< dddZdeddfdd Zdee fd
d Z dd d
Z
dS )
MovingAveragez0Tracks an exponentially-weighted moving average.averager' Nc C
d | _ d S r( r r3 r r r r0 L rC zMovingAverage.__init__samplec C s8 |dk rd S | j d u r|| _ d S d| j d| | _ d S )Nr g?g?r )r/ r r r r
add_sampleO s
zMovingAverage.add_samplec C r5 )z6Get the calculated average, or None if no samples yet.r r3 r r r get\ rZ zMovingAverage.getc C r r( r r3 r r r reset` rC zMovingAverage.resetr[ ) r2 rH rI rJ r float__annotations__r0 r r r r r r r r G s
r N)r ),rJ collectionsr typingr r r r r Zpymongor Zpymongo.errorsr Zpymongo.server_selectorsr
r rS r` rg rl rn r) r r r! r$ rO rM rL objectr% rQ r^ rf rk rm ro r{ r r| Z_MODESrr r r r r r r sR 0(3()
: