# DynoLayer
O **DynoLayer** é uma ferramenta poderosa que simplifica e agiliza o acesso e manipulação de dados no Amazon DynamoDB. Baseada no padrão Active Record, esta biblioteca oferece uma abstração intuitiva para interagir com tabelas no DynamoDB, permitindo operações de CRUD (Create, Read, Update, Delete) de forma fácil e natural.
## Instalação
Para usar o pacote basta instalar através do gerenciador de dependências de sua preferência.
```sh
pip install dynolayer
```
ou
```sh
pipenv install dynolayer
```
## Exemplos
Para mais exemplos, consulte a pasta [docs](https://github.com/kauelima21/dynolayer/tree/main/docs)
Para iniciar, primeiro você precisa criar a sua model herdando a classe *DynoLayer*. O nome da tabela e os atributos obrigatórios são os únicos campos requeridos, os demais já possuem um valor padrão.
```python
from dynolayer import DynoLayer
class User(DynoLayer):
def __init__(self) -> None:
super().__init__('users', [])
```
Por padrão, o timezone utilizado é o ```America/Sao_Paulo```. Para alterar isso basta adicionar a variável de ambiente **TIMESTAMP_TIMEZONE** com o valor desejado.
```sh
TIMESTAMP_TIMEZONE='US/Eastern'
```
O mesmo se aplica para a região e para o uso local do dynamodb. Caso as variáveis abaixo não existam, os valores padrão serão **sa-east-1** e o dynamodb da da aws na região utilizada.
```sh
REGION='us-east-1'
LOCAL_ENDPOINT='http://localhost:8000'
```
### Save
Para criar um registro, é preciso instanciar a model e atribuir valor as suas propriedades. Depois basta rodar um **save()** para salvar no banco!
```python
user = User()
user.full_name = 'John Doe'
user.email = 'john@mail.com'
user.stars = 5
user.phones = [
'11 91234-5678',
'10 95678-1234',
]
if user.save():
print('Usuário adicionado com sucesso!')
```
O mesmo método é usado para atualizar o registro, basta possuir a chave de partição e os dados que precisam ser alterados.
```python
user = User()
user.id = 'meu-id-55'
user.email = 'john.doe@email.com' # altera o email
user.save() # atualiza o registro para o novo email
```
### Find By Id
Para buscar um registro pela chave de partição, se usa o método **find_by_id()**. O mesmo vai retornar a instancia da model com os atributos buscados, mantendo o Active Record e possibilitando a execução de outras instruções, como o update que vimos a pouco.
```python
user = User().find_by_id('meu-id-55')
user.stars = 17
print(f'O usuário {user.full_name} possui {user.stars} estrelas!')
user.save()
```
### Find
Para as demais consultas, como uma busca geral (scan) ou uma busca com filtro, o método utilizado é o **find()** e os métodos subsequentes para formar um *Query Builder*.
```python
# busca todos os produtos
products = Product().find().fetch()
# busca todos os usuários que estão com o status COMPLETED
completed_users = User().find(
'#st = :st',
{':st': 'COMPLETED'},
{'#st': 'status'}
).fetch()
# busca todos os usuários com limite de 10
users = User().find().limit(10).fetch()
```
É importante destacar que o scan possui um limite na quantidade de dados que retorna, e para trabalhar com isso basta assinalar o parâmetro *paginate_through_results* como ```True``` no método **fetch()**.
```python
# busca todos os produtos paginando o resultado da consulta no DynamoDB
products = Product().find().fetch(True)
```
### Find By
Para os casos de consultas com filtro em determinada propriedade que não seja uma chave de partição, pode-se usar o método **find_by**. Para verificar a contagem de itens recebidos ao realizar o fetch (após o *find* ou *find_by*), basta usar a propriedade **get_count**
```python
users = User()
online_users = users.find_by('status', '=', 'online').fetch(True)
print(f'{users.get_count} online no momento!')
```
### Query By
Para os casos de consultas com filtro em determinada chave de partição, pode-se usar o método **query_by**.
```python
users = User()
online_users = users.query_by('status', '=', 'online').fetch(True)
print(f'{users.get_count} online no momento!')
```
### Order
Serve para ordenar de acordo com determinado atributo, podendo também trazer a resposta de form crescente ou decrescente, a depender do valor que for passado no segundo argumento que por padrão é True e retorna de maneira crescente.
```python
users = User()
online_users = users.find_by('status', '=', 'online').order('first_name').fetch(True)
print(f'{users.get_count} online no momento!')
```
### Count
Caso queira contar o total de itens na tabela ou operação que você fizer sem retornar os dados registrados nela, basta substituir o método **fetch()** por **count()**
```python
users = User()
online_users = users.find_by('status', '=', 'online').order('first_name').count()
print(f'{online_users} online no momento!')
```
### Fetch
Por default retorna os dados como um dict, mas ao passar o argumento object como True ele retorna os registros como um objeto DynoLayer.
```python
users = User().find_by('status', '=', 'online').order('first_name').fetch(object=True)
print(users[0].name)
```
### Destroy
Para remover um registro, basta obter a sua chave de partição e executar o método **destroy()** em seguida.
```python
user = User().find_by_id('meu-id-55')
if user.destroy():
print('Usuário removido com sucesso!')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/kauelima21/dynolayer",
"name": "dynolayer",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "dynolayer, dynamodb, active record, aws lambda",
"author": "Kau\u00ea Leal de Lima",
"author_email": "kaueslim@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0c/33/1222b218ede658fa10d161034346c91b33bf5f7d0156629fb8e0f4382b5f/dynolayer-0.4.2.tar.gz",
"platform": null,
"description": "# DynoLayer\r\n\r\nO **DynoLayer** \u00c3\u00a9 uma ferramenta poderosa que simplifica e agiliza o acesso e manipula\u00c3\u00a7\u00c3\u00a3o de dados no Amazon DynamoDB. Baseada no padr\u00c3\u00a3o Active Record, esta biblioteca oferece uma abstra\u00c3\u00a7\u00c3\u00a3o intuitiva para interagir com tabelas no DynamoDB, permitindo opera\u00c3\u00a7\u00c3\u00b5es de CRUD (Create, Read, Update, Delete) de forma f\u00c3\u00a1cil e natural.\r\n\r\n## Instala\u00c3\u00a7\u00c3\u00a3o\r\n\r\nPara usar o pacote basta instalar atrav\u00c3\u00a9s do gerenciador de depend\u00c3\u00aancias de sua prefer\u00c3\u00aancia.\r\n\r\n```sh\r\npip install dynolayer\r\n```\r\n\r\nou\r\n\r\n```sh\r\npipenv install dynolayer\r\n```\r\n\r\n## Exemplos\r\n\r\nPara mais exemplos, consulte a pasta [docs](https://github.com/kauelima21/dynolayer/tree/main/docs)\r\n\r\nPara iniciar, primeiro voc\u00c3\u00aa precisa criar a sua model herdando a classe *DynoLayer*. O nome da tabela e os atributos obrigat\u00c3\u00b3rios s\u00c3\u00a3o os \u00c3\u00banicos campos requeridos, os demais j\u00c3\u00a1 possuem um valor padr\u00c3\u00a3o.\r\n\r\n```python\r\nfrom dynolayer import DynoLayer\r\n\r\n\r\nclass User(DynoLayer):\r\n def __init__(self) -> None:\r\n super().__init__('users', [])\r\n```\r\n\r\nPor padr\u00c3\u00a3o, o timezone utilizado \u00c3\u00a9 o ```America/Sao_Paulo```. Para alterar isso basta adicionar a vari\u00c3\u00a1vel de ambiente **TIMESTAMP_TIMEZONE** com o valor desejado.\r\n\r\n```sh\r\nTIMESTAMP_TIMEZONE='US/Eastern'\r\n```\r\n\r\nO mesmo se aplica para a regi\u00c3\u00a3o e para o uso local do dynamodb. Caso as vari\u00c3\u00a1veis abaixo n\u00c3\u00a3o existam, os valores padr\u00c3\u00a3o ser\u00c3\u00a3o **sa-east-1** e o dynamodb da da aws na regi\u00c3\u00a3o utilizada.\r\n\r\n```sh\r\nREGION='us-east-1'\r\nLOCAL_ENDPOINT='http://localhost:8000'\r\n```\r\n\r\n### Save\r\n\r\nPara criar um registro, \u00c3\u00a9 preciso instanciar a model e atribuir valor as suas propriedades. Depois basta rodar um **save()** para salvar no banco!\r\n\r\n```python\r\nuser = User()\r\n\r\nuser.full_name = 'John Doe'\r\nuser.email = 'john@mail.com'\r\nuser.stars = 5\r\nuser.phones = [\r\n '11 91234-5678',\r\n '10 95678-1234',\r\n]\r\n\r\nif user.save():\r\n print('Usu\u00c3\u00a1rio adicionado com sucesso!')\r\n```\r\n\r\nO mesmo m\u00c3\u00a9todo \u00c3\u00a9 usado para atualizar o registro, basta possuir a chave de parti\u00c3\u00a7\u00c3\u00a3o e os dados que precisam ser alterados.\r\n\r\n```python\r\nuser = User()\r\n\r\nuser.id = 'meu-id-55'\r\nuser.email = 'john.doe@email.com' # altera o email\r\n\r\nuser.save() # atualiza o registro para o novo email\r\n```\r\n\r\n### Find By Id\r\n\r\nPara buscar um registro pela chave de parti\u00c3\u00a7\u00c3\u00a3o, se usa o m\u00c3\u00a9todo **find_by_id()**. O mesmo vai retornar a instancia da model com os atributos buscados, mantendo o Active Record e possibilitando a execu\u00c3\u00a7\u00c3\u00a3o de outras instru\u00c3\u00a7\u00c3\u00b5es, como o update que vimos a pouco.\r\n\r\n```python\r\nuser = User().find_by_id('meu-id-55')\r\nuser.stars = 17\r\nprint(f'O usu\u00c3\u00a1rio {user.full_name} possui {user.stars} estrelas!')\r\n\r\nuser.save()\r\n```\r\n\r\n### Find\r\n\r\nPara as demais consultas, como uma busca geral (scan) ou uma busca com filtro, o m\u00c3\u00a9todo utilizado \u00c3\u00a9 o **find()** e os m\u00c3\u00a9todos subsequentes para formar um *Query Builder*.\r\n\r\n```python\r\n# busca todos os produtos\r\nproducts = Product().find().fetch() \r\n\r\n# busca todos os usu\u00c3\u00a1rios que est\u00c3\u00a3o com o status COMPLETED\r\ncompleted_users = User().find(\r\n '#st = :st',\r\n {':st': 'COMPLETED'},\r\n {'#st': 'status'}\r\n).fetch()\r\n\r\n# busca todos os usu\u00c3\u00a1rios com limite de 10\r\nusers = User().find().limit(10).fetch() \r\n```\r\n\r\n\u00c3\u2030 importante destacar que o scan possui um limite na quantidade de dados que retorna, e para trabalhar com isso basta assinalar o par\u00c3\u00a2metro *paginate_through_results* como ```True``` no m\u00c3\u00a9todo **fetch()**.\r\n\r\n```python\r\n# busca todos os produtos paginando o resultado da consulta no DynamoDB\r\nproducts = Product().find().fetch(True)\r\n```\r\n\r\n### Find By\r\nPara os casos de consultas com filtro em determinada propriedade que n\u00c3\u00a3o seja uma chave de parti\u00c3\u00a7\u00c3\u00a3o, pode-se usar o m\u00c3\u00a9todo **find_by**. Para verificar a contagem de itens recebidos ao realizar o fetch (ap\u00c3\u00b3s o *find* ou *find_by*), basta usar a propriedade **get_count**\r\n\r\n```python\r\nusers = User()\r\nonline_users = users.find_by('status', '=', 'online').fetch(True)\r\nprint(f'{users.get_count} online no momento!')\r\n```\r\n\r\n### Query By\r\nPara os casos de consultas com filtro em determinada chave de parti\u00c3\u00a7\u00c3\u00a3o, pode-se usar o m\u00c3\u00a9todo **query_by**.\r\n\r\n```python\r\nusers = User()\r\nonline_users = users.query_by('status', '=', 'online').fetch(True)\r\nprint(f'{users.get_count} online no momento!')\r\n```\r\n\r\n### Order\r\nServe para ordenar de acordo com determinado atributo, podendo tamb\u00c3\u00a9m trazer a resposta de form crescente ou decrescente, a depender do valor que for passado no segundo argumento que por padr\u00c3\u00a3o \u00c3\u00a9 True e retorna de maneira crescente.\r\n\r\n```python\r\nusers = User()\r\nonline_users = users.find_by('status', '=', 'online').order('first_name').fetch(True)\r\nprint(f'{users.get_count} online no momento!')\r\n```\r\n\r\n### Count\r\nCaso queira contar o total de itens na tabela ou opera\u00c3\u00a7\u00c3\u00a3o que voc\u00c3\u00aa fizer sem retornar os dados registrados nela, basta substituir o m\u00c3\u00a9todo **fetch()** por **count()**\r\n\r\n```python\r\nusers = User()\r\nonline_users = users.find_by('status', '=', 'online').order('first_name').count()\r\nprint(f'{online_users} online no momento!')\r\n```\r\n\r\n### Fetch\r\nPor default retorna os dados como um dict, mas ao passar o argumento object como True ele retorna os registros como um objeto DynoLayer.\r\n\r\n```python\r\nusers = User().find_by('status', '=', 'online').order('first_name').fetch(object=True)\r\nprint(users[0].name)\r\n```\r\n\r\n### Destroy\r\n\r\nPara remover um registro, basta obter a sua chave de parti\u00c3\u00a7\u00c3\u00a3o e executar o m\u00c3\u00a9todo **destroy()** em seguida.\r\n\r\n```python\r\nuser = User().find_by_id('meu-id-55')\r\n\r\nif user.destroy():\r\n print('Usu\u00c3\u00a1rio removido com sucesso!')\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "O DynoLayer \u00e9 uma ferramenta poderosa que simplifica e agiliza o acesso e manipula\u00e7\u00e3o de dados no Amazon DynamoDB, baseada no padr\u00e3o Active Record.",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://github.com/kauelima21/dynolayer"
},
"split_keywords": [
"dynolayer",
" dynamodb",
" active record",
" aws lambda"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c331222b218ede658fa10d161034346c91b33bf5f7d0156629fb8e0f4382b5f",
"md5": "e91b9eb4d41d7d83088749859cc7f3f7",
"sha256": "5002c07df8baba47d5542f926e949e82b8630175c2a016e9c76d8ff102894d0c"
},
"downloads": -1,
"filename": "dynolayer-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "e91b9eb4d41d7d83088749859cc7f3f7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10368,
"upload_time": "2024-03-19T22:52:58",
"upload_time_iso_8601": "2024-03-19T22:52:58.188101Z",
"url": "https://files.pythonhosted.org/packages/0c/33/1222b218ede658fa10d161034346c91b33bf5f7d0156629fb8e0f4382b5f/dynolayer-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-19 22:52:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kauelima21",
"github_project": "dynolayer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "dynolayer"
}
JSON
