Skip to content

Commit a661fba

Browse files
mstuttgartmstuttgart
committed
Update README
1 parent 5ff1d6e commit a661fba

1 file changed

Lines changed: 235 additions & 55 deletions

File tree

‎README.md‎

Lines changed: 235 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66
BrazilCEP
77
</h2>
88

9+
<p align="center">
10+
<strong>A minimalist and easy-to-use Python library for querying Brazilian CEP (Postal Address Code) data</strong>
11+
</p>
12+
913
<p align="center">
1014

1115
<a href="https://github.com/mstuttgart/brazilcep/actions?query=workflow%3A%22Github+CI%22">
@@ -32,108 +36,284 @@
3236
<img alt="Python Versions" src="https://img.shields.io/pypi/pyversions/brazilcep.svg">
3337
</a>
3438

39+
<a href="https://github.com/mstuttgart/brazilcep/blob/main/LICENSE">
40+
<img alt="License" src="https://img.shields.io/github/license/mstuttgart/brazilcep?color=fcd800">
41+
</a>
42+
3543
</p>
3644

3745
<p align="center">
38-
<a href="#about">About</a> |
39-
<a href="#install">Install</a> |
40-
<a href="#quick-start">Quick Start</a> |
41-
<a href="#documentation">Documentation</a> |
42-
<a href="#contribute">Contribute</a> |
43-
<a href="#credits">Credits</a>
46+
<a href="#features">Features</a> •
47+
<a href="#installation">Installation</a> •
48+
<a href="#quick-start">Quick Start</a> •
49+
<a href="#usage-examples">Usage Examples</a> •
50+
<a href="#documentation">Documentation</a> •
51+
<a href="#contributing">Contributing</a> •
52+
<a href="#license">License</a>
4453
</p>
4554

46-
## About
55+
---
56+
57+
## Features
4758

48-
**BrazilCEP** is a minimalist and easy-to-use Python library designed to query CEP (Postal Address Code) data.
59+
✨ **Simple and Intuitive API** - Easy-to-use interface for CEP queries
4960

50-
Its goal is to provide a unified query interface for multiple search services, simplifying the integration of Python applications with these services.
61+
🚀 **Async/Await Support** - Full support for asynchronous operations
5162

52-
Currently, it supports several CEP APIs:
63+
🔄 **Multiple Web Services** - Support for ViaCEP, ApiCEP, and OpenCEP
5364

54-
- [ViaCEP](https://viacep.com.br)
55-
- [ApiCEP (WideNet)](https://apicep.com)
56-
- [OpenCEP](https://opencep.com)
65+
⚡ **Fast and Lightweight** - Minimal dependencies and optimized performance
5766

58-
> [!NOTE]
59-
> **BrazilCEP** is the new name of the former **PyCEPCorreio** Python library.
60-
> To migrate your old code to the new version, refer to the [migration guide](https://brazilcep.readthedocs.io/api.html#migrate-from-pycepcorreios).
67+
🛡️ **Type Hints** - Full type annotation support for better IDE experience
6168

62-
> [!TIP]
63-
> **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.
69+
🔧 **Customizable** - Configure timeout, proxies, and preferred web service
6470

65-
## Install
71+
📦 **Well Tested** - Comprehensive test coverage
6672

67-
To install the latest stable release of BrazilCEP, use [pip](http://pip-installer.org):
73+
## Installation
6874

69-
```sh
75+
BrazilCEP requires Python 3.9 or higher.
76+
77+
Install using [pip](https://pip.pypa.io/):
78+
79+
```bash
7080
pip install brazilcep
7181
```
7282

83+
Or using [poetry](https://python-poetry.org/):
84+
85+
```bash
86+
poetry add brazilcep
87+
```
88+
7389
## Quick Start
7490

75-
Making a request is straightforward. Start by importing the BrazilCEP module:
91+
### Synchronous Usage
7692

7793
```python
78-
>>> import brazilcep
94+
import brazilcep
95+
96+
# Query a CEP
97+
address = brazilcep.get_address_from_cep('37503-130')
98+
99+
print(address)
100+
# Output:
101+
# {
102+
# 'cep': '37503-130',
103+
# 'street': 'Rua Geraldino Campista',
104+
# 'district': 'Santo Antônio',
105+
# 'city': 'Itajubá',
106+
# 'uf': 'MG',
107+
# 'complement': 'até 214/215'
108+
# }
79109
```
80110

81-
Next, use the `get_address_from_cep` function to query any CEP:
111+
### Asynchronous Usage
82112

83113
```python
84-
>>> address = brazilcep.get_address_from_cep('37503-130')
114+
import asyncio
115+
import brazilcep
116+
117+
async def main():
118+
address = await brazilcep.async_get_address_from_cep('37503-130')
119+
print(address)
120+
121+
asyncio.run(main())
85122
```
86123

87-
The result is a dictionary containing the address details:
124+
## Usage Examples
125+
126+
### Choosing a Web Service
127+
128+
BrazilCEP supports multiple CEP lookup services. You can specify which one to use:
88129

89130
```python
90-
>>> address
91-
{
92-
'district': 'rua abc',
93-
'cep': '37503130',
94-
'city': 'city ABC',
95-
'street': 'str',
96-
'uf': 'str',
97-
'complement': 'str',
98-
}
131+
from brazilcep import get_address_from_cep, WebService
132+
133+
# Using ViaCEP (default for backwards compatibility, but OpenCEP is now default)
134+
address = get_address_from_cep('37503-130', webservice=WebService.VIACEP)
135+
136+
# Using ApiCEP
137+
address = get_address_from_cep('37503-130', webservice=WebService.APICEP)
138+
139+
# Using OpenCEP (default)
140+
address = get_address_from_cep('37503-130', webservice=WebService.OPENCEP)
99141
```
100142

101-
The CEP must always be provided as a string.
143+
### Configuring Timeout
102144

103-
> [!TIP]
104-
> BrazilCEP is designed for on-demand queries in web applications. Bulk querying through scripts or other means is discouraged.
145+
Set a custom timeout for requests (default is 5 seconds):
105146

106-
> [!IMPORTANT]
107-
> 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.
147+
```python
148+
# Set timeout to 10 seconds
149+
address = get_address_from_cep('37503-130', timeout=10)
150+
```
151+
152+
### Using Proxies
153+
154+
Configure proxy settings for requests:
108155

109-
#### Asynchronous Requests with BrazilCEP
156+
```python
157+
proxies = {
158+
'http': 'http://10.10.1.10:3128',
159+
'https': 'http://10.10.1.10:1080',
160+
}
161+
162+
address = get_address_from_cep('37503-130', proxies=proxies)
163+
```
164+
165+
### Handling Exceptions
110166

111-
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.
167+
```python
168+
from brazilcep import get_address_from_cep, exceptions
169+
170+
try:
171+
address = get_address_from_cep('00000-000')
172+
except exceptions.CEPNotFound:
173+
print('CEP not found!')
174+
except exceptions.InvalidCEP:
175+
print('Invalid CEP format!')
176+
except exceptions.ConnectionError:
177+
print('Connection error!')
178+
except exceptions.Timeout:
179+
print('Request timeout!')
180+
except exceptions.BrazilCEPException as e:
181+
print(f'An error occurred: {e}')
182+
```
112183

113-
To perform an asynchronous request, use the `async_get_address_from_cep` function:
184+
### Complete Async Example
114185

115186
```python
116187
import asyncio
117-
import brazilcep
188+
from brazilcep import async_get_address_from_cep, WebService, exceptions
189+
190+
async def fetch_multiple_ceps():
191+
"""Fetch multiple CEPs concurrently."""
192+
ceps = ['37503-130', '01310-100', '20040-020']
193+
194+
tasks = [
195+
async_get_address_from_cep(cep, webservice=WebService.OPENCEP)
196+
for cep in ceps
197+
]
198+
199+
try:
200+
addresses = await asyncio.gather(*tasks)
201+
for cep, address in zip(ceps, addresses):
202+
print(f"\nCEP {cep}:")
203+
print(f" Street: {address['street']}")
204+
print(f" City: {address['city']}/{address['uf']}")
205+
except exceptions.BrazilCEPException as e:
206+
print(f"Error fetching addresses: {e}")
207+
208+
asyncio.run(fetch_multiple_ceps())
209+
```
118210

119-
async def main():
120-
address = await brazilcep.async_get_address_from_cep('37503-130')
121-
print(address)
211+
## Supported Web Services
122212

123-
asyncio.run(main())
213+
| Service | Website | Status | Rate Limit |
214+
|---------|---------|--------|------------|
215+
| [OpenCEP](https://opencep.com) | https://opencep.com | ✅ Active | Yes |
216+
| [ViaCEP](https://viacep.com.br) | https://viacep.com.br | ✅ Active | Yes |
217+
| [ApiCEP](https://apicep.com) | https://apicep.com | ✅ Active | Yes |
218+
219+
> [!IMPORTANT]
220+
> 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. Please check each service's terms of use and rate limits.
221+
222+
## Response Format
223+
224+
All queries return a dictionary with the following structure:
225+
226+
```python
227+
{
228+
'cep': str, # Postal code (e.g., '37503-130')
229+
'street': str, # Street name (e.g., 'Rua Geraldino Campista')
230+
'district': str, # Neighborhood/district (e.g., 'Santo Antônio')
231+
'city': str, # City name (e.g., 'Itajubá')
232+
'uf': str, # State abbreviation (e.g., 'MG')
233+
'complement': str # Additional information (may be empty)
234+
}
124235
```
125-
> [!NOTE]
126-
> This function is asynchronous and must be awaited when called.
127-
> Ensure that your environment supports asynchronous programming before using this function.
128236

129237
## Documentation
130238

131-
Comprehensive documentation for BrazilCEP is available on [ReadTheDocs](https://brazilcep.readthedocs.io/).
239+
For comprehensive documentation, including advanced usage, API reference, and migration guides, visit:
240+
241+
📚 **[BrazilCEP Documentation](https://brazilcep.readthedocs.io/)**
242+
243+
### Quick Links
244+
245+
- [API Reference](https://brazilcep.readthedocs.io/api.html)
246+
- [Migration from PyCEPCorreios](https://brazilcep.readthedocs.io/api.html#migrate-from-pycepcorreios)
247+
- [Contributing Guide](https://brazilcep.readthedocs.io/contributing.html)
248+
- [Changelog](https://github.com/mstuttgart/brazilcep/blob/main/CHANGELOG)
249+
250+
## Contributing
251+
252+
Contributions are welcome! Here's how you can help:
253+
254+
1. 🐛 **Report bugs** - Open an issue describing the bug
255+
2. 💡 **Suggest features** - Share your ideas for improvements
256+
3. 📝 **Improve documentation** - Help make the docs clearer
257+
4. 🔧 **Submit pull requests** - Fix bugs or add features
258+
259+
Please read our [Contributing Guide](https://brazilcep.readthedocs.io/contributing.html) before submitting a pull request.
260+
261+
### Development Setup
262+
263+
```bash
264+
# Clone the repository
265+
git clone https://github.com/mstuttgart/brazilcep.git
266+
cd brazilcep
267+
268+
# Install dependencies
269+
make setup
270+
271+
# Run tests
272+
make test
132273

133-
## Contribute
274+
# Run linting
275+
make lint
134276

135-
To contribute, follow the guidelines outlined [here](https://brazilcep.readthedocs.io/contributing.html).
277+
# Run all checks
278+
make check
279+
```
280+
281+
## About CEP
282+
283+
**CEP** (Código de Endereçamento Postal) or **Postal Address Code** is the Brazilian postal code system created, maintained, and organized by Correios do Brasil (Brazilian Post Office). It consists of eight digits and helps streamline address organization and delivery of mail and packages across Brazil.
284+
285+
## Migration from PyCEPCorreios
286+
287+
BrazilCEP is the successor to PyCEPCorreios. To migrate your code:
288+
289+
**Old (PyCEPCorreios):**
290+
```python
291+
from pycepcorreios import get_address_from_cep
292+
```
293+
294+
**New (BrazilCEP):**
295+
```python
296+
from brazilcep import get_address_from_cep
297+
```
298+
299+
For detailed migration instructions, see the [migration guide](https://brazilcep.readthedocs.io/api.html#migrate-from-pycepcorreios).
300+
301+
## License
302+
303+
BrazilCEP is released under the [MIT License](https://github.com/mstuttgart/brazilcep/blob/main/LICENSE).
136304

137305
## Credits
138306

139-
Copyright (C) 2016-2024 by Michell Stuttgart
307+
Created and maintained by [Michell Stuttgart](https://github.com/mstuttgart).
308+
309+
## Support
310+
311+
- 📧 Issues: [GitHub Issues](https://github.com/mstuttgart/brazilcep/issues)
312+
- 💬 Discussions: [GitHub Discussions](https://github.com/mstuttgart/brazilcep/discussions)
313+
- 📖 Documentation: [ReadTheDocs](https://brazilcep.readthedocs.io/)
314+
315+
---
316+
317+
<p align="center">
318+
Made with ❤️ in Brazil
319+
</p>

0 commit comments

Comments
 (0)