viacep 1.0.0 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 975b270e25133dc39b46c6139c707879d34b52cf4d264335e20bfc29099d5e26
-  data.tar.gz: f16ffb518a74e69b62f1fbba4c08b17e8c81487a8475365d13dc680dcf8b1a7a
+  metadata.gz: d996e5aa0ad22ffabeddff59c6e01715e82506cb67ba9161c7b706c0bf3b1231
+  data.tar.gz: 511ab0884767f8c4534454ce935dde9d6da9a7e7571e72b8f72caa2c875a2bc3
 SHA512:
-  metadata.gz: 2cc2dcf8bd8ef9ad4ed68be18ab89ea0c01c7bb8784f1f9475243123d3d588d2a7c336b55431285a52a41b3104bed62acd6536268ec0fe8c6501ba6a6ced6b29
-  data.tar.gz: c7991ce8de2e218187524ac6cebbaded33991d5db420649e1044c3f1f13d8e0a21e817feb80be36f72940731bf3adbf7a21497645ddeb351e07633f83ab31908
+  metadata.gz: 8822385880160352463509f979354cd456dc72edc85f14906ab69d7d03a1a09c06c76b32d62f3daf9a449c7669a015304be9c0ecf680f1ce6f89996840a1cffb
+  data.tar.gz: 5debef0f5bd8b1babb8b268f82b62872a44d0ce59ce4f0e731e77209ebcb5a03b5e00300506abd448698fd080d12086d7186eee4b8a1633c5063adbd513aa3ef

data/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

data/.gitignore

@@ -0,0 +1,55 @@
+*.gem
+*.rbc
+/.config
+capybara-*.html
+.rspec
+/log
+/db/*.sqlite3
+/db/*.sqlite3-journal
+/public/system
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/version_tmp/
+**/tmp/*
+**.orig
+rerun.txt
+pickle-email-*.html
+
+## Specific to RubyMotion:
+config/initializers/secret_token.rb
+config/secrets.yml
+
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version*
+.ruby-gemset*
+.rvmrc*
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# if using bower-rails ignore default bower_components path bower.json files
+/vendor/assets/bower_components
+*.bowerrc
+bower.json
+
+# Ignore pow environment settings
+.powenv

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/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+gemspec

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

@@ -0,0 +1,50 @@
+<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/bc/BRA_orthographic.svg/270px-BRA_orthographic.svg.png" align="right" />
+
+# 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.
+
+## Installing
+
+You can easily install viacep through [RubyGems](https://rubygems.org/gems/viacep/):
+
+```shell
+gem install viacep
+=> Rock on! 🚀
+```
+
+or add the following to your Gemfile:
+
+```shell
+gem "viacep"
+```
+
+## Usage
+
+```ruby
+require 'viacep'
+
+# 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="">
+
+# 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">
+
+# or even an nonexistent zipcode... =(
+ViaCep::Address.new('12345678')
+=> exception thrown: ViaCep::ApiRequestError
+
+# and specifying a timeout in seconds... =)
+ViaCep::Address.new('80210130', timeout: 0.2)
+=> exception thrown: Timeout::Error (execution expired)
+```
+
+## Contributing
+
+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,24 +1,6 @@
-require 'service'
-
 module ViaCep
-  class Address
-    attr_reader :cep, :address, :neighborhood, :city, :state, :ibge, :gia
-
-    def initialize(cep, options = {})
-      cep = cep.delete('^0-9')
-      fill_from_response(Service.fetch(cep, options[:timeout]))
-    end
-
-    private
+  VERSION = "2.0.3".freeze
 
-    def fill_from_response(response)
-      @cep          = response['cep']
-      @address      = response['logradouro']
-      @neighborhood = response['bairro']
-      @city         = response['localidade']
-      @state        = response['uf']
-      @ibge         = response['ibge']
-      @gia          = response['gia']
-    end
-  end
+  require_relative "viacep/address"
+  require_relative "viacep/exceptions"
 end

data/lib/viacep/address.rb

@@ -0,0 +1,55 @@
+require_relative 'service'
+
+module ViaCep
+  class Address
+    attr_reader :cep, :address, :neighborhood, :city, :state, :ibge, :gia
+
+    #
+    # 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'
+      end
+
+      cep = cep.to_s.delete('^0-9')
+
+      if cep.length != 8
+        raise ArgumentError, 'CEP must have 8 digits'
+      end
+
+      response = Service.fetch cep, options[:timeout]
+      fill_from response
+    end
+
+    private
+
+    def fill_from(response)
+      @cep          = response['cep']
+      @address      = response['logradouro']
+      @neighborhood = response['bairro']
+      @city         = response['localidade']
+      @state        = response['uf']
+      @ibge         = response['ibge']
+      @gia          = response['gia']
+    end
+  end
+end

data/lib/{exceptions.rb → viacep/exceptions.rb}

@@ -1,4 +1,4 @@
 module ViaCep
   class Error < StandardError; end
-  class AddressNotFound < Error; end
+  class ApiRequestError < Error; end
 end

data/lib/viacep/service.rb

@@ -0,0 +1,49 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'timeout'
+require_relative 'exceptions'
+
+module ViaCep
+  class Service
+    BASE_URL = 'https://viacep.com.br/ws'.freeze
+
+    #
+    # 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")
+        request = Net::HTTP.get_response(uri)
+
+        if request.code == '200'
+          response = JSON.parse(request.body)
+
+          if response["erro"]
+            raise ApiRequestError, "The server responded with HTTP 200 could not process the request"
+          end
+
+          response
+        else
+          raise ApiRequestError, "The server responded with HTTP #{request.code}"
+        end
+      end
+    end
+  end
+end

data/spec/address_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+RSpec.describe ViaCep::Address do
+  describe '#initialize' do
+    context 'when a valid CEP is passed' do
+      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)
+      end
+    end
+
+    context 'when a unexistent CEP is passed' do
+      it 'raises ViaCep::ApiRequestError' do
+        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)
+      end
+    end
+
+    context 'when a low timeout is specified' do
+      it 'raises a Timeout::Error' do
+        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
+      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
+  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

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+RSpec.describe ViaCep::Service do
+  it 'should have a base URL' do
+    expect(ViaCep::Service::BASE_URL).not_to be_empty
+  end
+
+  describe '.fetch' do
+    context 'when a small timeout is specified' do
+      it 'raises Timeout::Error' do
+        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
+      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
+        mock_viacep_invalid_format
+        expect { ViaCep::Service.fetch('000000', nil) }
+          .to raise_error(ViaCep::ApiRequestError)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+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
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  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

@@ -0,0 +1,19 @@
+require File.expand_path('../lib/viacep', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name          = 'viacep'
+  s.version       = ViaCep::VERSION
+  s.date          = '2018-05-02'
+  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         = '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 'webmock', '~> 3.8.3'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: viacep
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.3
 platform: ruby
 authors:
 - Vinicius Brasil (@vnbrs)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-29 00:00:00.000000000 Z
+date: 2018-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -25,29 +25,46 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.7'
 - !ruby/object:Gem::Dependency
-  name: httparty
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.13.7
-  type: :runtime
+        version: 3.8.3
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.13.7
-description: 
-email: vnbrs@icloud.com
+        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: vini@hey.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/exceptions.rb
-- lib/service.rb
+- ".editorconfig"
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- _config.yml
 - lib/viacep.rb
-homepage: 
+- 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
+homepage: https://github.com/vnbrs/viacep
 licenses:
 - MIT
 metadata: {}
@@ -66,10 +83,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Gem responsável por buscar endereços a partir do CEP utilizando a API do
-  ViaCEP com features úteis como timeout.
+summary: Gem sem dependências e fácil de usar para busca de endereços a partir do
+  CEP utilizando o ViaCEP
 test_files: []

data/lib/service.rb

@@ -1,20 +0,0 @@
-require 'httparty'
-require 'timeout'
-require 'exceptions'
-
-module ViaCep
-  class Service
-    BASE_URI = 'https://viacep.com.br/ws'
-
-    def self.fetch(cep, timeout = nil)
-      Timeout::timeout(timeout) do
-        response = HTTParty.get("#{BASE_URI}/#{cep}/json")
-        if response.code == 404 || response.parsed_response['erro']
-          raise AddressNotFound, 'the API responded with HTTP 404'
-        else
-          response.parsed_response
-        end
-      end
-    end
-  end
-end