📝 Update README with basic example

tiangolo · tiangolo · commit 58eb5e38ca7e · 2020-05-02T18:43:03.000+02:00
diff --git a/README.md b/README.md
@@ -4,6 +4,93 @@ Tools to generate Pydantic models from SQLAlchemy models.
 
 Still experimental.
 
+## How to use
+
+Quick example:
+
+```Python
+from typing import List
+
+from pydantic_sqlalchemy import sqlalchemy_to_pydantic
+from sqlalchemy import Column, ForeignKey, Integer, String, create_engine
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import Session, relationship, sessionmaker
+
+Base = declarative_base()
+
+engine = create_engine("sqlite://", echo=True)
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    fullname = Column(String)
+    nickname = Column(String)
+
+    addresses = relationship(
+        "Address", back_populates="user", cascade="all, delete, delete-orphan"
+    )
+
+
+class Address(Base):
+    __tablename__ = "addresses"
+    id = Column(Integer, primary_key=True)
+    email_address = Column(String, nullable=False)
+    user_id = Column(Integer, ForeignKey("users.id"))
+
+    user = relationship("User", back_populates="addresses")
+
+
+PydanticUser = sqlalchemy_to_pydantic(User)
+PydanticAddress = sqlalchemy_to_pydantic(Address)
+
+
+class PydanticUserWithAddresses(PydanticUser):
+    addresses: List[PydanticAddress] = []
+
+
+Base.metadata.create_all(engine)
+
+
+LocalSession = sessionmaker(bind=engine)
+
+db: Session = LocalSession()
+
+ed_user = User(name="ed", fullname="Ed Jones", nickname="edsnickname")
+
+address = Address(email_address="ed@example.com")
+address2 = Address(email_address="eddy@example.com")
+ed_user.addresses = [address, address2]
+db.add(ed_user)
+db.commit()
+
+
+def test_pydantic_sqlalchemy():
+    user = db.query(User).first()
+    pydantic_user = PydanticUser.from_orm(user)
+    data = pydantic_user.dict()
+    assert data == {
+        "fullname": "Ed Jones",
+        "id": 1,
+        "name": "ed",
+        "nickname": "edsnickname",
+    }
+    pydantic_user_with_addresses = PydanticUserWithAddresses.from_orm(user)
+    data = pydantic_user_with_addresses.dict()
+    assert data == {
+        "fullname": "Ed Jones",
+        "id": 1,
+        "name": "ed",
+        "nickname": "edsnickname",
+        "addresses": [
+            {"email_address": "ed@example.com", "id": 1, "user_id": 1},
+            {"email_address": "eddy@example.com", "id": 2, "user_id": 1},
+        ],
+    }
+```
+
 ## License
 
 This project is licensed under the terms of the MIT license.
