| Name | coraline JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Use Pydantic Models to handle AWS DynamoDB tables |
| upload_time | 2024-10-09 22:23:42 |
| maintainer | None |
| docs_url | None |
| author | Chris Maillefaud |
| requires_python | <4,>=3.11 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## Welcome to Coraline
Coraline is a Python library that aims to use Pydantic models to work with AWS DynamoDB tables.
### Install
```shell
$ pip install coraline
```
Coraline needs `boto3` to work. If you don't have it installed, you can install it using:
```shell
$ pip install coraline[boto]
```
---
### Documentation
* TODO
---
### Quick Start:
```python
import uuid
from enum import Enum
from coraline import CoralModel, KeyField, HashType
from pydantic import SecretStr, Field
class UserType(Enum):
USER = "USER"
ADMIN = "ADMIN"
class Users(CoralModel):
user_id: uuid.UUID = KeyField(default=lambda: uuid.uuid4(), hash_key=HashType.HASH, alias="userId")
user_type: UserType = KeyField(..., hash_type=HashType.RANGE, alias="userType")
name: str
age: int = Field(..., gt=0)
password: SecretStr
Users.get_or_create_table()
new_user = Users(name="John Doe", user_type=UserType.USER, age=30, password="123456")
new_user.save()
```
This class will create a DynamoDB table named `Users`, with `PAY_PER_REQUEST` billing mode and using default AWS
session, with the following fields:
* `userId` as a String. It's the Table's Hash Key.
* `userType` as a String. It's the Table's Range Key.
* `name` as a String
* `email` as a Number
* `password` as a String
### Configuring the table
Use the `CoralConfig` class to configure your table.
```python
import uuid
from enum import Enum
from coraline import CoralModel, KeyField, HashType, CoralConfig, BillingMode, TableClass
from pydantic import SecretStr, Field
class UserType(Enum):
USER = "USER"
ADMIN = "ADMIN"
def to_camel(string: str) -> str:
return ''.join(word.capitalize() for word in string.split('_'))
# CoralModel is a subclass of Pydantic's BaseModel
class Users(CoralModel):
# CoralConfig is a subclass of Pydantic's ConfigDict
model_config = CoralConfig(
table_name="MyUsers",
billing_mode=BillingMode.PROVISIONED,
read_capacity_units=5,
write_capacity_units=5,
alias_generator=to_camel,
protect_from_exclusion=True,
table_class=TableClass.STANDARD_INFREQUENT_ACCESS,
extra_table_params={
"Tags": [
{
"Key": "Project",
"Value": "MyProject"
}
]
}
)
# KeyField is a sub method of Pydantic's Field
user_id: uuid.UUID = KeyField(default=lambda: uuid.uuid4(), hash_key=HashType.HASH)
user_type: UserType = KeyField(..., hash_type=HashType.RANGE)
name: str
age: int = Field(..., gt=0)
password: SecretStr
```
For Table Name, Billing Methods, you can use the `BillingMode` and Capacity Units constants. For any other parameter
accepted by `boto3`'s `create_table` use the `extra_table_params` parameter.
---
### Configuring AWS Credentials
To configure boto3's client credentials, Coraline will:
1. Check for Class specific configuration in `model_config`
2. Check for Coraline Environment Variables (
ex. `CORALINE_AWS_REGION`, `CORALINE_AWS_ACCESS_KEY_ID`, `CORALINE_AWS_SECRET_ACCESS_KEY`)
3. Check for AWS Environment Variables (ex. `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
#### Env Example:
```dotenv
# Add to .env file:
AWS_REGION="local"
CORALINE_ENDPOINT_URL="http://localhost:8000"
```
#### Class Example:
```python
from coraline import CoralModel, CoralConfig
class Users(CoralModel):
model_config = CoralConfig(
aws_region="local",
aws_endpoint_url="http://localhost:8000"
)
```
#### Class Example using Boto3 Config instance:
```python
from botocore.config import Config
from coraline import CoralModel, CoralConfig
config = Config(
region_name="local",
endpoint_url="http://localhost:8000"
)
class Users(CoralModel):
model_config = CoralConfig(
aws_region="local",
aws_config=config
)
```
---
### Basic Operations
#### Get or Create Table
Use to get Table info or create the table if it doesn't exist.
```python
table_description: dict = Users.get_or_create_table()
```
#### Get Table Info
Use to get Table info. You can also add boto's client `describe_XXX` methods here, for any describe operation which does not have signature
or the only argument is the TableName:
* Allowable Descriptions Example: `describe_continuous_backups`, `describe_time_to_live`, `descript_limits`, etc...
* Not Allowable Descriptions Example: `describe_backup`, `describe_global_table`, `describe_export`, etc...
```python
table_info: dict = Users.get_table_info(include=["describe_time_to_live"])
```
#### Check if Record exists
Use to check if a record exists in the table. You need to pass on the parameters all hash and range keys defined in Model:
```python
user_exists: bool = Users.exists(user_id="12345678-1234-1234-1234-123456789012", user_type=UserType.USER)
```
#### Get Record
Use to get a record from the table. You need to pass on the parameters all hash and range keys defined in Model:
```python
user: Users = Users.get(user_id="12345678-1234-1234-1234-123456789012", user_type=UserType.USER)
```
#### Save Record
Use to save a record in the table:
```python
new_user = Users(name="John Doe", user_type=UserType.USER, age=30, password="123456")
new_user.save()
```
### Using boto3's Client
You can use boto3's client to perform any operation you need. Just use the `get_client` method:
```python
new_user = Users(name="John Doe", user_type=UserType.USER, age=30, password="123456")
new_user.save()
new_user.get_client().create_backup(
TableName=new_user.table_name(), # or Users.get_table_name()
BackupName="MyBackup"
)
```
---
### Current Project Status
Current status: In Progress
We strong advise to not use this lib in Production projects at this current stage.
Except bugs and breaking changes between each release.
### Future Implementations
* Add option to "update" tables (`create_or_update_table` method)
* Add native support for Global and Local Secondary Indexes
* Add native support for Query operations
* Add native support for TransactWriteItems and TransactGetItems
* Add native support for BatchWriteItems and BatchGetItems
---
### Not working?
Don't panic. Get a towel and, please, open an
[issue](https://github.com/megalus/coraline/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "coraline",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Chris Maillefaud",
"author_email": "chrismaille@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/0e/07/a8b0eb171737d8e08bdffee59dc15786bd6c7f959d99203e435389d71c4b/coraline-1.0.0.tar.gz",
"platform": null,
"description": "## Welcome to Coraline\n\nCoraline is a Python library that aims to use Pydantic models to work with AWS DynamoDB tables.\n\n### Install\n\n```shell\n$ pip install coraline\n```\n\nCoraline needs `boto3` to work. If you don't have it installed, you can install it using:\n\n```shell\n$ pip install coraline[boto]\n```\n\n---\n\n### Documentation\n\n* TODO\n\n---\n\n### Quick Start:\n\n```python\nimport uuid\nfrom enum import Enum\nfrom coraline import CoralModel, KeyField, HashType\nfrom pydantic import SecretStr, Field\n\n\nclass UserType(Enum):\n USER = \"USER\"\n ADMIN = \"ADMIN\"\n\n\nclass Users(CoralModel):\n user_id: uuid.UUID = KeyField(default=lambda: uuid.uuid4(), hash_key=HashType.HASH, alias=\"userId\")\n user_type: UserType = KeyField(..., hash_type=HashType.RANGE, alias=\"userType\")\n name: str\n age: int = Field(..., gt=0)\n password: SecretStr\n\n\nUsers.get_or_create_table()\nnew_user = Users(name=\"John Doe\", user_type=UserType.USER, age=30, password=\"123456\")\nnew_user.save()\n```\n\nThis class will create a DynamoDB table named `Users`, with `PAY_PER_REQUEST` billing mode and using default AWS\nsession, with the following fields:\n\n* `userId` as a String. It's the Table's Hash Key.\n* `userType` as a String. It's the Table's Range Key.\n* `name` as a String\n* `email` as a Number\n* `password` as a String\n\n### Configuring the table\n\nUse the `CoralConfig` class to configure your table.\n\n```python\nimport uuid\nfrom enum import Enum\nfrom coraline import CoralModel, KeyField, HashType, CoralConfig, BillingMode, TableClass\nfrom pydantic import SecretStr, Field\n\n\nclass UserType(Enum):\n USER = \"USER\"\n ADMIN = \"ADMIN\"\n\n\ndef to_camel(string: str) -> str:\n return ''.join(word.capitalize() for word in string.split('_'))\n\n\n# CoralModel is a subclass of Pydantic's BaseModel\nclass Users(CoralModel):\n # CoralConfig is a subclass of Pydantic's ConfigDict\n model_config = CoralConfig(\n table_name=\"MyUsers\",\n billing_mode=BillingMode.PROVISIONED,\n read_capacity_units=5,\n write_capacity_units=5,\n alias_generator=to_camel,\n protect_from_exclusion=True,\n table_class=TableClass.STANDARD_INFREQUENT_ACCESS,\n extra_table_params={\n \"Tags\": [\n {\n \"Key\": \"Project\",\n \"Value\": \"MyProject\"\n }\n ]\n }\n )\n\n # KeyField is a sub method of Pydantic's Field\n user_id: uuid.UUID = KeyField(default=lambda: uuid.uuid4(), hash_key=HashType.HASH)\n user_type: UserType = KeyField(..., hash_type=HashType.RANGE)\n name: str\n age: int = Field(..., gt=0)\n password: SecretStr\n```\n\nFor Table Name, Billing Methods, you can use the `BillingMode` and Capacity Units constants. For any other parameter\naccepted by `boto3`'s `create_table` use the `extra_table_params` parameter.\n\n---\n\n### Configuring AWS Credentials\n\nTo configure boto3's client credentials, Coraline will:\n\n1. Check for Class specific configuration in `model_config`\n2. Check for Coraline Environment Variables (\n ex. `CORALINE_AWS_REGION`, `CORALINE_AWS_ACCESS_KEY_ID`, `CORALINE_AWS_SECRET_ACCESS_KEY`)\n3. Check for AWS Environment Variables (ex. `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)\n\n#### Env Example:\n```dotenv\n# Add to .env file:\nAWS_REGION=\"local\"\nCORALINE_ENDPOINT_URL=\"http://localhost:8000\"\n```\n\n#### Class Example:\n```python\nfrom coraline import CoralModel, CoralConfig\n\nclass Users(CoralModel):\n model_config = CoralConfig(\n aws_region=\"local\",\n aws_endpoint_url=\"http://localhost:8000\"\n )\n```\n\n#### Class Example using Boto3 Config instance:\n```python\nfrom botocore.config import Config\nfrom coraline import CoralModel, CoralConfig\n\nconfig = Config(\n region_name=\"local\",\n endpoint_url=\"http://localhost:8000\"\n)\n\nclass Users(CoralModel):\n model_config = CoralConfig(\n aws_region=\"local\",\n aws_config=config\n )\n```\n\n---\n\n### Basic Operations\n\n#### Get or Create Table\nUse to get Table info or create the table if it doesn't exist.\n\n```python\ntable_description: dict = Users.get_or_create_table()\n```\n\n#### Get Table Info\nUse to get Table info. You can also add boto's client `describe_XXX` methods here, for any describe operation which does not have signature\nor the only argument is the TableName:\n\n* Allowable Descriptions Example: `describe_continuous_backups`, `describe_time_to_live`, `descript_limits`, etc...\n* Not Allowable Descriptions Example: `describe_backup`, `describe_global_table`, `describe_export`, etc...\n\n```python\ntable_info: dict = Users.get_table_info(include=[\"describe_time_to_live\"])\n```\n\n#### Check if Record exists\nUse to check if a record exists in the table. You need to pass on the parameters all hash and range keys defined in Model:\n\n```python\nuser_exists: bool = Users.exists(user_id=\"12345678-1234-1234-1234-123456789012\", user_type=UserType.USER)\n```\n\n#### Get Record\nUse to get a record from the table. You need to pass on the parameters all hash and range keys defined in Model:\n\n```python\nuser: Users = Users.get(user_id=\"12345678-1234-1234-1234-123456789012\", user_type=UserType.USER)\n```\n\n#### Save Record\nUse to save a record in the table:\n\n```python\nnew_user = Users(name=\"John Doe\", user_type=UserType.USER, age=30, password=\"123456\")\nnew_user.save()\n```\n\n### Using boto3's Client\n\nYou can use boto3's client to perform any operation you need. Just use the `get_client` method:\n\n```python\nnew_user = Users(name=\"John Doe\", user_type=UserType.USER, age=30, password=\"123456\")\nnew_user.save()\nnew_user.get_client().create_backup(\n TableName=new_user.table_name(), # or Users.get_table_name()\n BackupName=\"MyBackup\"\n)\n```\n\n---\n### Current Project Status\n\nCurrent status: In Progress\n\nWe strong advise to not use this lib in Production projects at this current stage.\nExcept bugs and breaking changes between each release.\n\n### Future Implementations\n* Add option to \"update\" tables (`create_or_update_table` method)\n* Add native support for Global and Local Secondary Indexes\n* Add native support for Query operations\n* Add native support for TransactWriteItems and TransactGetItems\n* Add native support for BatchWriteItems and BatchGetItems\n\n---\n\n### Not working?\n\nDon't panic. Get a towel and, please, open an\n[issue](https://github.com/megalus/coraline/issues).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Use Pydantic Models to handle AWS DynamoDB tables",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2efe97dc417a228b712f26f9494edcd12d77514f5ee9bc1918d1ed02e24e2ac0",
"md5": "9ae10e565b6c9f3a85ddc7cf5030a37f",
"sha256": "e978c5c64e35c589931b7886d8a4b08385a3e0a4aece7115bb7973f1c3291937"
},
"downloads": -1,
"filename": "coraline-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ae10e565b6c9f3a85ddc7cf5030a37f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 9424,
"upload_time": "2024-10-09T22:23:40",
"upload_time_iso_8601": "2024-10-09T22:23:40.249920Z",
"url": "https://files.pythonhosted.org/packages/2e/fe/97dc417a228b712f26f9494edcd12d77514f5ee9bc1918d1ed02e24e2ac0/coraline-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e07a8b0eb171737d8e08bdffee59dc15786bd6c7f959d99203e435389d71c4b",
"md5": "3750dc535ef3123013e001999f8a341a",
"sha256": "ef93fa75b1c4c14c804a8ef0712e3e8c063c250f4cb93beab6e605e148536cbe"
},
"downloads": -1,
"filename": "coraline-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3750dc535ef3123013e001999f8a341a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 9628,
"upload_time": "2024-10-09T22:23:42",
"upload_time_iso_8601": "2024-10-09T22:23:42.027951Z",
"url": "https://files.pythonhosted.org/packages/0e/07/a8b0eb171737d8e08bdffee59dc15786bd6c7f959d99203e435389d71c4b/coraline-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 22:23:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "coraline"
}
