オーマー

概要

ormarパッケージはPythonの非同期ORMで、Postgres、My SQL、SQLiteをサポートしています。

ormarを使用する主な利点は次のとおりです。

• 非同期フレームワーク（fastapi、starletteなど）で使用できる非同期ORMを取得します
• は1つのモデルのみを維持します。pydanticや他のormモデル（sqlalchemy、peewee、ginoなど）を維持する必要はありません

目標は、pydanticベースのデータ検証のfastapiで直接使用できるシンプルなORMを作成することです（リクエストとレスポンスのモデルとして）。

Ormar-名前の中で明らかな「ORM」に加えて、その名前はスウェーデン語で蛇を意味するormarと、クロアチア語で内閣を意味するormar(e)に由来している。

Python ORMにとって、スネークキャビネットよりも優れた名前は何ですか:)

ormarが好きな場合は、ギットハブのリポジトリにスターを付けることを忘れないでください。

私たちが作ったコミュニティが大きいほど、間違いを発見し、貢献者を惹きつけやすい

ドキュメント

詳細については、ドキュメントを参照してください。

簡潔にするために、ほとんどのドキュメントセグメントでは、データベースの作成と非同期実行関数の実行のスケジューリングが省略されていることに注意してください。

ドキュメントよりも多くの実際の例が必要な場合は、ほとんどのテストで実際に作成してデータベースに接続する必要があるため、テストフォルダーを確認できます。

ただし、これらは単なるテストであり、すべてのソリューションが実際の使用に適しているわけではないことに注意してください。

fastapiエコシステムの一部

fastapiエコシステムの一部として、ormarはデータベースと何らかの方法で動作する選択されたライブラリでサポートされています。

OrmarはまだSQL方言とは関係がないため、サポートされているすべてのバックエンドで動作する列のみが実装されます。

ormarの拡張として、特定の方言の列を実装することは比較的簡単です。

Postgresの特定の列の実装:ormar-postgres-extensions

別のライブラリを維持または使用していて、ormarをサポートしたい場合は、どのように役立つか教えてください。

依存関係

Ormarの構築には以下が含まれます:

• クエリを構築するためのsqlalchemyコア。
• データベース間の非同期サポート用のデータベース。
• pydanticはデータ検証に使用されます。

ライセンス

ormarはオープンソースソフトウェアとして構築されており、完全に無料（MITライセンス）のままです。

私が仕事の日々の問題を解決したり、強力なPythonコミュニティを促進して構築したりするためにオープンソースコードを書くときは、私の仕事が無料で維持されていることを確認するために、感謝してコーヒーを買ったり、毎月私に資金を提供したりすることができます。

スポンサー

sqlalchemyと既存のデータベースからの移行

現在sqlalchemyを使用していて、ormarに切り替えたい場合は、既存のsqlalchemy ormモデルを手動で翻訳するのに役立つ自動翻訳ツールを確認してください。

ベータ版はギットハブで見つけることができます: sqlalchemy-toormarまたは単に pip install sqlalchemy-to-ormar

sqlalchemy-to-ormarをsqlacodegenと組み合わせて使用すると、プロジェクトがsqlalchemyを使用していなくても、既存のデータベースからormarモデルを自動的にマッピング/生成できます。

移行とデータベースの作成

ormarはSQLAlchemyコアに基づいて構築されているため、alembicを使用してデータベース移行を提供できます（本番コードの場合は実際に行う必要があります）。

テストと基本的なアプリケーションでは、sqlalchemyで十分です。

#これは以下の部分的なスニペットの完全な作業例に過ぎないことに注意してください。
#1.インポート
sqlalchemyをインポート
データベースのインポート
インポートまたは

#2.初期化
DATABASE_URL="sqlite:///db. sqlite"
base_ormar_config=ormar. OrmarConfig(ベースの設定
    metadata=sqlalchemy. MetaData(),
    データベース=データベース。データベース(DATABASE_URL)、
    engine=sqlalchemy. create_engine(DATABASE_URL),
)

#ここでモデルを定義する

#3。データベースの作成とテーブルの作成
base_or_config. metadata.create_all(エンジン)

alembicの構成例、および移行とデータベース作成の詳細については、移行ドキュメントのセクションを参照してください。

パッケージバージョン

Ormarはまだ開発中です:依存関係を固定することをお勧めします（つまり、ormar~=0.9.1）

ormarもリリース番号に従います。つまり、大きな変更はプライマリバージョン番号を追加し、他の変更や修正はマイナーバージョン番号を追加します。後者については、安全に更新できるはずですが、必ず最初にリリースドキュメントを読んでください。example: (0.5.2 -> 0.6.0 - breaking, 0.5.2 -> 0.5.3 - non breaking)。

非同期Python

ormarは非同期ORMであることに注意してください。つまり、イベントループで実行する予定のメソッドの呼び出しを待つ必要があります。Pythonには、これを実行できるモジュールasyncioが組み込まれています。

ほとんどの「通常の」Pythonインタプリタでは、関数の外側でwaitを実行できないことに注意してください（実際には、この関数を遅延させて実行するようにスケジュールし、すぐに結果を取得しないため）。

fastapiなどの最新のWebフレームワークでは、フレームワークがこの問題を処理しますが、自分で実行する場合は、以下のクイックスタートで説明するように、手動で実行する必要があります。

クイックスタート

同じスクリプトがギットハブのサンプルフォルダにあることに注意してください。

入力からインポートオプション

データベースのインポート

インポートまたは
sqlalchemyをインポート

DATABASE_URL="sqlite:///db. sqlite"
base_ormar_config=ormar. OrmarConfig(ベースの設定
    metadata=sqlalchemy. MetaData(),
    データベース=データベース。データベース(DATABASE_URL)、
    engine=sqlalchemy. create_engine(DATABASE_URL),
)

#このステップはオプションであることに注意してください->すべてのormar caresは名前のフィールドです
#ormer_config#と適切なパラメータですが、この方法では繰り返す必要はありません。
#データベースを1つだけ使用する場合は、同じパラメータ
#
#すべてのタイプヒントはオプションであることに注意してください。
#以下は完全に有効なモデル宣言です。
#class Author(ormar. Model):
#ormer_config=base_ormer_config. copy(tablename="著者")
#
#id=ormar. Integer（プライマリキー=True）#<=フィールドタイプがないことに注意してください
#name=ormar. String(max_length=100)


class Author(ormar. Model):
    or_config=base_or_config. copy(tablename="著者")

    id: int=ormar.Integer(プライマリキー=True)
    name: str=ormar.String(max_length=100)


class Book(ormar. Model):
    or_config=base_or_config. copy(tablename="books")

    id: int=ormar.Integer(プライマリキー=True)
    著者:オプション[著者]=ormar. ForeignKey(著者)
    title: str=ormar.String(max_length=100)
    year: int=ormar.Integer(nullable=True)


#データベースを作成する
#本番環境ではマイグレーションを使用する必要があることに注意してください
#既存のデータベースに接続する場合は、これは必要ありません。
#前にDBをクリアしたことを確認するために
base_or_config. metadata.drop_all(エンジン)
base_or_config. metadata.create_all(エンジン)


#以下のすべての機能は、機能カテゴリに分かれています。
すべての関数がasyncで定義されていることに注意してください。
#自分で待つ
async def create():
    QuerySet. createメソッドを使用して、作業するレコードを作成します。
    #クエリセットは各モデルのクラスでオブジェクトとして公開されることに注意してください。
    tolkien=await Author. object.create(name="J.R.R.Tolkien")
    await Book. object.create(著者=tolkien,タイトル="ホビット",年=1937)
    await Book. object.create(著者=tolkien,タイトル="The Lord of the Rings",年=1955)
    await Book. object.create(著者=tolkien,タイトル="The Silmarillion",年=1977)

    #2つのステップに分かれたオブジェクトの代替作成
    sapkowski=著者(name="Andrzej Sapkowski")
    #何かをする
    Waitsapkowski.save()

    #または初期化後にsave()
    await Book(Author=sapkowski, title="The Witcher",year=1990).save()
    await Book(Author=sapkowski, title="The Tower of Fools",year=2002).save()

    #データベースへのデータの挿入の詳細を読む
    #訪問:https://collerek.github.io/ormar/queries/create/


async def read():
    外部キーリレーションシップを読み込まずにインスタンスを取得します。
    #ジャンゴスタイル
    book=await Book. object.get(title="ホビット")
    #またはPythonスタイル
    book=await Book. object.get(Book.title=="ホビット")
    book 2=await Book. object.first()

    #first()プライマリキーの値が低いインスタンスを取得する
    book 2をアサートする

    #ロードされたモデルのすべてのフィールドにアクセスできます。
    assert book. title=="ホビット"
    book. yearをアサートする==1937

    #get()に条件が渡されない場合
    #主キーカラムに基づいてlast()として動作します
    book 3=await Book. object.get()
    assert book 3. title=="愚者の塔"

    #関係がある場合、ormarは常に関連するモデルを定義します。
    #この例のように、ロードしたものがすべて外部キー値であっても
    isinstanceをアサート(book.author, Author)
    #主キーは、ブックテーブルに保存されている外部キーから入力されます。
    アサートbook.author.pk==1
    #関連するモデルがロードされなかったため、他のすべてのフィールドはNoneです。
    アサートbook.author.nameはなし

    #関連するモデルがすでにある場合に、データベースからリレーションシップを読み込む
    #あるいは、以下のジョインセクションを参照してください。
    waitbook.author. load()
    assertbook.author.name=="J. R.R.トールキン"

    #与えられたモデルのすべての行を取得する
    Author=await Author. object.all()
    assert len(著者)==2

    #データベースからのデータの読み取りについての詳細を読む
    #訪問:https://collerek.github.io/ormar/queries/read/


async def update():
    #dbから既存の行を読み込む
    tolkien=await Author. object.get(name="J.R.R.Tolkien")
    asserttolkien.name=="J. R.R.トールキン"
    Torkien_id=tolkien.id

    #選択したプロパティを変更する
    tolkien.nameジョン・ロナルド・ロイエル・トールキン（John Ronald Reuel Tolkien）
    #モデルインスタンスの更新を呼び出す
    ページを更新()

    #オブジェクトが更新されたことを確認する
    tolkien=await Author. object.get(name="John Ronald Reuel Tolkien")
    ジョンtolkien.name・ロイエル・トールキン（John Ronald Reuel Tolkien）
    アサートtolkien.id==tolkien_id

    #代わりにロードせずにデータを更新する
    await Author. object.filter(name__include="Tolkien").update(name="J.R.R.Tolkien")

    #データベース内のデータの更新の詳細を読む
    #訪問:https://collerek.github.io/ormar/queries/update/


async def delete():
    silmarillion=await Book. object.get(year=1977)
    #インスタンスでdelete()を呼び出す
    silmarillionを待ちます。delete()

    #代わりに読み込まずに削除する
    await Book. object.delete(title="愚者の塔")

    レコードormarがない場合、NoMatch例外が発生することに注意してください。
    トライ:
        await Book. object.get(年=1977)
    ormar. NoMatchを除いて:
        print("1977年の本はありません!")

    #データベースからのデータ削除の詳細を読む
    #訪問:https://collerek.github.io/ormar/queries/delete/

    #レコードがデータベースに存在しなくなったにもかかわらず
    上記のオブジェクトはまだアクセス可能で、再度使用できます（そしてsave()）。
    Torkien=silmarillion.author
    await Book. object.create(著者=tolkien,タイトル="The Silmarillion",年=1977)


async def join s():
    #2つのモデルを結合してselect_関連を使用する

    #ジャンゴスタイル
    book=await Book. object.select_関連("著者").get(title="ホビット")
    #Pythonスタイル
    Book=await Book. object.select_Book.author().get(
        Book. title=="ホビット"
    )

    #今、著者はすでに先取りされています
    assertbook.author.name=="J. R.R.トールキン"

    #デフォルトでは、リレーションの2番目の側面も取得します。
    #小文字のソースモデル名+'s'（この場合は書籍）として構築
    #パラメータ関連名でカスタム名を提供することもできます。

    #ジャンゴスタイル
    著者=await著者.オブジェクト.選択関連("books"). all(name="J.R.R.トールキン")
    #Pythonスタイル
    Author=await Author. object.select_関連(Author.books).all(
        Author.name=="J. R.R.トールキン"
    )
    assert len（著者[0]. books）==3

    #リバースと多対多の関係については、prefetch_関連することもできます。
    #関連するモデルごとに個別のクエリを実行する

    #ジャンゴスタイル
    著者=await著者.オブジェクト. prefetch_関連("books").get(name="J.R.R.トールキン")
    #Pythonスタイル
    Author=await Author. object.prefetch_関連(Author.books).get(
        Author.name=="J. R.R.トールキン"
    )
    assert len(Author. books)==3

    #関係についてもっと読む
    #訪問:https://collerek.github.io/ormar/relations/

    #ジョインとサブクエリの詳細を読む
    #訪問:https://collerek.github.io/ormar/queries/joins-and-subqueries/


async def filter_and_sort():
    #クエリをフィルタリングするには、filter()を使用するか、キー値パーを渡すことができます。
    #get()、all()など。
    #特別なメソッドを使用したり、関連するモデルフィールドにアクセスしたりするには、ダブルを使用します。
    #アンダースコア著者の名前でフィルタリングするのが好き著者__nameを使用
    #ジャンゴスタイル
    books=await Book. object.all(Author__name="J.R.R.Tolkien")
    #Pythonスタイル
    books=await Book. object.all(Book.author.name=="J.R.R.Tolkien")
    len(books)==3をアサートする

    #フィルターは、ダブルアンダースコアで区切られた特別なメソッドも受け入れることができます。
    #sqlクエリ ` where authors.name like "%tolkien%"` を発行する
    #ケースセンシティブ（したがってトールキンでは小さなt）
    #ジャンゴスタイル
    books=await Book. object.filter(Author__name__icontains="tolkien").all()
    #Pythonスタイル
    books=await Book. object.filter(Book.author.nameicontains("tolkien")).all()
    len(books)==3をアサートする

    #querysetのorder_by()関数を使ってソートする
    #フィールド名の前にハイフンを使う
    #フィルターと同じように、ダブルアンダースコアを使って関連するフィールドにアクセスすることができます。
    #ジャンゴスタイル
    本=(
        await Book. object.filter(Author__name__icontains="tolkien")
        . order_by("-year")
        . all()
    )
    #Pythonスタイル
    本=(
        Book. object.filter(Book.author.nameicontains("tolkien"))を待つ
        . order_by(Book.year.desc())
        . all()
    )
    len(books)==3をアサートする
    assert books[0]. title=="シルマリオン"
    assert books[2]. title=="ホビット"

    #フィルタリングと注文についてもっと読む
    #訪問:https://collerek.github.io/ormar/queries/filter-and-sort/


async def subset_of_column():
    #データベースをクエリする際に、一部の列を読み込みから除外する
    #fileds()メソッドを使用できます
    hobbit=await Book. object.field(["title"]).get(title="The Hobbit")
    #フィールドに含まれていないフィールドが空であることに注意してください（Noneに設定）
    assert hobbit. year isなし
    アサートhobbit.authorはなし

    #選択されたフィールドがあります
    assert hobbit. title=="The Hobbit"

    #あるいは、除外したい列を提供することもできます。
    hobbit=awaitブック。オブジェクト。除外フィールド(["年"])。get(タイトル="ホビット")
    #年はまだ設定されていません
    assert hobbit. year isなし
    #しかし、著者は戻ってきました
    アサートhobbit.authorはなし

    #また、主キー列を除外することはできません-常にそこにあります
    #明示的に除外してもそこにある

    #各モデルには、pkであるプライマリキー列のショートカットがあることに注意してください。
    #以下のように、このエイリアスで値をフィルタリング/アクセス/設定することができます。
    アサートhobbit.pkはなし

    #nullableでないフィールドを除外できないことに注意してください
    #(必須)モデル定義
    トライ:
        awaitブック.オブジェクト.除外フィールド(["タイトル"]). get(タイトル="ホビット")
    pydantic. ValidationErrorを除いて:
        print("Nullableでないフィールドタイトルを除外できません")

    #列のサブセットの選択についてもっと読む
    #訪問:https://collerek.github.io/ormar/queries/select-columns/


async def pagination():
    返される行数を制限するにはlimit()を使用します
    books=await Book. object.limit(1).all()
    len(books)==1をアサートする
    assert books[0]. title=="ホビット"

    返される行の数をオフセットするには、off set()を使用します。
    books=await Book. object.limit(1).off set(1).all()
    書籍の長さ==1
    assert books[0]. title=="ロード・オブ・ザ・リング"

    #あるいは、両方を組み合わせたpaginateを使う
    books=await Book. object.paginate(page=2,page_size=2).all()
    書籍の長さ==2
    delete()でSapkowskiの本を1冊削除しました。
    #とSilmarillionを再作成しました-order_byが設定されていない場合のデフォルト
    #プライマリキーカラムでソートを並べ替える
    assert books[0]. title=="The Witcher"
    書籍を主張する[1]. title=="シルマリオン"

    #ページネーションと行数についてもっと読む
    #訪問:https://collerek.github.io/ormar/queries/pagination-and-rows-number/


async defアグリゲーション():
    #カウント:
    assert 2==await Author. object.count()

    #存在する
    assert await Book. object.filter(title="The Hobbit").プレゼンス()

    #最大
    assert 1990==awaitブック.オブジェクト. max(列=["年"])

    #最小
    assert 1937==awaitブック.オブジェクト. min(列=["年"])

    #平均
    assert 1964.75==awaitブック.オブジェクト. avg(列=["年"])

    #合計
    assert 7859==await Book. object.sum(column=["year"])

    #集約関数についてもっと読む
    #訪問:https://collerek.github.io/ormar/queries/aggregations/


async def raw_data():
    #ディクトやタプルの形で生データを抽出する
    #これはモデルの検証(!)をスキップすることに注意してください。
    #解析済みデータから作成されない

    #オブジェクトのリストをdictsとして取得する
    assert await Book. object.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},
    ]

    #オブジェクトのリストをタプルとして取得する
    assert await Book. object.values_list()==[
        (1,1,「ホビット」,1937),
        『指輪物語』The Lord of the Rings(1955)
        (4,2,「ウィッチャー」,1990),
        (5,1,「シルマリリオン」,1977),
    ]

    #フィルターデータ-常にリストを取得する方法に注意してください
    assert await Book. object.filter(title="The Hobbit").values()==[
        {"id": 1, "author": 1, "title": "The Hobbit", "year": 1937}
    ]

    必要なフィールドのみを選択
    assert await Book. object.filter(title="The Hobbit").values(["id","title"])==[
        {"id": 1, "title": "The Hobbit"}
    ]

    #1つの列だけを選択すると、value_listで平らにすることができます。
    assert await Book. object.values_list("title",flatten=True)==[
        『ホビット』The Hobbit
        『指輪物語』The Lord of the Rings
        『ウィッチャー』The Witcher
        『シルマリリオン』The Silmarillion
    ]

    #生の値の抽出についてもっと読む
    #訪問:https://collerek.github.io/ormar/queries/aggregations/


async def with_connect(function):
    #sqlite以外のバックエンドでは、実際に
    #データベースに接続してDB操作を行う
    データベースと非同期:
        await関数()

    `fastapi` のようなフレームワークを使用する場合は、接続しないでください。
    #エンドポイントにグローバル接続プールがある
    #DB接続でhttps://collerek.github.io/ormar/fastapi/とセクションを確認する


#すべての関数を集めて実行する
#note-通常、インポートはファイルの先頭にする必要があります
インポートasyncio

#通常、いくつかの関数を実行するためにギャザー()関数を使用することに注意してください。
#同時に、実際にデータを変更し、関数の順序に依存します。
funcについて[
    作成、
    読む、
    アップデート、
    削除、
    参加、
    フィルタとソート,
    サブセット_of_列,
    ページネーション,
    集計,
    生データ,
]:
    print(f"実行中:{func.__name__}")
    asyncio.run(with_connect(func))

#データベーステーブルをドロップする
metadata. drop_all(エンジン)

オマール仕様

クエリセットメソッド

• 作成(**kwargs):->モデル
• 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
• 存在()->ブール値
• 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])

関係の種類

• 1対多-ForeignKey(to: Model)を使用する
• 多対多-と ManyToMany(to: Model, Optional[through]: Model)

モデルフィールドタイプ

使用可能なモデルフィールド(必須パラメーター-ドキュメント内のオプションパラメーター):

• 文字列(最大長)
• テキスト（）
• ブール値()
• 整数()
• 浮遊（）
• 日付（）
• 時間（）
• 日付と時刻()
• JSON()
• 大きな整数()
• 小さい整数()
• 小数（小数の桁数、精度）
• UUID()
• ビッグバイナリ（最大長）
• 列挙型(列挙型クラス)
• Fieldと同様の列挙-選択を他のFieldタイプに渡すことによって
• EncryptedString-暗号化された_secretと暗号化された_backendを渡すことによって
• 外部キー(へ)
• 多対多（へ）

利用可能なフィールドオプション

次のキーワードパラメーターは、すべてのフィールドタイプでサポートされています。

• プライマリキー:ブール値
• 空:ブール値
• デフォルト:任意
• サーバのデフォルト:任意
• インデックス:ブール値
• 唯一:ブール
• 名前: str

次のいずれかが設定されていない限り、すべてのフィールドが必須です。

• nullable-空の列を作成します。デフォルト値をFalseに設定します。詳細については、フィールドの共通パラメータをお読みください。
• sql_nullable-pydanticとデータベースの異なる設定を行うために使用されます。デフォルト値を空にすることができる値に設定します。詳細については、フィールドの共通パラメータをお読みください。
• デフォルト-フィールドのデフォルト値を設定します。リレーショナルフィールドには適用されません
• server_default-サーバーサイドフィールドのデフォルト値を設定します(sqlalchemyのfunc.now()など)。リレーショナルフィールドには適用されません
• 自動増分付きプライマリキー-カラムがプライマリキーに設定され、そのカラムに自動増分が設定されている場合。デフォルトでは、intプライマリキーは自動増分を設定します。

利用可能な信号

シグナルを使用すると、特定のモデル上の特定のイベントに対して関数をトリガーできます。

• 事前保存
• 保存後
• プレアップデート
• 更新後
• 事前削除
• 削除後
• 事前リレーションシップの追加
• 関係を追加した後
• 事前リレーションシップの削除
• 関係を削除した後