viacep 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3394e46631b047c6c4d8ee13b0e73e01e1c0f935128b2ea559a172aac3724e8c
-  data.tar.gz: 96f668e8080c5850419aa28e3190f40bb2ef0cb02dfeabc2c1e0de15904c583a
+  metadata.gz: d996e5aa0ad22ffabeddff59c6e01715e82506cb67ba9161c7b706c0bf3b1231
+  data.tar.gz: 511ab0884767f8c4534454ce935dde9d6da9a7e7571e72b8f72caa2c875a2bc3
 SHA512:
-  metadata.gz: a6515fcf3bab3b1b96ae4ade5e98464939824acd443af707a400f13be17fbe1ea917bd58416d0e553cfef0e9280088cedef32ca61e1ccadc344d913fc3f6c304
-  data.tar.gz: 67b0d365a02aabeda3144dc9a072f473513880573ee506a275d06cbab2435a485add1ca9b045eb55acf608c121438114e01a01cd420338ab1aa233dac556ce3e
+  metadata.gz: 8822385880160352463509f979354cd456dc72edc85f14906ab69d7d03a1a09c06c76b32d62f3daf9a449c7669a015304be9c0ecf680f1ce6f89996840a1cffb
+  data.tar.gz: 5debef0f5bd8b1babb8b268f82b62872a44d0ce59ce4f0e731e77209ebcb5a03b5e00300506abd448698fd080d12086d7186eee4b8a1633c5063adbd513aa3ef

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+### Added
+N/A
+
+### Changed
+N/A
+
+### Deprecated
+N/A
+
+### Removed
+N/A
+
+### Fixed
+N/A
+
+### Security
+N/A
+
+## [2.0.3] - 2019-07-20
+### Added
+- Create CHANGELOG.md file to track changes.
+
+### Fixed
+- Improve public API documentation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Vinicius Brasil
+
+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.

data/README.md

@@ -1,55 +1,50 @@
 <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/bc/BRA_orthographic.svg/270px-BRA_orthographic.svg.png" align="right" />
 
-# viacep [![GitHub license](https://img.shields.io/github/license/vnbrs/burocracia.cr.svg)](https://github.com/vnbrs/burocracia.cr/blob/master/LICENSE) 
-> Gem responsável por buscar endereços a partir do CEP utilizando a API do ViaCEP com features úteis como timeout.
+# viacep ![Tests](https://github.com/vnbrs/viacep/workflows/Tests/badge.svg) [![GitHub license](https://img.shields.io/github/license/vnbrs/burocracia.cr.svg)](https://github.com/vnbrs/burocracia.cr/blob/master/LICENSE) 
+> Dependency-less zipcode lookup gem for Brazilian addresses with an easy-to-use API and useful features such as timeout.
 
-## Instalação
+## Installing
 
-Instale o viacep pelo [RubyGems](https://rubygems.org/gems/viacep/) facilmente via terminal:
+You can easily install viacep through [RubyGems](https://rubygems.org/gems/viacep/):
 
 ```shell
 gem install viacep
-=> Vai que é tua! 🚀
+=> Rock on! 🚀
 ```
 
-ou...
+or add the following to your Gemfile:
 
 ```shell
-bundle add viacep
-=> Gem instalada no Gemfile! 🤓
+gem "viacep"
 ```
 
-## Como usar?
+## Usage
 
 ```ruby
 require 'viacep'
 
-# com CEPs sem formatação...
+# with unformatted zipcodes... =)
 ViaCep::Address.new('80210130')
 => #<ViaCep::Address:0x00007fe52a8a0568 @cep="80210-130", @address="Rua José Ananias Mauad", @neighborhood="Jardim Botânico", @city="Curitiba", @state="PR", @ibge="4106902", @gia="">
 
-# com CEPs formatados...
+# with formatted zipcodes... =)
 ViaCep::Address.new('13035-680')
 => #<ViaCep::Address:0x00007fe52a99e730 @cep="13035-680", @address="Avenida João Jorge", @neighborhood="Vila Industrial", @city="Campinas", @state="SP", @ibge="3509502", @gia="2446">
 
-# um CEP não existente...
-ViaCep::Address.new('123')
+# or even an nonexistent zipcode... =(
+ViaCep::Address.new('12345678')
 => exception thrown: ViaCep::ApiRequestError
 
-# especificando um timeout em segundos...
+# and specifying a timeout in seconds... =)
 ViaCep::Address.new('80210130', timeout: 0.2)
 => exception thrown: Timeout::Error (execution expired)
 ```
 
-## Contribuindo
+## Contributing
 
-1. Faça um fork (https://github.com/vnbrs/viacep/fork)
-2. Crie uma branch (git checkout -b my-new-feature)
-3. Faça um commit  (git commit -am 'Add some feature')
-4. Faça o push (git push origin my-new-feature)
-5. Crie um Pull Request
-6. Valeu! 🤙🏼
-
-## Contribuidores
-
-- [vnbrs](https://github.com/vnbrs) Vinicius Brasil - creator, maintainer
+1. Create a fork (https://github.com/vnbrs/viacep/fork)
+2. Create a branch (git checkout -b my-new-feature)
+3. Make a commit  (git commit -am 'Add some feature')
+4. Push your code (git push origin my-new-feature)
+5. Create a Pull Request
+6. Thanks! 🤙🏼

data/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-minimal

data/lib/viacep.rb

@@ -1,5 +1,5 @@
 module ViaCep
-  VERSION = "2.0.2".freeze
+  VERSION = "2.0.3".freeze
 
   require_relative "viacep/address"
   require_relative "viacep/exceptions"

data/lib/viacep/address.rb

@@ -4,7 +4,27 @@ module ViaCep
   class Address
     attr_reader :cep, :address, :neighborhood, :city, :state, :ibge, :gia
 
-    # Initializes an instance of Address and fetches the CEP using the external API
+    #
+    # Initializes an instance of ViaCep::Address and fetches the CEP using the external API.
+    #
+    # @example Fetch a CEP
+    #   ViaCep::Address.new('80210130')
+    #   #=> #<ViaCep::Address:0x00007fe52a8a0568 @cep="80210-130", @address="Rua José Ananias Mauad", @neighborhood="Jardim Botânico", @city="Curitiba", @state="PR", @ibge="4106902", @gia="">
+    #
+    # @example Fetch a CEP with a formatted string
+    #   ViaCep::Address.new('80210-130')
+    #   #=> #<ViaCep::Address:0x00007fe52a8a0568 @cep="80210-130", @address="Rua José Ananias Mauad", @neighborhood="Jardim Botânico", @city="Curitiba", @state="PR", @ibge="4106902", @gia="">
+    #
+    # @param [String] cep The CEP to be fetched.
+    # @option options [Integer] :timeout The timeout in seconds to the request.
+    #
+    # @raise [ArgumentError] This is raised when CEP is nil.
+    # @raise [ArgumentError] This is raised when CEP format is invalid.
+    # @raise [ViaCep::ApiRequestError] This is raised when the external API is down or the CEP does not exist.
+    # @raise [Timeout::Error] This is raised when the timeout argument is specified and the request timed out.
+    #
+    # @return [ViaCep::Address]
+    #
     def initialize(cep, options = {})
       if cep.nil?
         raise ArgumentError, 'CEP cannot be nil'

data/lib/viacep/service.rb

@@ -8,7 +8,25 @@ module ViaCep
   class Service
     BASE_URL = 'https://viacep.com.br/ws'.freeze
 
-    # Fetches the ViaCEP API to request a CEP
+    #
+    # Fetches the ViaCEP API to request a CEP.
+    #
+    # @example Fetch a CEP with no timeout.
+    #   ViaCep::Service.fetch('80210130', nil)
+    #   #=> {"cep"=>"80210-130", "logradouro"=>"Rua José Ananias Mauad", "complemento"=>"", "bairro"=>"Jardim Botânico", "localidade"=>"Curitiba", "uf"=>"PR", "unidade"=>"", "ibge"=>"4106902", "gia"=>""}
+    #
+    # @example Fetch a CEP with a timeout of 30 seconds.
+    #   ViaCep::Service.fetch('80210130', 30)
+    #   #=> {"cep"=>"80210-130", "logradouro"=>"Rua José Ananias Mauad", "complemento"=>"", "bairro"=>"Jardim Botânico", "localidade"=>"Curitiba", "uf"=>"PR", "unidade"=>"", "ibge"=>"4106902", "gia"=>""}
+    #
+    # @param [String] cep The CEP to be fetched.
+    # @param [Integer, nil] timeout The timeout in seconds for the request to be finished.
+    #
+    # @raise [ViaCep::ApiRequestError] This is raised when the external API is down or the CEP does not exist.
+    # @raise [Timeout::Error] This is raised when the timeout argument is specified and the request timed out.
+    #
+    # @return [Hash]
+    #
     def self.fetch(cep, timeout)
       Timeout.timeout(timeout) do
         uri = URI("#{BASE_URL}/#{cep}/json")

data/spec/address_spec.rb

@@ -1,45 +1,51 @@
+require 'spec_helper'
+
 RSpec.describe ViaCep::Address do
   describe '#initialize' do
     context 'when a valid CEP is passed' do
-      subject(:address) { ViaCep::Address.new('80210130') }
-
       it 'returns the Address' do
+        mock_viacep_success
+
+        address = ViaCep::Address.new('80210130')
         expect(address.address).not_to be_empty
       end
     end
 
     context 'when a invalid length CEP is passed' do
       it 'raises ArgumentError' do
-        expect { ViaCep::Address.new('000000') }.
-          to raise_error(ArgumentError)
+        expect { ViaCep::Address.new('000000') }
+          .to raise_error(ArgumentError)
       end
     end
 
     context 'when a unexistent CEP is passed' do
       it 'raises ViaCep::ApiRequestError' do
-        expect { ViaCep::Address.new('00000000') }.
-          to raise_error(ViaCep::ApiRequestError)
+        mock_viacep_not_found
+        expect { ViaCep::Address.new('00000000') }
+          .to raise_error(ViaCep::ApiRequestError)
       end
     end
-  
+
     context 'when a nil CEP is passed' do
       it 'raises ArgumentError' do
-        expect { ViaCep::Address.new(nil) }.
-          to raise_error(ArgumentError)
+        expect { ViaCep::Address.new(nil) }
+          .to raise_error(ArgumentError)
       end
     end
 
     context 'when a low timeout is specified' do
       it 'raises a Timeout::Error' do
-        expect { ViaCep::Address.new('80210130', timeout: 0.001) }.
-          to raise_error(Timeout::Error)
+        mock_viacep_slow_success(delay_in_seconds: 0.01)
+        expect { ViaCep::Address.new('80210130', timeout: 0.001) }
+          .to raise_error(Timeout::Error)
       end
     end
 
     context 'when a regular timeout is specified' do
-      subject(:address) { ViaCep::Address.new('80210130', timeout: 25) }
-
       it 'returns the Address' do
+        mock_viacep_success
+
+        address = ViaCep::Address.new('80210130', timeout: 3.0)
         expect(address.address).not_to be_empty
       end
     end

data/spec/mock/request_mocker.rb

@@ -0,0 +1,28 @@
+require 'webmock/rspec'
+
+module ViaCep
+  module Test
+    module RequestMocker
+      def mock_viacep_success
+        WebMock.stub_request(:get, /viacep/).to_return(File.new("#{__dir__}/viacep_success.txt"))
+      end
+
+      def mock_viacep_not_found
+        WebMock.stub_request(:get, /viacep/).to_return(File.new("#{__dir__}/viacep_not_found.txt"))
+      end
+
+      def mock_viacep_invalid_format
+        WebMock.stub_request(:get, /viacep/).to_return(File.new("#{__dir__}/viacep_invalid_format.txt"))
+      end
+
+      def mock_viacep_slow_success(delay_in_seconds:)
+        success = lambda do |request|
+          sleep delay_in_seconds
+          File.new("#{__dir__}/viacep_success.txt")
+        end
+
+        WebMock.stub_request(:get, /viacep/).to_return(success)
+      end
+    end
+  end
+end

data/spec/mock/viacep_invalid_format.txt

@@ -0,0 +1,8 @@
+HTTP/1.1 400 Bad Request
+Server: nginx/1.14.0
+Date: Thu, 14 Feb 2019 23:35:24 GMT
+Content-Type: text/html; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+
+<h3>ViaCEP Bad Request (400)</h3>

data/spec/mock/viacep_not_found.txt

@@ -0,0 +1,17 @@
+HTTP/1.1 200 OK
+Server: nginx/1.14.0
+Date: Thu, 14 Feb 2019 23:34:10 GMT
+Content-Type: application/json; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, OPTIONS
+Access-Control-Allow-Headers: Content-Type, X-Request-With, X-Requested-By
+Access-Control-Allow-Credentials: true
+Access-Control-Max-Age: 86400
+Cache-Control: max-age=3600
+Cache-Control: public
+
+{
+  "erro": true
+}

data/spec/mock/viacep_success.txt

@@ -0,0 +1,25 @@
+HTTP/1.1 200 OK
+Server: nginx/1.14.0
+Date: Thu, 14 Feb 2019 23:32:54 GMT
+Content-Type: application/json; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, OPTIONS
+Access-Control-Allow-Headers: Content-Type, X-Request-With, X-Requested-By
+Access-Control-Allow-Credentials: true
+Access-Control-Max-Age: 86400
+Cache-Control: max-age=3600
+Cache-Control: public
+
+{
+  "cep": "13035-680",
+  "logradouro": "Avenida João Jorge",
+  "complemento": "",
+  "bairro": "Vila Industrial",
+  "localidade": "Campinas",
+  "uf": "SP",
+  "unidade": "",
+  "ibge": "3509502",
+  "gia": "2446"
+}

data/spec/service_spec.rb

@@ -1,3 +1,5 @@
+require 'spec_helper'
+
 RSpec.describe ViaCep::Service do
   it 'should have a base URL' do
     expect(ViaCep::Service::BASE_URL).not_to be_empty
@@ -6,23 +8,25 @@ RSpec.describe ViaCep::Service do
   describe '.fetch' do
     context 'when a small timeout is specified' do
       it 'raises Timeout::Error' do
-        expect { ViaCep::Service.fetch('80210130', 0.001) }.
-          to raise_error(Timeout::Error)
+        mock_viacep_slow_success(delay_in_seconds: 0.01)
+        expect { ViaCep::Service.fetch('80210130', 0.001) }
+          .to raise_error(Timeout::Error)
       end
     end
 
     context 'when a suficient timeout is specified' do
-      subject(:response) { ViaCep::Service.fetch('80210130', 25) }
-
       it 'returns the response' do
+        mock_viacep_success
+        response = ViaCep::Service.fetch('80210130', 5.0)
         expect(response).not_to be_empty
       end
     end
 
     context 'when a invalid CEP is passed' do
       it 'raises ViaCep::ApiRequestError' do
-        expect { ViaCep::Service.fetch('000000', nil) }.
-          to raise_error(ViaCep::ApiRequestError)
+        mock_viacep_invalid_format
+        expect { ViaCep::Service.fetch('000000', nil) }
+          .to raise_error(ViaCep::ApiRequestError)
       end
     end
   end

data/spec/spec_helper.rb

@@ -1,6 +1,10 @@
 require_relative '../lib/viacep'
+require_relative './mock/request_mocker'
+require 'webmock/rspec'
 
 RSpec.configure do |config|
+  config.include ViaCep::Test::RequestMocker
+
   config.expect_with :rspec do |expectations|
     expectations.include_chain_clauses_in_custom_matcher_descriptions = true
     expectations.syntax = :expect
@@ -12,4 +16,9 @@ RSpec.configure do |config|
 
   config.shared_context_metadata_behavior = :apply_to_host_groups
   config.order = :random
+
+  config.before(:each) do
+    WebMock.reset!
+    WebMock.disable_net_connect!
+  end
 end

data/viacep.gemspec

@@ -7,12 +7,13 @@ Gem::Specification.new do |s|
   s.summary       = 'Gem sem dependências e fácil de usar para busca de endereços a partir do CEP utilizando o ViaCEP'
   s.description   = 'Gem sem dependências e fácil de usar para busca de endereços a partir do CEP utilizando o ViaCEP'
   s.authors       = ['Vinicius Brasil (@vnbrs)']
-  s.email         = 'marcosbrasilaraujo@gmail.com'
+  s.email         = 'vini@hey.com'
   s.license       = 'MIT'
   s.homepage      = 'https://github.com/vnbrs/viacep'
 
   s.require_paths = ['lib']
   s.files         = `git ls-files | grep -Ev '^(test|doc|examples|.yardoc|.github)'`.split("\n")
 
-  s.add_development_dependency 'rspec', '~> 3.7'
+  s.add_development_dependency 'rspec',   '~> 3.7'
+  s.add_development_dependency 'webmock', '~> 3.8.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: viacep
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
 platform: ruby
 authors:
 - Vinicius Brasil (@vnbrs)
@@ -24,22 +24,43 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.3
 description: Gem sem dependências e fácil de usar para busca de endereços a partir
   do CEP utilizando o ViaCEP
-email: marcosbrasilaraujo@gmail.com
+email: vini@hey.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
+- LICENSE
 - README.md
+- _config.yml
 - lib/viacep.rb
 - lib/viacep/address.rb
 - lib/viacep/exceptions.rb
 - lib/viacep/service.rb
 - spec/address_spec.rb
+- spec/mock/request_mocker.rb
+- spec/mock/viacep_invalid_format.txt
+- spec/mock/viacep_not_found.txt
+- spec/mock/viacep_success.txt
 - spec/service_spec.rb
 - spec/spec_helper.rb
 - viacep.gemspec
@@ -62,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Gem sem dependências e fácil de usar para busca de endereços a partir do