D6i-dZddlZddlmZmZddlmZddlZddl m Z m Z ddl m Z ddlmZed gd ZGd d ZeZd Zy)a This module provides a decorator function for observing changes in a given property. Internally the decorator is implemented using SQLAlchemy event listeners. Both column properties and relationship properties can be observed. Property observers can be used for pre-calculating aggregates and automatic real-time data denormalization. Simple observers ---------------- At the heart of the observer extension is the :func:`observes` decorator. You mark some property path as being observed and the marked method will get notified when any changes are made to given path. Consider the following model structure: :: class Director(Base): __tablename__ = 'director' id = sa.Column(sa.Integer, primary_key=True) name = sa.Column(sa.String) date_of_birth = sa.Column(sa.Date) class Movie(Base): __tablename__ = 'movie' id = sa.Column(sa.Integer, primary_key=True) name = sa.Column(sa.String) director_id = sa.Column(sa.Integer, sa.ForeignKey(Director.id)) director = sa.orm.relationship(Director, backref='movies') Now consider we want to show movies in some listing ordered by director id first and movie id secondly. If we have many movies then using joins and ordering by Director.name will be very slow. Here is where denormalization and :func:`observes` comes to rescue the day. Let's add a new column called director_name to Movie which will get automatically copied from associated Director. :: from sqlalchemy_utils import observes class Movie(Base): # same as before.. director_name = sa.Column(sa.String) @observes('director') def director_observer(self, director): self.director_name = director.name .. note:: This example could be done much more efficiently using a compound foreign key from director_name, director_id to Director.name, Director.id but for the sake of simplicity we added this as an example. Observes vs aggregated ---------------------- :func:`observes` and :func:`.aggregates.aggregated` can be used for similar things. However performance wise you should take the following things into consideration: * :func:`observes` works always inside transaction and deals with objects. If the relationship observer is observing has a large number of objects it's better to use :func:`.aggregates.aggregated`. * :func:`.aggregates.aggregated` always executes one additional query per aggregate so in scenarios where the observed relationship has only a handful of objects it's better to use :func:`observes` instead. Example 1. Movie with many ratings Let's say we have a Movie object with potentially thousands of ratings. In this case we should always use :func:`.aggregates.aggregated` since iterating through thousands of objects is slow and very memory consuming. Example 2. Product with denormalized catalog name Each product belongs to one catalog. Here it is natural to use :func:`observes` for data denormalization. Deeply nested observing ----------------------- Consider the following model structure where Catalog has many Categories and Category has many Products. :: class Catalog(Base): __tablename__ = 'catalog' id = sa.Column(sa.Integer, primary_key=True) product_count = sa.Column(sa.Integer, default=0) @observes('categories.products') def product_observer(self, products): self.product_count = len(products) categories = sa.orm.relationship('Category', backref='catalog') class Category(Base): __tablename__ = 'category' id = sa.Column(sa.Integer, primary_key=True) catalog_id = sa.Column(sa.Integer, sa.ForeignKey('catalog.id')) products = sa.orm.relationship('Product', backref='category') class Product(Base): __tablename__ = 'product' id = sa.Column(sa.Integer, primary_key=True) price = sa.Column(sa.Numeric) category_id = sa.Column(sa.Integer, sa.ForeignKey('category.id')) :func:`observes` is smart enough to: * Notify catalog objects of any changes in associated Product objects * Notify catalog objects of any changes in Category objects that affect products (for example if Category gets deleted, or a new Category is added to Catalog with any number of Products) :: category = Category( products=[Product(), Product()] ) category2 = Category( product=[Product()] ) catalog = Catalog( categories=[category, category2] ) session.add(catalog) session.commit() catalog.product_count # 2 session.delete(category) session.commit() catalog.product_count # 1 Observing multiple columns -------------------------- You can also observe multiple columns by specifying all the observable columns in the decorator. :: class Order(Base): __tablename__ = 'order' id = sa.Column(sa.Integer, primary_key=True) unit_price = sa.Column(sa.Integer) amount = sa.Column(sa.Integer) total_price = sa.Column(sa.Integer) @observes('amount', 'unit_price') def total_price_observer(self, amount, unit_price): self.total_price = amount * unit_price N) defaultdict namedtuple)Iterable) getdotattr has_changes)AttrPath) is_sequenceCallbackfuncbackreffullpathcHeZdZdZdZdZdZdZdZdZ dZ d Z d Z y ) PropertyObservercZtjjd|jftjjd|jftjj j d|jfg|_tt|_ tt|_ y)Nmapper_configuredafter_configured before_flush) saormMapperupdate_generator_registry gather_pathssessionSessioninvoke_callbacks listener_argsrlist callback_mapgenerator_registryselfs \/home/azureuser/techstart-app/venv/lib/python3.12/site-packages/sqlalchemy_utils/observer.py__init__zPropertyObserver.__init__sx VV]]/1O1O P VV]].0A0A B VV^^ # #^T5J5J K  (-"-d"3c^|jD]}tjj| yN)rreventremover#argss r$remove_listenersz!PropertyObserver.remove_listenerss'&& #D HHOOT " #r&c|jD];}tjj|r tjj|=yr()rrr)containslistenr+s r$register_listenersz#PropertyObserver.register_listenerss9&& 'D88$$d+& 'r&cy)Nzr"s r$__repr__zPropertyObserver.__repr__s#r&c|jjD]-}t|ds|j|j |/y)zA Adds generator functions to generator_registry. __observes__N)__dict__valueshasattrr!append)r#mapperclass_ generators r$rz*PropertyObserver.update_generator_registrysE  //1 BIy.1''/66yA Br&c b|jjD]\}}|D]}g}|jD]}|jt |||D]}|j |jt |d|tt|D]}|dz}||j} t| tjjs<||jjj} |j | jt ||d||y)Nr r)r!itemsr6r:r r r rangelenproperty isinstancerrRelationshipPropertyr;r<) r#r< generatorscallback full_paths call_pathpathindexiprop prop_classs r$rzPropertyObserver.gather_pathss."&"9"9"?"?"A  FJ&  !)!6!6CI%%hvy&ABC'D%%f-44 hzR"'s4y!1 !AI#E{33%dBFF,G,GH)-e)=)=)D)D)K)KJ --j9@@ ()1.22AhK-7!"     r&c#FKtjj|}|D]m}|j}|r t ||n|}|s"t |t s|g}|j5|D]}|s|j||}|s|  dddoy#1swYzxYwwr() rrobject_sessionrrrCr no_autoflushget_callback_args) r#obj callbacksrrFr root_objsroot_objr,s r$gather_callback_argsz%PropertyObserver.gather_callback_argss&&'',! +H&&G4; 30I!)X6!* I))+$-+##'#9#9(H#MD#&* +++ +++s0AB!B!%B.BB B!B B!c :tjj||jDcgc]}t ||fd}}|jDcgc] }t |}}|D]#}d|vs t ||s||j|fcSycc}wcc}w)Nc |jvSr()deleted)rRrs r$z4PropertyObserver.get_callback_args.. s3goo3Mr&.)rrrOrrstrrr )r#rUrFrIobjectspathsrs @r$rQz"PropertyObserver.get_callback_argss&&''1!))  x'M N  (0'8'89tT99 :Dd{k(D9 (--99 :  :s BBc#Ktj|j|j|j}|D]7}|j j D]\}}t||s||f9ywr() itertoolschainnewdirtyrYr r?rC)r#robjsrRr<rSs r$iterate_objects_and_callbacksz.PropertyObserver.iterate_objects_and_callbackssjw{{GMM7??K )C%)%6%6%<%<%> )! c6*y.( ) )s A'A5* A5c (td}|j|D]\}}|j||}|D]u\}} } ||| si||| <t| D]Q\} } t | r6||| j | t t | z||| | <G| ||| | <Sw|jD]I\}} | jD]1\}}||gtt|D cgc]} ||  c} 3Kycc} w)Nc ttSr()rsetr3r&r$rZz3PropertyObserver.invoke_callbacks..s K,<r&) rrerV enumerater getrhr?r@rA)r#rctx instances callback_argsrRrSr,rUr r]rKobject_ callback_objsrFrds r$rz!PropertyObserver.invoke_callbackssL#$<= "@@I CNC,,S).wraps..wrapper]s.t.v. .r&)r6)r rxr^s` r$wrapszobserves..wraps\s / %r&)poprtr1)r^ observer_kw observer_rys` r$observesr}0s.R H5I   " Lr&)__doc__r` collectionsrrcollections.abcr sqlalchemyr functionsrrrIr utilsr r rrtr}r3r&r$rsNm^/$. j"A BmImI`  3r&