Metadata-Version: 2.4
Name: brazilcep
Version: 7.0.0
Summary: Minimalist and easy-to-use Python library designed to query CEP (Postal Address Code) data
Author-email: Michell Stuttgart <michellstut@gmail.com>
License: 
        MIT License
        
        Copyright (c) 2016-2024, Michell Stuttgart
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Documentation, https://brazilcep.readthedocs.io/index.html
Project-URL: Repository, https://github.com/mstuttgart/brazilcep
Project-URL: Tracker, https://github.com/mstuttgart/brazilcep/issues
Project-URL: Changelog, https://github.com/mstuttgart/brazilcep/blob/main/CHANGELOG
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Natural Language :: English
Classifier: Natural Language :: Portuguese (Brazilian)
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.2
Requires-Dist: aiohttp>=3.8.1
Provides-Extra: dev
Requires-Dist: tox>=4.23.2; extra == "dev"
Requires-Dist: pytest>=7.3.1; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: mypy<1.5,>=1.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: requests-mock>=1.10.0; extra == "dev"
Requires-Dist: black<24.0,>=23.0; extra == "dev"
Requires-Dist: isort<5.13,>=5.12; extra == "dev"
Requires-Dist: pre-commit>=4.0.1; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ipdb; extra == "dev"
Provides-Extra: coverage
Requires-Dist: coveralls>=3.3.1; extra == "coverage"
Requires-Dist: pytest-cov>=4.0.0; extra == "coverage"
Requires-Dist: requests-mock>=1.10.0; extra == "coverage"
Requires-Dist: codecov-cli>=2.0.15; extra == "coverage"
Provides-Extra: docs
Requires-Dist: Sphinx<8,>=6; extra == "docs"
Requires-Dist: readme-renderer==43; extra == "docs"
Requires-Dist: myst-parser<2.1,>=1.0; extra == "docs"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "docs"
Requires-Dist: sphinx-autobuild==2021.3.14; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints==1.23.3; extra == "docs"
Provides-Extra: build
Requires-Dist: build==1.2.2.post1; extra == "build"
Dynamic: license-file

<h2 align="center">
  <a href="https://pypi.org/project/brazilcep/">
    <img src="https://github.com/mstuttgart/brazilcep/assets/8174740/fb7c86c8-6261-4300-b2e0-65877084d865" width="15%" alt="BrazilCEP Logo">
  </a>
  <br>
  BrazilCEP
</h2>

<p align="center">

  <a href="https://github.com/mstuttgart/brazilcep/actions?query=workflow%3A%22Github+CI%22">
    <img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/mstuttgart/brazilcep/test.yml?color=fcd800&branch=main">
  </a>

  <a href="https://codecov.io/gh/mstuttgart/brazilcep">
    <img alt="Codecov" src="https://img.shields.io/codecov/c/github/mstuttgart/brazilcep?color=fcd800">
  </a>

  <a href="https://brazilcep.readthedocs.io/">
    <img alt="Read the Docs" src="https://img.shields.io/readthedocs/brazilcep?color=fcd800">
  </a>

  <a href="https://pypi.org/project/brazilcep">
    <img alt="Downloads" src="https://img.shields.io/pypi/dm/brazilcep?color=fcd800">
  </a>

  <a href="https://pypi.org/project/brazilcep">
    <img alt="PyPI Version" src="https://img.shields.io/pypi/v/brazilcep.svg?color=fcd800">
  </a>

  <a href="https://pypi.org/project/brazilcep/">
    <img alt="Python Versions" src="https://img.shields.io/pypi/pyversions/brazilcep.svg?color=fcd800">
  </a>

</p>

<p align="center">
  <a href="#about">About</a> |
  <a href="#install">Install</a> |
  <a href="#quick-start">Quick Start</a> |
  <a href="#documentation">Documentation</a> |
  <a href="#contribute">Contribute</a> |
  <a href="#credits">Credits</a>
</p>

## About

**BrazilCEP** is a minimalist and easy-to-use Python library designed to query CEP (Postal Address Code) data.

Its goal is to provide a unified query interface for multiple search services, simplifying the integration of Python applications with these services.

Currently, it supports several CEP APIs:

- [ViaCEP](https://viacep.com.br)
- [ApiCEP (WideNet)](https://apicep.com)
- [OpenCEP](https://opencep.com)

> [!NOTE]
> **BrazilCEP** is the new name of the former **PyCEPCorreio** Python library.
> To migrate your old code to the new version, refer to the [migration guide](https://brazilcep.readthedocs.io/api.html#migrate-from-pycepcorreios).

> [!TIP]
> **CEP** or **Código de Endereçamento Postal** (_Postal Address Code_) is a system of numeric codes created, maintained, and organized by _Correios do Brasil_ to streamline address organization and delivery of letters and parcels.

## Install

To install the latest stable release of BrazilCEP, use [pip](http://pip-installer.org):

```sh
pip install brazilcep
```

## Quick Start

Making a request is straightforward. Start by importing the BrazilCEP module:

```python
>>> import brazilcep
```

Next, use the `get_address_from_cep` function to query any CEP:

```python
>>> address = brazilcep.get_address_from_cep('37503-130')
```

The result is a dictionary containing the address details:

```python
>>> address
{
    'district': 'rua abc',
    'cep': '37503130',
    'city': 'city ABC',
    'street': 'str',
    'uf': 'str',
    'complement': 'str',
}
```

The CEP must always be provided as a string.

> [!TIP]
> BrazilCEP is designed for on-demand queries in web applications. Bulk querying through scripts or other means is discouraged.

> [!IMPORTANT]
> BrazilCEP does not guarantee the availability or support of any third-party query APIs. This library serves as a convenient interface for accessing these services.

#### Asynchronous Requests with BrazilCEP

BrazilCEP (version >= 7.0.0) also supports asynchronous operations , allowing you to retrieve address information for a given CEP without blocking your application. This is particularly useful for web applications or services that require high responsiveness.

To perform an asynchronous request, use the `async_get_address_from_cep` function:

```python
import asyncio
import brazilcep

async def main():
  address = await brazilcep.async_get_address_from_cep('37503-130')
  print(address)

asyncio.run(main())
```
> [!NOTE]
> This function is asynchronous and must be awaited when called.
> Ensure that your environment supports asynchronous programming before using this function.

## Documentation

Comprehensive documentation for BrazilCEP is available on [ReadTheDocs](https://brazilcep.readthedocs.io/).

## Contribute

To contribute, follow the guidelines outlined [here](https://brazilcep.readthedocs.io/contributing.html).

## Credits

Copyright (C) 2016-2024 by Michell Stuttgart
