temp

Makefile

@@ -1,3 +1,8 @@
+.PHONY : docs
+docs :
+	rm -rf docs/build/
+	sphinx-autobuild -b html --watch brazilcep/ docs/source/ docs/build/
+
 .PHONY : run-checks
 run-checks :
 	isort --check .

brazilcep/__init__.py

@@ -12,6 +12,7 @@
 :license: MIT, see LICENSE for more details.
 """
 
+from .version import VERSION, VERSION_SHORT
 from .client import WebService, get_address_from_cep
 
 __all__ = [

brazilcep/version.py

@@ -0,0 +1,11 @@
+_MAJOR = "6"
+_MINOR = "3"
+# On main and in a nightly release the patch should be one ahead of the last
+# released build.
+_PATCH = "1"
+# This is mainly for nightly builds which have the suffix ".dev$DATE". See
+# https://semver.org/#is-v123-a-semantic-version for the semantics.
+_SUFFIX = ""
+
+VERSION_SHORT = "{0}.{1}".format(_MAJOR, _MINOR)
+VERSION = "{0}.{1}.{2}{3}".format(_MAJOR, _MINOR, _PATCH, _SUFFIX)

docs/.gitignore

@@ -0,0 +1 @@
+build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/CHANGELOG.md

@@ -0,0 +1 @@
+CHANGELOG.md

docs/source/CONTRIBUTING.md

@@ -0,0 +1 @@
+CONTRIBUTING.md

docs/source/conf.py

@@ -0,0 +1,129 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import logging
+import os
+import sys
+from datetime import datetime
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+
+sys.path.insert(0, os.path.abspath("../../"))
+
+from brazilcep import VERSION, VERSION_SHORT  # noqa: E402
+
+# -- Project information -----------------------------------------------------
+
+project = "brazilcep"
+copyright = f"{datetime.today().year}, Michell Stuttgart"
+author = "Michell Stuttgart"
+version = VERSION_SHORT
+release = VERSION
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.doctest",
+    "sphinx_copybutton",
+    "sphinx_autodoc_typehints",
+]
+
+# Tell myst-parser to assign header anchors for h1-h3.
+myst_heading_anchors = 3
+
+suppress_warnings = ["myst.header"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build"]
+
+source_suffix = [".rst", ".md"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    # Uncomment these if you use them in your codebase:
+    #  "torch": ("https://pytorch.org/docs/stable", None),
+    #  "datasets": ("https://huggingface.co/docs/datasets/master/en", None),
+    #  "transformers": ("https://huggingface.co/docs/transformers/master/en", None),
+}
+
+# By default, sort documented members by type within classes and modules.
+autodoc_member_order = "groupwise"
+
+# Include default values when documenting parameter types.
+typehints_defaults = "comma"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+html_title = f"brazilcep v{VERSION}"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# html_css_files = ["css/custom.css"]
+
+html_favicon = "_static/favicon.ico"
+
+html_theme_options = {
+    "logo": "logo.png",
+    "show_powered_by": False,
+    "github_user": "mstuttgart",
+    "github_repo": "brazilcep",
+    "github_banner": True,
+    "show_related": False,
+    "note_bg": "#FFF59C",
+}
+
+# Custom sidebar templates, maps document names to template names.
+html_sidebars = {
+    "index": ["sidebarintro.html", "sourcelink.html", "searchbox.html", "hacks.html"],
+    "**": [
+        "sidebarlogo.html",
+        "localtoc.html",
+        "relations.html",
+        "sourcelink.html",
+        "searchbox.html",
+        "hacks.html",
+    ],
+}
+
+# -- Hack to get rid of stupid warnings from sphinx_autodoc_typehints --------
+
+
+class ShutupSphinxAutodocTypehintsFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if "Cannot resolve forward reference" in record.msg:
+            return False
+        return True
+
+
+logging.getLogger("sphinx.sphinx_autodoc_typehints").addFilter(ShutupSphinxAutodocTypehintsFilter())

docs/source/index.md

@@ -0,0 +1,78 @@
+# **BrazilCEP**
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Getting started
+
+install
+tutorial
+migrate
+overview
+```
+
+```{toctree}
+:hidden:
+:caption: Development
+
+CHANGELOG
+CONTRIBUTING
+License <https://raw.githubusercontent.com/mstuttgart/brazilcep/main/LICENSE>
+GitHub Repository <https://github.com/mstuttgart/brazilcep>
+```
+
+<!-- ## Indices and tables -->
+
+<!-- ```{eval-rst} -->
+<!-- * :ref:`genindex` -->
+<!-- * :ref:`modindex` -->
+<!-- ``` -->
+<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://pypi.org/project/brazilcep">
+    <img src="https://img.shields.io/pypi/v/brazilcep.svg?" alt="Ratings">
+  </a>
+
+  <a href="https://pypi.org/project/brazilcep/">
+    <img src="https://img.shields.io/pypi/pyversions/brazilcep.svg" alt="Version">
+  </a>
+
+</p>
+
+
+**BrazilCEP** is a minimalist and easy-to-use python library designed to query CEP (brazilian zip codes) data.
+
+-----------------------------
+
+Its objective is to provide a common query interface to all these search services, facilitating the integration of Python applications with these services.
+
+```python
+>>> get_address_from_cep('37503-130')
+{
+    'bairro': 'str',
+    'cep': 'str',
+    'cidade': 'str',
+    'logradouro': 'str',
+    'uf': 'str',
+    'complemento': 'str',
+}
+```
+
+**BrazilCEP** is the new name of former **PyCEPCorreio** python library. If you want to migrate the old code to the new version, please see the [migrate](/migrate) section.
+
+## Features
+
+* Cross-platform: Windows, Mac, and Linux are officially supported.
+* Works with Python 3.8, 3.9, 3.10, 3.11 and 3.12.
+* Currently supports several CEP API's:
+  * [ViaCEP](https://viacep.com.br)
+  * [ApiCEP (WideNet)](https://apicep.com)
+  * [OpenCEP](https://opencep.com/)
+  * [Correios (site)](https://www2.correios.com.br/sistemas/buscacep/resultadoBuscaEndereco.cfm)
+
+BrazilCEP started as a personal study project and evolved into a serious and open source project that is used by many developers on a daily basis.
+

docs/source/install.md

@@ -0,0 +1,16 @@
+# Install
+
+The recommended way to get BrazilCEP is to **install the latest stable release**
+via [pip](http://pip-installer.org>):
+
+```sh
+pip install brazilcep
+```
+
+We currently support **Python 3.8+ only**. Users on older interpreter versions
+are urged to upgrade.
+
+BrazilCEP has only a few **direct dependencies**:
+
+- [Zeep](https://pypi.org/project/zeep): for SOAP requests.
+- [requests](https://pypi.org/project/requests): for REST API requests.

docs/source/migrate.md

@@ -0,0 +1,67 @@
+# Migrate
+
+**BrazilCEP** is the new name of former **PycepCorreios**. This page
+guide you on to process of migrate old code to new version.
+
+It's simples migrate te code and require minimal steps.
+
+## imports
+
+First, rename the `import` statements from:
+
+```python title="PyCEPCorreios"
+import pycepcorreios
+```
+to
+
+```python title="BrazilCEP"
+import brazilcep
+```
+
+## Query results
+
+The next step, is adjust the *keys* of query returned by `get_address_from_cep` function.
+
+The keys have simply been translated to english. Take a look on this old code:
+
+``` python title="PyCEPCorreios"
+>>> get_address_from_cep('37503-130')
+{
+  'bairro': 'rua abc',
+  'cep': '37503130',
+  'cidade': 'city ABC',
+  'logradouro': 'str',
+  'uf': 'str',
+  'complemento': 'str',
+}
+```
+This is the new code:
+
+``` python title="BrazilCEP"
+>>> get_address_from_cep('37503-130')
+{
+  'district': 'rua abc',
+  'cep': '37503130',
+  'city': 'city ABC',
+  'street': 'str',
+  'uf': 'str',
+  'complement': 'str',
+}
+```
+
+## Exceptions
+
+The follow Exceptions have been removed.
+
+```python
+exceptions.ConnectionError
+exceptions.Timeout
+exceptions.HTTPError
+exceptions.BaseException
+```
+
+Please, use the [requests](https://requests.readthedocs.io/en/latest/user/quickstart/#errors-and-exceptions) exceptions instead.
+
+## Questions?
+
+The best way to send question is open a issue in **BrazilCEP** issue tracker [here](https://github.com/mstuttgart/brazilcep/issues).