K:g_vddlZddlZddlZddlmZddlmZddlmZmZm Z m Z m Z m Z m Z mZmZmZmZmZddlmZddlmZddlmZmZddlmZdd lmZdd lm Z m!Z!m"Z"m#Z#m$Z$dd l%m&Z&m'Z'm(Z(dd l)m*Z*dd l+m,Z,m-Z-ddl.m/Z/m0Z0erddl1m2Z2GddZ3eGddZ4edGddZ5y)N) dataclass)cached_property) TYPE_CHECKINGAnyClassVarDictIterableListMappingOptionalSetTypeUnioncast)Self)retrying)Api TimeoutTuple)Base)Table) FieldName RecordDictRecordIdUpdateRecordDictWritableFields)EQOR RECORD_ID)Comment)AnyFieldField)datetime_from_iso_strdatetime_to_iso_str) _ClassInfoc eZdZUdZdZeed<dZee jed<e ded<dZ e ed <dZ e ed <eeefed <eee fed <e eeefed <deffd Zed5dZedeeeffdZedeeeffdZdefdZdefdZde fdZddde ddfdZde fdZedddee dedeefdZedddee dedeefd Z ed!edee ddfd"Z!d6d#e de"fd$Z#eddd%e"dee defd&Z$ed'dd(d)ed*e dee defd+Z%d5d,Z&ed'dd(d-e'ed*e dee deefd.Z(ed/eeddfd0Z)ed/eeddfd1Z*dee+fd2Z,d3ede+fd4Z-xZ.S)7Modela Supports creating ORM-style classes representing Airtable tables. For more details, see :ref:`orm`. A nested class or dict called ``Meta`` is required and can specify the following attributes: * ``api_key`` (required) - API key or personal access token. * ``base_id`` (required) - Base ID (not name). * ``table_name`` (required) - Table ID or name. * ``timeout`` - A tuple indicating a connect and read timeout. Defaults to no timeout. * ``typecast`` - |kwarg_typecast| Defaults to ``True``. * ``retry`` - An instance of `urllib3.util.Retry `_. If ``None`` or ``False``, requests will not be retried. If ``True``, the default strategy will be applied (see :func:`~pyairtable.retry_strategy` for details). * ``use_field_ids`` - Whether fields will be defined by ID, rather than name. Defaults to ``False``. * ``memoize`` - Whether the model should reuse models it creates between requests. See :ref:`Memoizing linked records` for more information. For example, the following two are equivalent: .. code-block:: python from pyairtable.orm import Model, fields class Contact(Model): class Meta: base_id = "appaPqizdsNHDvlEm" table_name = "Contact" api_key = "keyapikey" timeout = (5, 5) typecast = True first_name = fields.TextField("First Name") age = fields.IntegerField("Age") .. code-block:: python from pyairtable.orm import Model, fields class Contact(Model): Meta = { "base_id": "appaPqizdsNHDvlEm", "table_name": "Contact", "api_key": "keyapikey", "timeout": (5, 5), "typecast": True, } first_name = fields.TextField("First Name") age = fields.IntegerField("Age") You can implement meta attributes as callables if certain values need to be dynamically provided or are unavailable at import time: .. code-block:: python from pyairtable.orm import Model, fields from your_app.config import get_secret class Contact(Model): class Meta: base_id = "appaPqizdsNHDvlEm" table_name = "Contact" @staticmethod def api_key(): return get_secret("AIRTABLE_API_KEY") first_name = fields.TextField("First Name") age = fields.IntegerField("Age") idN created_time_MetametaF_deleted_fetched_fields_changed _memoizedkwargsc rt||_i|_|jt |di|y)N)r*r+r0_validate_classsuper__init_subclass__)clsr1 __class__s Q/var/www/html/lionshead/venv/lib/python3.12/site-packages/pyairtable/orm/model.pyr6zModel.__init_subclass__s1:   !+F+returnc|jjdddsJ|jjdddsJ|jjdddsJ|jjDcgc]}|j dr|}}t |j tjj}|r&tdj|j| ycc}w) Napi_keyTF)requiredcallbase_id table_name__z5Class {cls} fields clash with existing method: {name})r7name) r+get__dict__keys startswithset intersectionr& ValueErrorformat__name__)r7amodel_attributes overriddens r9r4zModel._validate_classsxx||I5|AAAxx||I5|AAAxx||L4e|DDD'*||'8'8':U':!!,,tBTA':U)*778K8K8MN GNN :O  Vs =C9C9c|jjDcic]\}}t|ts||c}}Scc}}w)a Build a mapping of the model's attribute names to field descriptor instances. >>> class Test(Model): ... first_name = TextField("First Name") ... age = NumberField("Age") ... >>> Test._attribute_descriptor_map() >>> { ... "field_name": , ... "another_Field": , ... } )rEitems isinstancer!)r7kvs r9_attribute_descriptor_mapzModel._attribute_descriptor_maps<"%!3!3!5N!5AAu9M1!5NNNs AAcz|jjDcic]}|j|c}Scc}w)a Build a mapping of the model's field names to field descriptor instances. >>> class Test(Model): ... first_name = TextField("First Name") ... age = NumberField("Age") ... >>> Test._field_name_descriptor_map() >>> { ... "First Name": , ... "Age": , ... } )rUvalues field_name)r7fs r9_field_name_descriptor_mapz Model._field_name_descriptor_maps8*-)F)F)H)O)O)QR)QA a)QRRRs8fieldsc |jd|_i|_|j D]/\}}||j vr t |t|||1i|_y#t$rY\wxYw)av Construct a model instance with field values based on the given keyword args. >>> Contact(name="Alice", birthday=date(1980, 1, 1)) The keyword argument ``id=`` special-cased and sets the record ID, not a field value. >>> Contact(id="recWPqD9izdsNvlE", name="Bob") r(N) popr(KeyErrorr.rQrUAttributeErrorsetattrr/)selfr[keyvalues r9__init__zModel.__init__s{ jj&DG  !,,.JC$88::$S)) D#u %)     sA)) A54A5c|jsd|jjdSd|jjd|jdS)Nz >**+4{!<`. Args: memoize: |kwarg_orm_memoize| rr3)rr+request_kwargsr|all from_recordr7rr1rs r9rz Model.all%sf  chh--.-#((..,,6v6 6 OOFGO 46   sA+c |j|jj|jjjdi|x}r|j ||Sy)z Retrieve the first record for this model. For all supported keyword arguments, see :meth:`Table.first `. Args: memoize: |kwarg_orm_memoize| rNr3)rr+rr|firstrrs r9rz Model.first4sS  chh--.)SXX^^))3F3 36 3??67?; ;r:instancecp||jjn|}|r||j|j<yy)zX If memoization is enabled, save the instance to the memoization cache. N)r+rr0r()r7rrs r9_maybe_memoizezModel._maybe_memoizeDs3 '.o#((""7 )1CMM(++ & r:rqc<|j}|jjDcic]/\}}||jr|s||dn||j |1}}}|j rt |j nd}|j||dScc}}w)a Build a :class:`~pyairtable.api.types.RecordDict` to represent this instance. This method converts internal field values into values expected by Airtable. For example, a ``datetime`` value from :class:`~pyairtable.orm.fields.DatetimeField` is converted into an ISO 8601 string. Args: only_writable: If ``True``, the result will exclude any values which are associated with readonly fields. Nr')r(rur[)rZr.rQreadonlyto_record_valuer)r#r()rarqmap_fieldrcr[cts r9r{zModel.to_recordMs..0!% 2 2 4 4 uK((] 5=4d5k.I.I%.P P 4  8<7H7H !2!2 3bggbFCC  s4Brc0|j}|djDcic]"\}}||vr||||j|nd$}}}||d}||_d|_t |d|_|j|||Scc}}w)z Create an instance from a record dict. Args: record: The record data from the Airtable API. memoize: |kwarg_orm_memoize| r[Nr(r(Tru)rZrQto_internal_valuer.r-r"r)r)r7rrname_field_maprrcrrs r9rzModel.from_recordbs779#)"2"8"8":  #;& $u%77>  #;   &,''  5f]6K L 8W-%  s'BT)fetchr record_idrc tt|j|}|r|js|j |j |||S#t$r ||}YFwxYw)z Create an instance from a record ID. Args: record_id: |arg_record_id| fetch: |kwarg_orm_fetch| memoize: |kwarg_orm_memoize| r)rSelfTyper0r^r-rr)r7rrrrs r9from_idz Model.from_idsc  )HcmmI&>?H ** NN  8W-  )i(H )sAA&%A&ch|js td|jjj|jfi|jj }|j |d}|j|_|jjd|_ |j|_ y)zS Fetch field values from the API and resets instance field values. z6cannot be fetched because instance does not have an idFrTN) r(rJr+r|rDrrr.r/r~r-r))rarunuseds r9rz Model.fetchswwUV V$$$TWWI 0H0HI!!&%!8~~   "//r: record_idsc|s!|Dcgc]}|j|dc}St|}i}|jr(|D]#} tt|j|||<%t t|t|z x}rVtdt |D}|j|j||Dcic]}|j|c}|Dcgc]}|| c}Scc}w#t $rYwxYwcc}wcc}w)aW Create a list of instances from record IDs. If any record IDs returned are invalid this will raise a KeyError, but only *after* retrieving all other valid records from the API. Args: record_ids: |arg_record_id| fetch: |kwarg_orm_fetch| memoize: |kwarg_orm_memoize| F)rc3DK|]}tt|ywN)rr).0rs r9 z!Model.from_ids..sWEV IK3EVs )formular) rlistr0rrr^sortedrHrrrr() r7rrrrby_id remainingrobjs r9from_idszModel.from_idss$ISTICKK K7T T*% *, ==' '+HcmmI6N'OE)$( s:U;< <9 <WVIEVWWG LL(+(QR(Q(QR  3==*Yi *==)U S>s#C0 C5D! D 5 DDmodelscLtfd|Dsttd|D|Dcgc]}|jr|}}|Dcgc]}|js|}}|Dcgc]}|j dx}r|d}}|Dcgc]!}|j dx}r |d|dd#}}|rPj j j|j jj j|rj j j|j jj j}t||D]"\}}|d|_t|d |_ $y y cc}wcc}wcc}wcc}w) z Save a list of model instances to the Airtable API with as few network requests as possible. Can accept a mixture of new records (which have not been saved yet) and existing records that have IDs. c36K|]}t|ywrrRrmodelr7s r9rz#Model.batch_save..>ve:eS)vc32K|]}t|ywrtyperrs r9rz#Model.batch_save..@U Trpr[r()r(r[rrruN)r TypeErrorrHr(r{r+r| batch_updatersrt batch_createzipr"r)) r7rr create_models update_modelsrcreate_recordsupdate_recordscreated_recordss ` r9 batch_savezModel.batch_saves>v>>C@@@A A,2CF5%((F C,2?F5ehhF ?'0 &///=== 8 & 0 '2 &///===$<6(+; <& 2  HHNN ' '**!hh44 (  !hhnn99**!hh44:O "%]O!D v!$<%:6-;P%Q""E 'D?0 2 s#FFF#F- F&F!c"td|Ds tdtfd|Dsttd|Djj j |Dcgc]}|jc}ycc}w)z Delete a list of model instances from Airtable. Raises: ValueError: if the model has not been saved to Airtable. c34K|]}|jywrrrs r9rz%Model.batch_delete..s0588szcannot delete an unsaved modelc36K|]}t|ywrrrs r9rz%Model.batch_delete..rrc32K|]}t|ywrrrs r9rz%Model.batch_delete..rrN)rrJrrHr+r| batch_deleter()r7rrs` r9rzModel.batch_deleteso000=> >>v>>C@@@A A ##6$B6%UXX6$BC$Bs1B c`|jjj|jS)z{ Return a list of comments on this record. See :meth:`Table.comments `. )r+r|commentsr(rhs r9rzModel.commentss! yy''00r:textcb|jjj|j|S)zu Add a comment to this record. See :meth:`Table.add_comment `. )r+r| add_commentr()rars r9rzModel.add_comments# yy**477D99r:)r;N)F)/rL __module__ __qualname____doc__r(str__annotations__r)r datetimerr,rkr-rrrrrr6 classmethodr4r rUrZrdrirlrrr rrrrr{rrrr rrrrrr __classcell__)r8s@r9r&r&+s.GVBL15L(8,,-4 7 HdHd )S. !!9d?##Xx/011,,   O$sH}*=OO S4 80C+DSS <=#=  %*- T- l- ^ ' '.2  Xd^  c  d8n    *. !$ :=  (   2h2$2D22DtD D*>B-5d^ @ "&   $   0 0 "& &>X&&> &> $ &> h &>&>P$RX$R4$R$RL D$x. DT D D1$w-1:::r:r&c eZdZUdZeeed<edee e ffdZ dde de de d e d e d de f d Zede fd Zede efdZede ee ej(ffdZedefdZede fdZedefdZede fdZedefdZede fdZede fdZ ede fdZ!ede"e e ffdZ#y)r*z Wrapper around a Model.Meta class that provides easier, typed access to configuration values (which may or may not be defined in the original class). rr;c`t|jddx}s"t|jjdt |t r|S t tttf|jS#t$r.t|jjdt|wxYw)NMetaz.Meta must be definedz#.Meta must be a dict or class; got ) getattrrr_rLrRdictrr rrrErr)rar+s r9_configz _Meta._config s FD999 DJJ$7$7#88M!NO O dD !K S)4==9 9 ::&&''J4PT:,W  s &A667B-NrCdefaultr>r? check_typesr$cr|r3||jvr%t|jjd|d|jj ||}t |r |r|}|r'|%t|jjd|d|&t ||std|dt||S)a+ Given a name, retrieve the model configuration with that name. Args: default: The default value to use if the name is not defined. required: If ``True``, raises ``ValueError`` if the name is undefined or None. call: If ``False``, does not execute any callables to retrieve this value; it will consider the callable itself as the value. check_types: If set, will raise a ``TypeError`` if the value is not an instance of the given type(s). z.Meta.z must be definedz cannot be Nonez expected z; got ) rrJrrLrDcallablerRrr)rarCrr>r?rrcs r9rDz _Meta.get-s& DLL0 3 34F4&@PQR R   w/ E?tGE   3 34F4&PQ Q  ":e[+Ii fT%[MJK K r:c:t|jddS)Nr=Tr>rrDrhs r9r=z _Meta.api_keyK488I8566r:cH|jddtdtfS)Ntimeoutrr)rDrtuplerhs r9rz _Meta.timeoutOs*xx dU+  r:cf|jddtdttjfS)NretryTr)rDrrkrRetryrhs r9retry_strategyz_Meta.retry_strategyWs0xx dT8>>:  r:cZt|j|j|jS)N)rr)rr=rrrhs r9apiz _Meta.api_s& LLLL..  r:c:t|jddS)Nr@Trrrhs r9r@z _Meta.base_idgrr:cL|jj|jSr)rbaser@rhs r9rz _Meta.baseksxx}}T\\**r:c:t|jddS)NrATrrrhs r9rAz_Meta.table_nameos488L48899r:cL|jj|jSr)rr|rArhs r9r|z _Meta.tablessyyt//r:c:t|jddS)NrsTrrkrDrhs r9rsz_Meta.typecastwsDHHZH677r:c:t|jddS)NrtFrrrhs r9rtz_Meta.use_field_ids{sDHH_eH<==r:c:t|jddS)NrFrrrhs r9rz _Meta.memoizesDHHYH677r:c$ddd|jdS)Njson) user_locale cell_format time_zonert)rtrhs r9rz_Meta.request_kwargss  !!//   r:)NFTN)$rLrrrrr&rpropertyr rrrrkr rDr=rrrrrrrrrr@rrrArr|rsrtrrrr3r:r9r*r*s ;  c*  .2     l+  <777 ,/   tX^^/C)D E   S  777+d++:C::0u008$88>t>>888 S#X  r:r*T)frozenceZdZUdZeed<dZeed<dZeed<dZ eed<e je Z eeed<d efd Zed efd Zy ) rna Represents the result of saving a record to the API. The result's attributes contain more granular information about the save operation: >>> result = model.save() >>> result.record_id 'recWPqD9izdsNvlE' >>> result.created False >>> result.updated True >>> result.forced False >>> result.field_names {'Name', 'Email'} If none of the model's fields have changed, calling :meth:`~pyairtable.orm.Model.save` will not perform any API requests and will return a SaveResult with no changes. >>> model = YourModel() >>> result = model.save() >>> result.saved True >>> second_result = model.save() >>> second_result.saved False For backwards compatibility, instances of SaveResult will evaluate as truthy if the record was created, and falsy if the record was not created. rFrvryrx)default_factoryrwr;cRtjdtd|jS)a Returns ``True`` if the record was created. This is for backwards compatibility with the behavior of :meth:`~pyairtable.orm.Model.save` prior to the 3.0 release, which returned a boolean indicating whether a record was created. z|Model.save() now returns SaveResult instead of bool; switch to checking Model.save().created instead before the 4.0 release.) stacklevel)warningswarnDeprecationWarningrvrhs r9__bool__zSaveResult.__bool__s(   P   ||r:c6|jxs |jS)z Whether the record was saved to the API. If ``False``, this indicates there were no changes to the model and the :meth:`~pyairtable.orm.Model.save` operation was not forced. )rvryrhs r9savedzSaveResult.saveds||+t||+r:N)rLrrrrrrvrkryrx dataclassesrrHrwr rr rrr3r:r9rnrnso>GTGTFD"3+"3"3C"HKYH $ ,t,,r:rn)6rrr r functoolsrtypingrrrrr r r r r rrrtyping_extensionsrrpyairtable.apirpyairtable.api.apirrpyairtable.api.baserpyairtable.api.tablerpyairtable.api.typesrrrrrpyairtable.formulasrrrpyairtable.modelsrpyairtable.orm.fieldsr r!pyairtable.utilsr"r#builtinsr$r&r*rnr3r:r9rs!%    /#0$&21%1G#i:i:X r r  r j $;,;,;,r: