par Ormar

Généralités

Le paquet ormar est un ORM asynchrone pour Python qui prend en charge Postgres, MySQL et SQLite.

Les principaux avantages de l'utilisation d'Ormar sont:

• Obtenir un ORM asynchrone qui peut être utilisé avec des frameworks asynchrones (fastapi, starlette, etc.)
• ne maintient qu 'un seul modèle-vous n'avez pas à maintenir pydantic et d'autres modèles orm (sqlalchemy, peewee, gino, etc.)

L'objectif est de créer un ORM simple qui peut être utilisé directement avec un fastapi basé sur la vérification des données pydantique (comme modèle de demande et de réponse).

Ormar-à l'exception de l'évident "ORM" dans le nom-tire son nom du mot suédois ormar, qui signifie serpent, et du mot croate ormar(e), qui signifie cabinet.

Quel meilleur nom pour un ORM python que Snakes Cabinet:)

Si vous aimez Ormar, n'oubliez pas de mettre une étoile sur le dépôt dans Github!

Plus la communauté que nous construisons est grande, plus il est facile de repérer les erreurs et d'attirer des contributeurs;)

Documentaire

Voir la documentation pour plus de détails.

Notez que, pour des raisons de concision, la plupart des fragments de document omettent la création de bases de données et la planification de l'exécution de fonctions asynchrones.

Si vous voulez plus d'exemples réels que dans la documentation, vous pouvez consulter les dossiers de test, car ils doivent être créés et connectés à la base de données dans la plupart des tests.

Mais gardez à l'esprit que ce ne sont que des tests et que toutes les solutions ne sont pas adaptées à une utilisation dans la vie réelle.

Une partie de l'écosystème des fastapi

Dans le cadre de l'écosystème fastapi, ormar est pris en charge dans des bibliothèques sélectionnées qui fonctionnent d'une certaine manière avec la base de données.

Ormar reste indépendant du dialecte sql-seules les colonnes qui fonctionnent dans tous les backends supportés sont donc implémentées.

En tant qu 'extension d'ormar, il est relativement facile d'implémenter des colonnes pour un dialecte particulier.

Implémentation de colonnes spécifiques à Postgres: ormar-postgres-extensions

Si vous maintenez ou utilisez une bibliothèque différente et que vous souhaitez qu 'elle prenne en charge ormar, dites-nous comment vous pouvez vous aider.

Dépendance

Ormar est construit avec:

• Le noyau sqlalchemy utilisé pour construire des requêtes.
• Base de données pour le support asynchrone entre bases de données.
• Pydantic est utilisé pour la validation des données.

Licence pour

Ormar est construit en tant que logiciel open source et restera entièrement libre (licence MIT).

Lorsque j'écris du code open source pour résoudre des problèmes quotidiens au travail ou pour promouvoir et construire une communauté Python solide, vous pouvez dire merci et m'acheter un café ou me financer chaque mois pour m'assurer que mon travail reste libre et maintenu.

sponsorisé

Migration de sqlalchemy et des bases de données existantes

Si vous utilisez actuellement sqlalchemy et que vous souhaitez passer à ormar, consultez l'outil de traduction automatique, qui vous aide à traduire votre modèle sqlalchemy orm existant afin que vous n'ayez pas à le faire manuellement.

La version Beta est disponible sur github: sqlalchemy-to-ormar ou simplement pip install sqlalchemy-to-ormar

sqlalchemy-to-ormar peut être utilisé avec sqlacodegen pour mapper/générer automatiquement des modèles ormar à partir de bases de données existantes, même si votre projet n'utilise pas sqlalchemy.

Migration et création de base de données

Comme ormar est construit sur le noyau SQLAlchemy, vous pouvez utiliser alembic pour fournir une migration de base de données (ce que vous devriez faire pour le code de production).

Pour les tests et les applications de base, sqlalchemy suffit:

#note Ceci est juste un snippet partiel plein exemple de travail below
#1. importations
Import sqlalchemy
Importation de databases
Import par Ormar

#2 Initialisation
DATABASE_URL ="sqlite:///db. sqlite"
base_ormar_config = ormar. OrmarConfig (
    metadata = sqlalchemy. MetaData (),
    database = databases. Database (DATABASE_URL),
    engine = sqlalchemy. create_engine (DATABASE_URL),
)

#Définition des modèles ici

# 3. création de base de données et création de tables
base_ormar_config.metadata.create_all(engine)

Pour obtenir un exemple de configuration d'alembic et plus d'informations sur la migration et la création de bases de données, consultez la section Documentation de migration.

Version encapsulée

ormar est toujours en développement: nous recommandons de fixer toutes les dépendances (c'est-à-dire ormar~=0.9.1).

Ormar suit également le numéro de version, c'est-à-dire que les modifications majeures augmentent le numéro de version majeure, tandis que d'autres modifications et correctifs augmentent le numéro de version mineure, donc pour ce dernier, vous devriez être en mesure de mettre à jour en toute sécurité, mais assurez-vous de lire d'abord la documentation de la distribution.example: (0.5.2 -> 0.6.0 - breaking, 0.5.2 -> 0.5.3 - non breaking).

Python asynchrone

Notez qu 'ormar est un ORM asynchrone, ce qui signifie que vous devez attendre l'appel d'une méthode que vous prévoyez d'exécuter dans une boucle d'événements. Python a un module intégré, asyncio, qui vous permet de le faire.

Notez que la plupart des interpréteurs Python « normaux » ne permettent pas l'exécution d'un wait en dehors d'une fonction (car vous programmez en fait cette fonction pour retarder son exécution et n'obtenez pas de résultat immédiat).

Dans les frameworks Web modernes tels que fastapi, le framework s'en occupera pour vous, mais si vous prévoyez de le faire vous-même, vous devrez le faire manuellement, comme décrit dans le démarrage rapide ci-dessous.

Commencer rapidement

Notez que vous pouvez trouver le même script dans le dossier exemple sur github.

de type import optionnel

Importation de databases

Importer à Ormar
Import scalalchemy

DATABASE_URL = "sqlite:///db.sqlite"
base_ormar_config = ormar.OrmarConfig(
    metadata=sqlalchemy.MetaData(),
    database=databases.Database(DATABASE_URL),
    engine = sqlalchemy.create_engine(DATABASE_URL),
)

# note que cette étape est optionnelle-> toutes les voitures d'ordre sont un champ avec un nom
# ormar_config #et paramètres propres, mais de cette façon, vous ne pouvez pas avoir à répéter
#les mêmes paramètres si vous utilisez seulement une base de données
#
# Note que tous les type sont optionnels
# below est une déclaration de modèle parfaitement valide
# class Author(modèle ormar):
#     ormar_config = base_ormar_config.copy(tablename="authors")
#
#     id = ormar.Integer(primary_key=True) # <= notice no field types
#     name = ormar.String(max_length=100)


Auteur de classe (modèle ormar):
    ormar_config = base_ormar_config.copy(tablename="authors")

    id: int = ormar.Integer(primary_key=True)
    nom: str = ormar.String(max_length=100)


Classe Book(modèle ormar):
    ormar_config = base_ormar_config.copy(tablename="livres")

    id: int = ormar.Integer(primary_key=True)
    author: Optional[Author] = ormar.ForeignKey(Author)
    title: str = ormar.String(max_length=100)
    année: int = ormar.Integer(nullable=True)


#Créer la base de données
# note que dans la production vous devriez utiliser migrations
# note que ceci n'est pas requis si vous vous connectez à la base de données existante
#Juste pour être sûr, nous avons nettoyé le db avant
base_ormar_config.metadata.drop_all(engine)
base_ormar_config.metadata.create_all(engine)


#toutes les fonctions sont divisées en catégories fonctionnelles
# note comment toutes les fonctions sont définies avec async -la force peut être utilisée avec await AND needs to
#Be awaited sur leur propre
def create():
    # Create some records to work with through QuerySet.create method.
    # Note que la demande est exposée sur la classe de chaque modèle en tant qu 'objets
    tolkien = await Author.objects.create(nom ="J.R.R. Tolkien")
    await Book.objects.create(author=tolkien, title="The Hobbit", year=1937)
    await Book.objects.create(author=tolkien, title="The Lord of the Rings", year=1955)
    await Book.objects.create(author=tolkien, title="The Silmarillion", année =1977)

    #Création alternative d'un objet divisé en 2 étapes
    Sapkowski = Author(nom ="Andrzej Sapkowski")
    # Do some stuff
    await sapkowski.save ()

    #ou save() après initialisation
    await Book(author=sapkowski, title="The Witcher", year=1990).save()
    await Book(author=sapkowski, title="The Tower of Fools", année =2002).save()

    #pour en savoir plus sur l'insertion de données dans la base de données
    # visit: https://collerek.github.io/ormar/queries/create/


async def lire ():
    # Fetch une instance, sans établir une relation clé étrangère sur elle.
    #style Django
    book = await Book.objects.get(title="The Hobbit")
    #ou style python
    book = await Book.objects.get(Book.title == "The Hobbit")
    book2 = await Book.objects.first()

    # first() fetch l'instance avec la valeur clé primaire inférieure
    assert book == book2

    #Vous pouvez accéder à tous les champs sur le modèle loadé
    assert book.title == "Le Hobbit"
    assert book.year == 1937

    #quand aucune condition n'est passée à obtenir ()
    # it behaves as last() based on primary key column
    book3 = await Book.objects.get()
    assert book3.title == "La Tour des Fools"

    #Lorsque vous avez une relation, Ormar définit toujours un modèle relationnel pour vous
    # even when all you loaded is a foreign key value like in this example
    assert isinstance(book.author, Author)
    #clé primaire est populaire à partir d'une clé étrangère conservée dans la table des livres
    assert book.author.pk == 1
    # since the related model was not loaded all other fields are None
    assert book.author.name est None

    #Charger la relation de la base de données lorsque vous avez déjà le modèle lié
    # alternatively see joins section below
    await book.author.load()
    assert book.author.name == "J.R.R. Tolkien"

    #Obtenez toutes les routes pour donner des modèles
    authors = await Author.objects.all()
    assert len(author) == 2

    #pour en savoir plus sur la lecture des données de la base de données
    # visit: https://collerek.github.io/ormar/queries/read/


def update():
    # read existing row from db
    tolkien = await Author.objects.get(nom ="J.R.R. Tolkien")
    assert tolkien.name == "J.R.R. Tolkien"
    tolkien_id = tolkien.id

    #changer la propriété sélectionnée
    tolkien.name = "John Ronald Reuel Tolkien"
    #Appel à mise à jour sur une instance modèle
    await tolkien.update()

    #confirmer que l'objet a été mis à jour
    tolkien = await Author.objects.get(nom ="John Ronald Reuel Tolkien")
    assert tolkien.name == "John Ronald Reuel Tolkien"
    assert tolkien.id == tolkien_id

    #alternativement mettre à jour les données sans loading
    await Author.objects.filter(name__contains="Tolkien").update(name="J.R.R. Tolkien")

    #pour en savoir plus sur updating data in the database
    # visit: https://collerek.github.io/ormar/queries/update/


def delete():
    silmarillion = await Book.objects.get(année =1977)
    # call delete() sur instance
    await silmarillion.delete()

    #alternativement supprimer sans loading.
    await Book.objects.delete(titre ="La Tour des Fools")

    # note que lorsqu 'il n'y avait pas d'exception record de raisins d'ordre NoMatch
    Essayez:
        await Book.objects.get(année =1977)
    Except ormar.NoMatch:
        print("Pas de livre de 1977!")

    #pour en savoir plus sur la transmission des données de la base de données
    # visit: https://collerek.github.io/ormar/queries/delete/

    # note qui dépite le fait qu 'il n'y a pas d'existence longue dans la base de données
    #l'objet au-dessus est encore accessible et vous pouvez l'utiliser (et c'est-à-dire sauver ()) à nouveau.
    tolkien = silmarillion.author
    await Book.objects.create(author=tolkien, title="The Silmarillion", année =1977)


def joins():
    # Tho joins deux modèles avec select_related

    #style Django
    book = await Book.objects.select_related("author").get(title="The Hobbit")
    #style Python
    book = await Book.objects.select_related(Book.author).get(
        Livre.title == "Le Hobbit"
    )

    #Maintenant, l'auteur est déjà préfabriqué
    assert book.author.name == "J.R.R. Tolkien"

    #Par défaut, vous pouvez obtenir un deuxième côté de la relation
    # constructed as lowercase source model name +'s ' (livres dans ce cas)
    #Vous pouvez aussi proposer un nom personnalisé avec parameter related_name

    # Django style
    author = await Author.objects.select_related("livres").all(nom ="J.R.R. Tolkien")
    #style Python
    author = await Author.objects.select_related(Author.books).all(
        Author.name == "J.R.R. Tolkien"
    )
    assert len(author[0].books) == 3

    #pour inverser et beaucoup à beaucoup de relations Vous pouvez aussi bien préférer_related
    #cela exprime une requête séparée pour chaque modèle lié

    # Django style
    author = await Author.objects.prefetch_related("livres").get(nom ="J.R.R. Tolkien")
    #style Python
    author = await Author.objects.prefetch_related(Author.books).get(
        Author.name == "J.R.R. Tolkien"
    )
    assert len(author.books) == 3

    #Pour en savoir plus sur Relations
    # visit: https://collerek.github.io/ormar/relations/

    #Pour en savoir plus sur les jointures et les sous-quêtes
    #visiter: https://collerek.github.io/ormar/queries/joins-and-subqueries/


async def filter_and_sort():
    #pour filtrer la requête Vous pouvez utiliser filter() ou passer la valeur clé par
    # get(), all() etc.
    #utiliser des méthodes spéciales ou accéder à des modèles liés aux champs utilisant le double
    #comprendre comme filtrer par le nom de l'auteur en utilisant author__name
    # Django style
    Livres = await Book.objects.all(author__name="J.R.R. Tolkien")
    #style python
    Livres = await Book.objects.all(Book.author.name == "J.R.R. Tolkien")
    assert len(livres) == 3

    # filter peut accepter les méthodes spéciales aussi séparées avec double underscore
    # to issue sql query ` where authors.name like "%tolkien%"` qui n'est pas
    #cas sensible (hence small t in Tolkien)
    # Django style
    books = await Book.objects.filter(author__name__icontains="tolkien").all()
    #style python
    books = await Book.objects.filter(Book.author.name.icontains("tolkien")).all()
    assert len(livres) == 3

    # to sort use order_by() function of queryset
    #à décréter en utilisant hyphen avant le nom du champ
    # same as with filter Vous pouvez utiliser double underscores pour accéder aux champs liés
    # Django style
    Livres = (
        await Book.objects.filter(author__name__icontains="tolkien")
        .order_by("-année")
        . tout ()
    )
    #style python
    Livres = (
        await Book.objects.filter(Book.author.name.icontains("tolkien"))
        .order_by(Book.year.desc()))
        . tout ()
    )
    assert len(livres) == 3
    assert books[0].title == "Le Silmarillion"
    assert books[2].title == "Le Hobbit"

    #pour en savoir plus sur le filtrage et l'ordonnancement
    # visit: https://collerek.github.io/ormar/queries/filter-and-sort/


async def subset_of_columns():
    #pour exclure certaines colonnes de l'affichage lorsque la base de données est consultée
    #Vous pouvez utiliser la méthode fileds()
    hobbit = await Book.objects.fields(["title"]).get(title="The Hobbit")
    # note que les champs ne sont pas inclus dans les champs sont vides (set to None)
    assert hobbit. année est None
    assert hobbit.author est None

    #Le champ sélectionné est là
    assert hobbit.title == "Le Hobbit"

    #alternativement, vous pouvez proposer des colonnes que vous souhaitez exclure
    hobbit = await Book.objects.exclude_fields(["year"]).get(title="The Hobbit")
    # Year is still not set
    assert hobbit. année est None
    #mais l'auteur est de retour
    assert hobbit.author n'est pas None

    #aussi vous ne pouvez pas exclure la colonne de clé primaire-c'est toujours là
    #même si vous excluez cela, il sera là

    # note que chaque modèle a un shortcut pour primary_key column qui est pk
    #et vous pouvez filtrer/accéder/définir les valeurs par cet alias comme below
    assert hobbit.pk n'est pas None

    # note que vous ne pouvez pas exclure des champs qui ne sont pas nullables
    # (required) dans Définition de modèle
    Essayez:
        await Book. objets.exclude_fields(["title"]).get(title="The Hobbit")
    Except pydantic.ValidationError:
        print(« Cannot exclude non nullable field title »)

    #pour en savoir plus sur la sélection du sous-ensemble des colonnes
    # visit: https://collerek.github.io/ormar/queries/select-columns/


async def pagination():
    #limiter le nombre de routes récupérées en utilisant limit()
    Livres = await Book.objects.limit(1).all()
    assert len(livres) == 1
    assert books[0].title == "Le Hobbit"

    # to offset number of returned rows use offset()
    Livres = await Book.objects.limit(1).offset(1).all()
    assert len(livres) == 1
    assert books[0].title == "Le Seigneur des anneaux"

    #alternativement utiliser paginate qui combine both
    livres = await Book.objects.paginate(page=2, page_size=2).all()
    assert len(livres) == 2
    # note que nous avons supprimé un livre de Sapkowski en supprimant ()
    #et enregistré The Silmarillion -par défaut quand il n'y a pas d'ordre_by est défini
    # ordering sorts by primary_key column
    assert books[0].title == "The Witcher"
    assert books[1].title == "Le Silmarillion"

    #pour en savoir plus sur la pagination et le nombre de rows
    #visiter: https://collerek.github.io/ormar/queries/pagination-and-rows-number/


async def aggregations():
    #Compte:
    assert 2 == await Author.objects.count()

    #existants
    assert await Book.objects.filter(title="The Hobbit").exists()

    # maximum
    assert 1990 == await Book.objects.max(colonnes =["année"])

    # minimum
    assert 1937 == await Book.objects.min(colonnes =["année"])

    #Avec
    assert 1964.75 == await Book.objects.avg(colonnes =["année"])

    #Somme
    assert 7859 == await Book.objects.sum(colonnes =["année"])

    #pour en savoir plus sur les fonctions agrégées
    #visiter: https://collerek.github.io/ormar/queries/aggregations/


async def raw_data()
    # extract raw data sous une forme de dicts ou de tuples
    # note que ceci saute la validation(!) comme les modèles sont
    #pas créé à partir de données partielles

    #Obtenez la liste des objets comme dicts
    assert await Book.objects.values() == [
        {"id": 1, "author": 1, "title": "The Hobbit", "year": 1937},
        {"id": 2, "author": 1, "title": "The Lord of the Rings", "year": 1955},
        {"id": 4, "author": 2, "title": "The Witcher", "year": 1990},
        {"id": 5, "author": 1, "title": "The Silmarillion", "year": 1977},
    ]

    #Obtenez la liste des objets en tant que tuples.
    assert await Book.objects.values_list() = [
        (1, 1, "The Hobbit", 1937),
        (2, 1,« Le Seigneur des anneaux », 1955),
        (4, 2, "The Witcher", 1990),
        (5, 1, "Le Silmarillion", 1977),
    ]

    # filter data - note comment vous pouvez toujours obtenir une liste
    assert await Book.objects.filter(title="The Hobbit").values() == [
        {"id": 1, "author": 1, "title": "The Hobbit", "year": 1937}
    ]

    #Sélectionnez uniquement les champs éveillés
    assert await Book.objects.filter(title="The Hobbit").values(["id", "title"]) == [
        {"id": 1, "title": "The Hobbit"}
    ]

    #Si vous ne sélectionnez qu 'une seule colonne, vous pourriez l'éclater avec des valeurs_list
    assert await Book.objects.values_list("title", flatten=True) == [
        « Le Hobbit »,
        « Le Seigneur des anneaux »
        "Le Witcher",
        "Le Silmarillion",
    ]

    #pour en savoir plus sur les valeurs extractives raw
    # visit: https://collerek.github.io/ormar/queries/aggregations/


async def avec_connect(function):
    # note que pour tout autre arrière-plan que sqlite vous avez actuellement besoin de
    #connecter à la base de données pour permettre les opérations db
    async avec base de donnée:
        fonction await ()

    # note que si vous utilisez le framework comme `fastapi` vous ne vous connectez pas
    #dans vos points finaux, mais avoir un pool de connexions mondial
    # check https://collerek.github.io/ormar/fastapi/ et section avec connexion db


# gather et execute toutes les fonctions
# note -Normalement, l'importation devrait être au début du fichier
Import asyncio

# note que normalement vous utilisez la fonction gather() pour exécuter des fonctions séparées
# concurrently mais nous modifions actuellement les données et nous nous en remettons à l'ordre des fonctions
pour func in [
    Créer,
    lecture,
    update,
    supprimer,
    joins,
    filter_et_sort,
    sous-ensemble_de_colonnes,
    La pagination,
    Aggregations,
    données_raw,
]:
    print(f"Exécuter: {func.__name__}")
    asyncio.run(with

#Drop the Database Tables
drop_all (engine)

Spécifications d'Omar

La méthode Query Set

• create (**kwargs): -> modèle
• get(*args, **kwargs): -> Model
• get_or_none(*args, **kwargs): -> Optional[Model]
• get_or_create(_defaults: Optional[Dict[str, Any]] = None, *args, **kwargs) -> Tuple[Model, bool]
• first(*args, **kwargs): -> Model
• update(each: bool = False, **kwargs) -> int
• update_or_create(**kwargs) -> Model
• bulk_create(objects: List[Model]) -> None
• bulk_update(objects: List[Model], columns: List[str] = None) -> None
• delete(*args, each: bool = False, **kwargs) -> int
• all(*args, **kwargs) -> List[Optional[Model]]
• iterate(*args, **kwargs) -> AsyncGenerator[Model]
• filter(*args, **kwargs) -> QuerySet
• exclude(*args, **kwargs) -> QuerySet
• select_related(related: Union[List, str]) -> QuerySet
• prefetch_related(related: Union[List, str]) -> QuerySet
• limit(limit_count: int) -> QuerySet
• offset(offset: int) -> QuerySet
• count(distinct: bool = True) -> int
• Existence ()-> valeurs booléennes
• max(columns: List[str]) -> Any
• min(columns: List[str]) -> Any
• avg(columns: List[str]) -> Any
• sum(columns: List[str]) -> Any
• fields(columns: Union[List, str, set, dict]) -> QuerySet
• exclude_fields(columns: Union[List, str, set, dict]) -> QuerySet
• order_by(columns:Union[List, str]) -> QuerySet
• values(fields: Union[List, str, Set, Dict])
• values_list(fields: Union[List, str, Set, Dict])

Types de relations

• Un à plusieurs-avec ForeignKey (to: Model)
• Plusieurs à plusieurs-avec ManyToMany(to: Model, Optional[through]: Model)

Type de champ de modèle

Champs de modèle disponibles (avec paramètres obligatoires-optionnels dans la documentation):

• String (longueur maximum)
• Le texte ()
• Valeur booléenne ()
• Entier ()
• flottant ()
• date ()
• Le temps ()
• Date et heure ()
• JSON()
• Grand nombre entier ()
• Petit nombre entier ()
• Décimales (nombre de décimales, précision)
• UUID()
• Grand binaire (longueur maximale)
• Énumération (énumération des classes)
• Énumération similaire à Field-en passant la sélection à tout autre type de champ
• EncryptedString -en passant encrypt_secret et encrypt_backend
• Clés étrangères (to)
• Plusieurs à plusieurs (to)

Options de champ disponibles

Tous les types de champs prennent en charge les paramètres de mots clés suivants.

• Clé primaire: Boolean Value
• Nullable: valeur booléenne
• Par défaut: n'importe quel
• Serveur par défaut: n'importe quel
• Index: Valeur booléenne
• Unique: Boole
• Prénom: STR

Tous les champs sont obligatoires, sauf si l'un des éléments suivants est défini:

• nullable -crée une colonne qui peut être vide. définit la valeur par défaut sur False. pour plus d'informations, lisez Paramètres génériques du champ.
• sql_nullable -Utilisé pour définir des paramètres différents pour pydantic et la base de données. définir la valeur par défaut sur une valeur qui peut être vide. lire les paramètres génériques du champ pour plus de détails.
• Default-Définit la valeur par défaut du champ. ne s'applique pas aux champs relationnels
• server_default -Définit la valeur par défaut d'un champ côté serveur (comme func.now () de sqlalchemy).
• Clé primaire avec incrément automatique-lorsqu 'une colonne est définie comme clé primaire et que l'incrément automatique est défini sur cette colonne. par défaut, la clé primaire int définit l'incrément automatique.

Signaux disponibles

Le signal permet de déclencher votre fonction pour un événement donné sur un modèle donné.

• Pré-sauvegarde
• Après conservation
• Pré-actualisation
• Après la mise à jour
• Pré-supprimé
• Après suppression
• Pré-relation Ajouter
• Post-relation Ajouter
• Suppression de pré-relation
• Après la suppression de la relation