o ckF[@9@s0ddlmZGdddeZGdddeZdS))deepcopyc@s eZdZdS)NEWVALUEN)__name__ __module__ __qualname__rr6/usr/lib/python3/dist-packages/boto/dynamodb2/items.pyrsrc@seZdZdZd6ddZddZdd Zd d Zd d ZddZ ddZ d7ddZ ddZ ddZ ddZeZddZd7ddZddZd d!Zd"d#Zd$d%Zd&d'Zd7d(d)Zd*d+Zd,d-Zd.d/Zd0d1Zd8d2d3Zd4d5ZdS)9Itema An object representing the item data within a DynamoDB table. An item is largely schema-free, meaning it can contain any data. The only limitation is that it must have data for the fields in the ``Table``'s schema. This object presents a dictionary-like interface for accessing/storing data. It also tries to intelligently track how data has changed throughout the life of the instance, to be as efficient as possible about updates. Empty items, or items that have no data, are considered falsey. NFcCs`||_||_i|_||_|j|_t|jtr|jj|_|jdur#i|_|jr.t|j|_dSdS)a Constructs an (unsaved) ``Item`` instance. To persist the data in DynamoDB, you'll need to call the ``Item.save`` (or ``Item.partial_save``) on the instance. Requires a ``table`` parameter, which should be a ``Table`` instance. This is required, as DynamoDB's API is focus around all operations being table-level. It's also for persisting schema around many objects. Optionally accepts a ``data`` parameter, which should be a dictionary of the fields & values of the item. Alternatively, an ``Item`` instance may be provided from which to extract the data. Optionally accepts a ``loaded`` parameter, which should be a boolean. ``True`` if it was preexisting data loaded from DynamoDB, ``False`` if it's new data from the user. Default is ``False``. Example:: >>> users = Table('users') >>> user = Item(users, data={ ... 'username': 'johndoe', ... 'first_name': 'John', ... 'date_joined': 1248o61592, ... }) # Change existing data. >>> user['first_name'] = 'Johann' # Add more data. >>> user['last_name'] = 'Doe' # Delete data. >>> del user['date_joined'] # Iterate over all the data. >>> for field, val in user.items(): ... print "%s: %s" % (field, val) username: johndoe first_name: John date_joined: 1248o61592 N)table_loaded _orig_data_data _dynamizer isinstancer r)selfr dataloadedrrr__init__s+   z Item.__init__cCs|j|dSNr getrkeyrrr __getitem__QzItem.__getitem__cCs||j|<dSrr )rrvaluerrr __setitem__TrzItem.__setitem__cCs||jvrdS|j|=dSrrrrrr __delitem__Ws  zItem.__delitem__cC |jSr)r keysrrrrr ] z Item.keyscCrr)r valuesr!rrrr#`r"z Item.valuescCrr)r itemsr!rrrr$cr"z Item.itemscCs|j||Srr)rrdefaultrrrrfrzItem.getccs|jD]}|j|VqdSrrrrrr__iter__is z Item.__iter__cCs ||jvSrrrrrr __contains__mr"zItem.__contains__cCs t|jSr)boolr r!rrr__bool__pr"z Item.__bool__cCsiigd}t|j}t|j}||D]%}|j||j|kr>||j|r7|j||d|<q|d|q||D]}||j|rW|j||d|<qD||D] }|d|q]|S)z Checks the ``-orig_data`` against the ``_data`` to determine what changes to the data are present. Returns a dictionary containing the keys ``adds``, ``changes`` & ``deletes``, containing the updated data. addschangesdeletesr,r-r+)setr r r intersection _is_storableappend difference)r alterations orig_keys data_keysrrrr_determine_alterationsus& zItem._determine_alterationscCs8|dur|}d}dD] }t||rd}|Sq |S)a Returns whether or not the data has changed on the ``Item``. Optionally accepts a ``data`` argument, which accepts the output from ``self._determine_alterations()`` if you've already called it. Typically unnecessary to do. Default is ``None``. Example: >>> user.needs_save() False >>> user['first_name'] = 'Johann' >>> user.needs_save() True NFr*T)r6len)rr needs_savekindrrrr8s zItem.needs_savecCst|j|_dS)aM Marks an ``Item`` instance as no longer needing to be saved. Example: >>> user.needs_save() False >>> user['first_name'] = 'Johann' >>> user.needs_save() True >>> user.mark_clean() >>> user.needs_save() False N)rr r r!rrr mark_cleanszItem.mark_cleancCsdS)z DEPRECATED: Marks an ``Item`` instance as needing to be saved. This method is no longer necessary, as the state tracking on ``Item`` has been improved to automatically detect proper state. Nrr!rrr mark_dirtyszItem.mark_dirtycCsFi|_|diD] \}}|j|||<q d|_t|j|_dS)aF This is only useful when being handed raw data from DynamoDB directly. If you have a Python datastructure already, use the ``__init__`` or manually set the data instead. Largely internal, unless you know what you're doing or are trying to mix the low-level & high-level APIs. r TN)r rr$rdecoder rr )rr field_name field_valuerrrloads  z Item.loadcCs(|j}i}|D]}||||<q |S)z\ Returns a Python-style dict of the keys/values. Largely internal. )r get_key_fields)r key_fieldskey_datarrrrget_keyss z Item.get_keyscCs.i}|D] \}}|j|||<q|S)z^ Returns a DynamoDB-style dict of the keys/values. Largely internal. )rCr$rencode)r raw_key_datarrrrr get_raw_keysszItem.get_raw_keyscCsi}|durt|jt|j}t|}|D]S}ddi||<d}||jvr4||jvr4td||j|t}|j|t}||krI|}n||jvr]||jvrZd||d<n|}n|}|durm|j |||d<q|S)zm Builds up a list of expecations to hand off to DynamoDB on save. Largely internal. NExistsTzUnknown key %s provided.FValue) listr r r r. ValueErrorrrrrD)rfieldsexpectsrr orig_value current_valuerrr build_expectss.   zItem.build_expectscCs|s|dvrdSdS)N)rgFFTr)rrrrrr01szItem._is_storablecCs8i}|jD]\}}||sq|j|||<q|S)z Runs through all fields & encodes them to be handed off to DynamoDB as part of an ``save`` (``put_item``) call. Largely internal. )r r$r0rrD)r final_datarrrrr prepare_full:s   zItem.prepare_fullcCsi}t}|}|dD]\}}d|j|j|d||<||q|dD]\}}d|j|j|d||<||q-|dD] }ddi||<||qI||fS)z Runs through **ONLY** the changed/deleted fields & encodes them to be handed off to DynamoDB as part of an ``partial_save`` (``update_item``) call. Largely internal. r+PUT)ActionrHr,r-rSDELETE)r.r6r$rrDr add)rrPrKr3rrrrrprepare_partialMs$     zItem.prepare_partialc Cs|}|\}}|sdS|D]\}}||vr.||=z||Wqty-Yqwq|j|d}|jj|||d}||S)an Saves only the changed data to DynamoDB. Extremely useful for high-volume/high-write data sets, this allows you to update only a handful of fields rather than having to push entire items. This prevents many accidental overwrite situations as well as saves on the amount of data to transfer over the wire. Returns ``True`` on success, ``False`` if no save was performed or the write failed. Example:: >>> user['last_name'] = 'Doh!' # Only the last name field will be sent to DynamoDB. >>> user.partial_save() F)rKrL) rCrVr$removeKeyErrorrOr _update_itemr:)rrrPrK fieldnamerrLreturnedrrr partial_saveqs"   zItem.partial_savecCsH|s|sdS|}d}|dur|}|jj||d}||S)aU Saves all data to DynamoDB. By default, this attempts to ensure that none of the underlying data has changed. If any fields have changed in between when the ``Item`` was constructed & when it is saved, this call will fail so as not to cause any data loss. If you're sure possibly overwriting data is acceptable, you can pass an ``overwrite=True``. If that's not acceptable, you may be able to use ``Item.partial_save`` to only write the changed field data. Optionally accepts an ``overwrite`` parameter, which should be a boolean. If you provide ``True``, the item will be forcibly overwritten within DynamoDB, even if another process changed the data in the meantime. (Default: ``False``) Returns ``True`` on success, ``False`` if no save was performed. Example:: >>> user['last_name'] = 'Doh!' # All data on the Item is sent to DynamoDB. >>> user.save() # If it fails, you can overwrite. >>> user.save(overwrite=True) FNrW)r8rQrOr _put_itemr:)r overwriterPrLr\rrrsaves z Item.savecCs|}|jjdi|S)z Deletes the item's data to DynamoDB. Returns ``True`` on success. Example:: # Buh-bye now. >>> user.delete() Nr)rCr delete_item)rrBrrrdeletes z Item.delete)NFr)F)rrr__doc__rrrrr r#r$rr&r'r) __nonzero__r6r8r:r;r?rCrFrOr0rQrVr]r`rbrrrrr s8 9  $  4 $ . -r N)copyrobjectrr rrrrs