Metadata-Version: 2.1
Name: detaorm
Version: 0.3.0
Summary: An async ORM for DetaBase.
License: MIT
Author: CircuitSacul
Author-email: circuitsacul@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Dist: aiohttp (>=3.8.1,<4.0.0)
Description-Content-Type: text/markdown

# DetaORM
An async ORM for [DetaBase](https://docs.deta.sh/docs/base/about/).

[Support](https://discord.gg/dGAzZDaTS9) | [PyPI](https://pypi.org/project/detaorm)

## Example Usage
Here's some examples of DetaORM, with commentary. I'll add real documentation at some point.

```py
from detaorm import Client, Base, Field


# create your base(s) (or models)
class User(Base, name="users"):
    # name is the name of your base. If left empty, it will
    # default to the lowered name of the class ("user" in
    # this case.)

    # all bases have a `key` field already.

    # typehints are optional. You could write this instead:
    # username = Field()
    username: Field[str] = Field()
    nicknames: Field[list[str]] = Field()


# create the client
# you have to list the bases when creating the client to
# allow the client to setup properly.
client = Client("<project key>", bases=[User])
# If you don't specify a project key, DetaORM will try to
# get a project key from the environment, which means that
# you don't need to specify a project keys when running
# your app with Deta Micros.

# actual usage:
new_user = User(username="CircuitSacul")

# all fields are optional, but they will raise a KeyError
# if you try to access them.
# The following line will raise a KeyError
new_user.nicknames

# to actually create the user, you have to call .insert():
created_user = await new_user.insert()
# created_user and new_user will be identical

# to update an item:
updated_user = await new_user.update(
    User.nicknames.set(["circuit"])
)
print(updated_user)
# > User({"key": ..., "username": "CircuitSacul", "nicknames": ["Awesome Person"]})
updated_user = await updated_user.update(
    User.nicknames.append(["sacul"])
)
print(updated_user)
# > User({"key": ..., "username": "CircuitSacul", "nicknames": ["circuit", "sacul"]})

# updated_user and new_user will be different now.
# DetaORM sends the query to DetaBase, but also tries
# to determine the updated value and returns a new item.
print(new_user)
# > User({"key": ..., "username": "CircuitSacul"]})

# you can also use Base.insert_many to insert up to 25 items:
await User.insert_many([
    User(username="BatMan", nicknames=["superhero"]),
    User(username="SuperMan", nicknames=["superhero"]),
])

# The easiest way to query items is with .where():
async for page in await User.where(User.nicknames.contains("superhero")):
    for user in page.items:
        print(user)
# > User({"key": ..., "username": "BatMan", "nicknames": ["superhero"]})
# > User({"key": ..., "username": "SuperMan", "nicknames": ["superhero"]})
```

