<h1 align="center">brasilapi-python</h1>
<div align="center">
<p>
<strong>Um cliente Python assíncrono para o <a href="https://brasilapi.com.br/" target="_blank">Brasil API</a></strong>
</p>
<p>
<img src="https://github.com/paulovitorweb/brasilapi-python/actions/workflows/test.yml/badge.svg"></img>
<img src="./coverage.svg"></img>
</p>
</div>
## Motivação
Fornecer um cliente HTTP assíncrono de alto nível para acessar e desserializar recursos do BrasilAPI.
## Instalação
Com pip:
```
pip install brasilapi
```
Ou com Poetry:
```
poetry add brasilapi
```
## Uso
Este cliente fornece chamadas à API do BrasilAPI dentro de um gerenciador de contexto assíncrono para uma melhor performance.
Por exemplo, o seguinte programa:
```python
import asyncio
from brasilapi import BrasilAPI
async def run():
async with BrasilAPI() as client:
result = await client.ceps.get("89010025")
print(repr(result))
if __name__ == "__main__":
asyncio.run(run())
```
Fornece uma saída igual ou semelhante a:
```python
CEP(cep='89010025', state='SC', city='Blumenau', neighborhood='Centro', street='Rua Doutor Luiz de Freitas Melro', service='correios', location=CEPLocation(type='Point', coordinates={'longitude': '-49.0641133', 'latitude': '-26.9239862'}))
```
Chamadas dentro do gerenciador de contexto utilizam uma mesma sessão que só é fechada ao sair do bloco. Você pode optar por compartilhar o mesmo cliente e sessão durante o tratamento de uma solicitação no seu aplicativo (por exemplo, funciona muito bem retornar uma instância do BrasilAPI como uma dependência do FastAPI) ou enquanto fizer sentido para seu cenário.
## Modelos Pydantic
Os resultados das consultas são instâncias de modelos [Pydantic v2](https://github.com/pydantic/pydantic). Você pode aproveitar a consistência e todas as dicas de tipo.
Os modelos Pydantic foram construídos com base na [documentação oficial do BrasilAPI](https://brasilapi.com.br/docs) e os nomes dos serviços e atributos são iguais aos
da documentação; portanto, alguns estão em inglês e outros em português. Excetuam-se mudanças de `camelCase` para `snake_case`. Mas você pode usar seu próprio modelo Pydantic:
```python
import asyncio
from pydantic import BaseModel, Field
from brasilapi import BrasilAPI
class CustomDDD(BaseModel):
estado: str = Field(alias="state")
cidades: list[str] = Field(alias="cities")
async def run():
async with BrasilAPI() as client:
ddd = await client.ddd.get("83").with_deserializer_class(CustomDDD)
print(repr(ddd))
if __name__ == "__main__":
asyncio.run(run())
```
Raw data
{
"_id": null,
"home_page": "https://github.com/paulovitorweb/brasilapi-python",
"name": "brasilapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "brasilapi,http,asyncio",
"author": "Paulo Freitas",
"author_email": "paulogeo5@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/89/3f/fcfe4f455395b860fca70e0de15a97515060e6a921e0cafa73d6ee944fac/brasilapi-0.1.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">brasilapi-python</h1>\n\n<div align=\"center\">\n <p>\n <strong>Um cliente Python ass\u00edncrono para o <a href=\"https://brasilapi.com.br/\" target=\"_blank\">Brasil API</a></strong>\n </p>\n <p>\n <img src=\"https://github.com/paulovitorweb/brasilapi-python/actions/workflows/test.yml/badge.svg\"></img> \n <img src=\"./coverage.svg\"></img>\n </p>\n</div>\n\n## Motiva\u00e7\u00e3o\n\nFornecer um cliente HTTP ass\u00edncrono de alto n\u00edvel para acessar e desserializar recursos do BrasilAPI.\n\n## Instala\u00e7\u00e3o\n\nCom pip:\n\n```\npip install brasilapi\n```\n\nOu com Poetry:\n\n```\npoetry add brasilapi\n```\n\n## Uso\n\nEste cliente fornece chamadas \u00e0 API do BrasilAPI dentro de um gerenciador de contexto ass\u00edncrono para uma melhor performance.\n\nPor exemplo, o seguinte programa:\n\n```python\nimport asyncio\nfrom brasilapi import BrasilAPI\n\nasync def run():\n async with BrasilAPI() as client:\n result = await client.ceps.get(\"89010025\")\n print(repr(result))\n\nif __name__ == \"__main__\":\n asyncio.run(run())\n```\n\nFornece uma sa\u00edda igual ou semelhante a:\n\n```python\nCEP(cep='89010025', state='SC', city='Blumenau', neighborhood='Centro', street='Rua Doutor Luiz de Freitas Melro', service='correios', location=CEPLocation(type='Point', coordinates={'longitude': '-49.0641133', 'latitude': '-26.9239862'}))\n```\n\nChamadas dentro do gerenciador de contexto utilizam uma mesma sess\u00e3o que s\u00f3 \u00e9 fechada ao sair do bloco. Voc\u00ea pode optar por compartilhar o mesmo cliente e sess\u00e3o durante o tratamento de uma solicita\u00e7\u00e3o no seu aplicativo (por exemplo, funciona muito bem retornar uma inst\u00e2ncia do BrasilAPI como uma depend\u00eancia do FastAPI) ou enquanto fizer sentido para seu cen\u00e1rio.\n\n## Modelos Pydantic\n\nOs resultados das consultas s\u00e3o inst\u00e2ncias de modelos [Pydantic v2](https://github.com/pydantic/pydantic). Voc\u00ea pode aproveitar a consist\u00eancia e todas as dicas de tipo.\n\nOs modelos Pydantic foram constru\u00eddos com base na [documenta\u00e7\u00e3o oficial do BrasilAPI](https://brasilapi.com.br/docs) e os nomes dos servi\u00e7os e atributos s\u00e3o iguais aos \nda documenta\u00e7\u00e3o; portanto, alguns est\u00e3o em ingl\u00eas e outros em portugu\u00eas. Excetuam-se mudan\u00e7as de `camelCase` para `snake_case`. Mas voc\u00ea pode usar seu pr\u00f3prio modelo Pydantic:\n\n```python\nimport asyncio\nfrom pydantic import BaseModel, Field\nfrom brasilapi import BrasilAPI\n\nclass CustomDDD(BaseModel):\n estado: str = Field(alias=\"state\")\n cidades: list[str] = Field(alias=\"cities\")\n\nasync def run():\n async with BrasilAPI() as client:\n ddd = await client.ddd.get(\"83\").with_deserializer_class(CustomDDD)\n print(repr(ddd))\n\nif __name__ == \"__main__\":\n asyncio.run(run())\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python async client for BrasilAPI",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/paulovitorweb/brasilapi-python",
"Homepage": "https://github.com/paulovitorweb/brasilapi-python",
"Repository": "https://github.com/paulovitorweb/brasilapi-python"
},
"split_keywords": [
"brasilapi",
"http",
"asyncio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cb9e4e562dafc98448a4fe961a202cafe468fbde4cc304878ddc1fd1432167fc",
"md5": "4d03a772bf1be63b3b29e3aa7d9a87b6",
"sha256": "064a0d74c2eb1f6ca2b0f3ef9ad7d8b3fe602021dddddf322b9ed1ab9159cae9"
},
"downloads": -1,
"filename": "brasilapi-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d03a772bf1be63b3b29e3aa7d9a87b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 10941,
"upload_time": "2023-10-29T20:38:41",
"upload_time_iso_8601": "2023-10-29T20:38:41.866539Z",
"url": "https://files.pythonhosted.org/packages/cb/9e/4e562dafc98448a4fe961a202cafe468fbde4cc304878ddc1fd1432167fc/brasilapi-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "893ffcfe4f455395b860fca70e0de15a97515060e6a921e0cafa73d6ee944fac",
"md5": "37773f1ac447f51b3b0731acce0bbb47",
"sha256": "cc1f1cf2a408afd865635ceed6761f474ab0060ce38512ed89dcad77a708bcf2"
},
"downloads": -1,
"filename": "brasilapi-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "37773f1ac447f51b3b0731acce0bbb47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 7974,
"upload_time": "2023-10-29T20:38:43",
"upload_time_iso_8601": "2023-10-29T20:38:43.668095Z",
"url": "https://files.pythonhosted.org/packages/89/3f/fcfe4f455395b860fca70e0de15a97515060e6a921e0cafa73d6ee944fac/brasilapi-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-29 20:38:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulovitorweb",
"github_project": "brasilapi-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "brasilapi"
}
JSON
