Python SQLAlchemy Hybrid Properties: Vypočítané atributy pro výkonné modelování dat

SQLAlchemy, výkonný a flexibilní Python SQL toolkit a Object-Relational Mapper (ORM), nabízí bohatou sadu funkcí pro interakci s databázemi. Mezi nimi vynikají Hybrid Properties (hybridní vlastnosti) jako obzvláště užitečný nástroj pro vytváření vypočítaných atributů ve vašich datových modelech. Tento článek poskytuje komplexního průvodce pro pochopení a využití SQLAlchemy Hybrid Properties, který vám umožní vytvářet expresivnější, udržovatelnější a efektivnější aplikace.

Co jsou SQLAlchemy Hybrid Properties?

Hybrid Property, jak název napovídá, je speciální typ vlastnosti v SQLAlchemy, která se může chovat odlišně v závislosti na kontextu, ve kterém je k ní přistupováno. Umožňuje definovat atribut, ke kterému lze přistupovat přímo na instanci vaší třídy (jako k běžné vlastnosti) nebo jej použít v SQL výrazech (jako sloupec). Toho je dosaženo definováním samostatných funkcí pro přístup na úrovni instance i na úrovni třídy.

V podstatě Hybrid Properties poskytují způsob, jak definovat vypočítané atributy, které jsou odvozeny od jiných atributů vašeho modelu. Tyto vypočítané atributy lze použít v dotazech a lze k nim také přistupovat přímo na instancích vašeho modelu, což poskytuje konzistentní a intuitivní rozhraní.

Proč používat Hybrid Properties?

Použití Hybrid Properties nabízí několik výhod:

• Expresivita: Umožňují vám vyjádřit složité vztahy a výpočty přímo ve vašem modelu, což činí váš kód čitelnějším a snazším na pochopení.
• Udržovatelnost: Zapouzdřením složité logiky do Hybrid Properties snižujete duplicitu kódu a zlepšujete udržovatelnost vaší aplikace.
• Efektivita: Hybrid Properties vám umožňují provádět výpočty přímo v databázi, což snižuje množství dat, které je třeba přenášet mezi vaší aplikací a databázovým serverem.
• Konzistence: Poskytují konzistentní rozhraní pro přístup k vypočítaným atributům, bez ohledu na to, zda pracujete s instancemi vašeho modelu nebo píšete SQL dotazy.

Základní příklad: Celé jméno

Začněme jednoduchým příkladem: výpočtem celého jména osoby z jejího křestního jména a příjmení.

Definice modelu

Nejprve definujeme jednoduchý model `Person` se sloupci `first_name` a `last_name`.

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.hybrid import hybrid_property

Base = declarative_base()

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    def __repr__(self):
        return f""


engine = create_engine('sqlite:///:memory:') # Databáze v paměti pro příklad
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

Vytvoření hybridní vlastnosti

Nyní přidáme hybridní vlastnost `full_name`, která zřetězí křestní jméno a příjmení.

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    def __repr__(self):
        return f""

V tomto příkladu dekorátor `@hybrid_property` přemění metodu `full_name` na hybridní vlastnost. Když přistoupíte k `person.full_name`, bude vykonán kód uvnitř této metody.

Přístup k hybridní vlastnosti

Vytvořme si nějaká data a podívejme se, jak přistupovat k vlastnosti `full_name`.

person1 = Person(first_name='Alice', last_name='Smith')
person2 = Person(first_name='Bob', last_name='Johnson')

session.add_all([person1, person2])
session.commit()

print(person1.full_name)  # Výstup: Alice Smith
print(person2.full_name)  # Výstup: Bob Johnson

Použití hybridní vlastnosti v dotazech

Skutečná síla Hybrid Properties se projeví, když je použijete v dotazech. Můžeme filtrovat na základě `full_name`, jako by to byl běžný sloupec.

people_with_smith = session.query(Person).filter(Person.full_name == 'Alice Smith').all()
print(people_with_smith) # Výstup: []

Výše uvedený příklad však bude fungovat pouze pro jednoduché porovnání rovnosti. Pro složitější operace v dotazech (jako `LIKE`) musíme definovat výrazovou funkci.

Definice výrazových funkcí

Chcete-li použít Hybrid Properties ve složitějších SQL výrazech, musíte definovat výrazovou funkci. Tato funkce říká SQLAlchemy, jak přeložit hybridní vlastnost na SQL výraz.

Upravme předchozí příklad tak, aby podporoval dotazy `LIKE` na vlastnost `full_name`.

from sqlalchemy import func

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    def __repr__(self):
        return f""

Zde jsme přidali dekorátor `@full_name.expression`. Ten definuje funkci, která jako argument bere třídu (`cls`) a vrací SQL výraz, který zřetězí křestní jméno a příjmení pomocí funkce `func.concat`. `func.concat` je funkce SQLAlchemy, která reprezentuje databázovou funkci pro zřetězení (např. `||` v SQLite, `CONCAT` v MySQL a PostgreSQL).

Nyní můžeme používat dotazy `LIKE`:

people_with_smith = session.query(Person).filter(Person.full_name.like('%Smith%')).all()
print(people_with_smith) # Výstup: []

Nastavení hodnot: Setter

Hybrid Properties mohou mít také settery, které vám umožní aktualizovat podkladové atributy na základě nové hodnoty. To se provádí pomocí dekorátoru `@full_name.setter`.

Přidejme do naší vlastnosti `full_name` setter, který rozdělí celé jméno na křestní jméno a příjmení.

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    @full_name.setter
    def full_name(self, full_name):
        parts = full_name.split()
        self.first_name = parts[0]
        self.last_name = ' '.join(parts[1:]) if len(parts) > 1 else ''

    def __repr__(self):
        return f""

Nyní můžete nastavit vlastnost `full_name` a ta aktualizuje atributy `first_name` a `last_name`.

person = Person(first_name='Alice', last_name='Smith')
session.add(person)
session.commit()

person.full_name = 'Charlie Brown'
print(person.first_name)  # Výstup: Charlie
print(person.last_name)   # Výstup: Brown

session.commit()

Deletery

Podobně jako settery můžete také definovat deleter pro hybridní vlastnost pomocí dekorátoru `@full_name.deleter`. To vám umožní definovat, co se stane, když se pokusíte o `del person.full_name`.

Pro náš příklad zařiďme, aby smazání celého jména vymazalo jak křestní jméno, tak příjmení.

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    @full_name.setter
    def full_name(self, full_name):
        parts = full_name.split()
        self.first_name = parts[0]
        self.last_name = ' '.join(parts[1:]) if len(parts) > 1 else ''

    @full_name.deleter
    def full_name(self):
        self.first_name = None
        self.last_name = None

    def __repr__(self):
        return f""

person = Person(first_name='Charlie', last_name='Brown')
session.add(person)
session.commit()

del person.full_name
print(person.first_name) # Výstup: None
print(person.last_name)  # Výstup: None

session.commit()

Pokročilý příklad: Výpočet věku z data narození

Podívejme se na složitější příklad: výpočet věku osoby z jejího data narození. To ukazuje sílu Hybrid Properties při práci s daty a provádění výpočtů.

Přidání sloupce s datem narození

Nejprve přidáme do našeho modelu `Person` sloupec `date_of_birth`.

from sqlalchemy import Date
import datetime

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)
    date_of_birth = Column(Date)

    # ... (předchozí kód)

Výpočet věku pomocí hybridní vlastnosti

Nyní vytvoříme hybridní vlastnost `age`. Tato vlastnost vypočítává věk na základě sloupce `date_of_birth`. Budeme muset ošetřit případ, kdy je `date_of_birth` `None`.

from sqlalchemy import Date
import datetime

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)
    date_of_birth = Column(Date)

    @hybrid_property
    def age(self):
        if self.date_of_birth:
            today = datetime.date.today()
            age = today.year - self.date_of_birth.year - ((today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day))
            return age
        return None # Nebo jiná výchozí hodnota

    @age.expression
    def age(cls):
        today = datetime.date.today()
        return func.cast(func.strftime('%Y', 'now') - func.strftime('%Y', cls.date_of_birth) - (func.strftime('%m-%d', 'now') < func.strftime('%m-%d', cls.date_of_birth)), Integer)

    # ... (předchozí kód)

Důležité body k zvážení:

• Databázově specifické funkce pro datum: Výrazová funkce používá `func.strftime` pro výpočty s daty. Tato funkce je specifická pro SQLite. Pro jiné databáze (jako PostgreSQL nebo MySQL) budete muset použít příslušné databázově specifické funkce pro datum (např. `EXTRACT` v PostgreSQL, `YEAR` a `MAKEDATE` v MySQL).
• Přetypování: Používáme `func.cast` k přetypování výsledku výpočtu data na celé číslo. To zajišťuje, že vlastnost `age` vrací celočíselnou hodnotu.
• Časová pásma: Při práci s daty mějte na paměti časová pásma. Ujistěte se, že vaše data jsou ukládána a porovnávána v konzistentním časovém pásmu.
• Zpracování hodnot `None` Vlastnost by měla ošetřovat případy, kdy je `date_of_birth` `None`, aby se předešlo chybám.

Použití vlastnosti věk

person1 = Person(first_name='Alice', last_name='Smith', date_of_birth=datetime.date(1990, 1, 1))
person2 = Person(first_name='Bob', last_name='Johnson', date_of_birth=datetime.date(1985, 5, 10))

session.add_all([person1, person2])
session.commit()

print(person1.age)  # Výstup: (Na základě aktuálního data a data narození)
print(person2.age)  # Výstup: (Na základě aktuálního data a data narození)

people_over_30 = session.query(Person).filter(Person.age > 30).all()
print(people_over_30) # Výstup: (Lidé starší 30 let na základě aktuálního data)

Složitější příklady a případy použití

Výpočet celkové částky objednávky v e-commerce aplikaci

V e-commerce aplikaci můžete mít model `Order` se vztahem k modelům `OrderItem`. Mohli byste použít hybridní vlastnost k výpočtu celkové hodnoty objednávky.

from sqlalchemy import ForeignKey, Float
from sqlalchemy.orm import relationship

class Order(Base):
    __tablename__ = 'orders'
    id = Column(Integer, primary_key=True)
    items = relationship("OrderItem", back_populates="order")

    @hybrid_property
    def total(self):
        return sum(item.price * item.quantity for item in self.items)

    @total.expression
    def total(cls):
        return session.query(func.sum(OrderItem.price * OrderItem.quantity)).\
            filter(OrderItem.order_id == cls.id).scalar_subquery()

class OrderItem(Base):
    __tablename__ = 'order_items'
    id = Column(Integer, primary_key=True)
    order_id = Column(Integer, ForeignKey('orders.id'))
    order = relationship("Order", back_populates="items")
    price = Column(Float)
    quantity = Column(Integer)

Tento příklad demonstruje složitější výrazovou funkci používající poddotaz k výpočtu celkové částky přímo v databázi.

Geografické výpočty

Pokud pracujete s geografickými daty, mohli byste použít Hybrid Properties k výpočtu vzdáleností mezi body nebo k určení, zda se bod nachází v určité oblasti. To často zahrnuje použití databázově specifických geografických funkcí (např. funkce PostGIS v PostgreSQL).

from geoalchemy2 import Geometry
from sqlalchemy import cast

class Location(Base):
    __tablename__ = 'locations'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    coordinates = Column(Geometry(geometry_type='POINT', srid=4326))

    @hybrid_property
    def latitude(self):
        if self.coordinates:
            return self.coordinates.x
        return None

    @latitude.expression
    def latitude(cls):
        return cast(func.ST_X(cls.coordinates), Float)

    @hybrid_property
    def longitude(self):
        if self.coordinates:
            return self.coordinates.y
        return None

    @longitude.expression
    def longitude(cls):
        return cast(func.ST_Y(cls.coordinates), Float)

Tento příklad vyžaduje rozšíření `geoalchemy2` a předpokládá, že používáte databázi s povoleným PostGIS.

Osvědčené postupy pro používání Hybrid Properties

• Udržujte to jednoduché: Používejte Hybrid Properties pro relativně jednoduché výpočty. Pro složitější logiku zvažte použití samostatných funkcí nebo metod.
• Používejte vhodné datové typy: Ujistěte se, že datové typy použité ve vašich Hybrid Properties jsou kompatibilní jak s Pythonem, tak s SQL.
• Zvažte výkon: Ačkoli Hybrid Properties mohou zlepšit výkon prováděním výpočtů v databázi, je nezbytné sledovat výkon vašich dotazů a optimalizovat je podle potřeby.
• Důkladně testujte: Důkladně testujte své Hybrid Properties, abyste se ujistili, že produkují správné výsledky ve všech kontextech.
• Dokumentujte svůj kód: Jasně dokumentujte své Hybrid Properties, abyste vysvětlili, co dělají a jak fungují.

Běžné nástrahy a jak se jim vyhnout

• Databázově specifické funkce: Ujistěte se, že vaše výrazové funkce používají databázově agnostické funkce nebo poskytují databázově specifické implementace, abyste se vyhnuli problémům s kompatibilitou.
• Nesprávné výrazové funkce: Dvakrát zkontrolujte, zda vaše výrazové funkce správně překládají vaši hybridní vlastnost na platný SQL výraz.
• Výkonnostní úzká hrdla: Vyhněte se používání Hybrid Properties pro výpočty, které jsou příliš složité nebo náročné na zdroje, protože to může vést k výkonnostním úzkým hrdlům.
• Konfliktní názvy: Vyhněte se používání stejného názvu pro vaši hybridní vlastnost a sloupec ve vašem modelu, protože to může vést ke zmatení a chybám.

Aspekty internacionalizace

Při práci s Hybrid Properties v internacionalizovaných aplikacích zvažte následující:

• Formáty data a času: Používejte vhodné formáty data a času pro různá místní nastavení.
• Formáty čísel: Používejte vhodné formáty čísel pro různá místní nastavení, včetně desetinných oddělovačů a oddělovačů tisíců.
• Formáty měn: Používejte vhodné formáty měn pro různá místní nastavení, včetně symbolů měn a desetinných míst.
• Porovnávání řetězců: Používejte funkce pro porovnávání řetězců, které jsou si vědomy místního nastavení, abyste zajistili, že řetězce jsou správně porovnávány v různých jazycích.

Například při výpočtu věku zvažte různé formáty data používané po celém světě. V některých regionech se datum píše jako `MM/DD/YYYY`, zatímco v jiných je to `DD/MM/YYYY` nebo `YYYY-MM-DD`. Ujistěte se, že váš kód správně parsuje data ve všech formátech.

Při zřetězování řetězců (jako v příkladu `full_name`) si buďte vědomi kulturních rozdílů v pořadí jmen. V některých kulturách je příjmení před křestním jménem. Zvažte poskytnutí možností pro uživatele, aby si mohli přizpůsobit formát zobrazení jména.

Závěr

SQLAlchemy Hybrid Properties jsou mocným nástrojem pro vytváření vypočítaných atributů ve vašich datových modelech. Umožňují vám vyjádřit složité vztahy a výpočty přímo ve vašich modelech, což zlepšuje čitelnost kódu, udržovatelnost a efektivitu. Porozuměním tomu, jak definovat Hybrid Properties, výrazové funkce, settery a deletery, můžete tuto funkci využít k vytváření sofistikovanějších a robustnějších aplikací.

Dodržováním osvědčených postupů uvedených v tomto článku a vyhýbáním se běžným nástrahám můžete efektivně využívat Hybrid Properties k vylepšení vašich SQLAlchemy modelů a zjednodušení vaší logiky přístupu k datům. Nezapomeňte zvážit aspekty internacionalizace, abyste zajistili, že vaše aplikace bude správně fungovat pro uživatele po celém světě. S pečlivým plánováním a implementací se Hybrid Properties mohou stát neocenitelnou součástí vaší sady nástrojů SQLAlchemy.