contentful 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6b4c5fc8a4dc2ae13b7ee0fe9e0444e995b921bf
-  data.tar.gz: 9f38b091341e8b0137292070a7ae9b10ccdcab7d
+  metadata.gz: 646bf441930ec6ed1182365e92ec26213a7c1326
+  data.tar.gz: fc8535671280aed058b63ade0bb1539bfb61a6df
 SHA512:
-  metadata.gz: b09b93dab0ba708a502cb898dd3dd05f23693053b517594f2f18faf2b0955ddc468868ccb9828eb9fdff50ebf951d45310d5b29e4e373bda90969dbeec714fe3
-  data.tar.gz: 3d0aaeca5389a70b4d7e957e982996dbf16e9593a5fb6df3f529ce6ffc7474c07b669460d300c681406edc57dd86d6ec257b8b6e309a107608bad5234b1f1e4c
+  metadata.gz: 5f16eec5e3b322607af9f58d26e64baef7f1d1d2fdc32ebbd5404618c02692ce8bd517b0b28f0877a535614784abfc906af2d7c2a8e810744b0106cd5a8ea81f
+  data.tar.gz: be5ccf489cb21a2e1e9f98eeb155cf30be2f655cdc850cef208498310f111dcf1eaaf56973db5c727fc1e6ef3a1f3316d563fa70ff996befb5e26a3f020747f7

data/.gitignore

@@ -1,5 +1,7 @@
 pkg
+doc/
+.yardoc/
 coverage
 Gemfile.lock
 .idea
-*.DS_Store
+*.DS_Store

data/.rubocop.yml

@@ -0,0 +1,25 @@
+inherit_from: .rubocop_todo.yml
+
+Encoding:
+  Enabled: false
+
+Metrics/ClassLength:
+  CountComments: false
+
+Metrics/MethodLength:
+  CountComments: false
+
+AllCops:
+  Exclude:
+    - contentful.gemspec
+    - spec/**/*
+    - examples/**/*
+    - Guardfile
+    - Gemfile
+    - Rakefile
+
+Metrics/ClassLength:
+  Max: 230
+
+Style/MutableConstant:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,35 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2016-02-02 13:30:13 -0300 using RuboCop version 0.36.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 6
+Metrics/AbcSize:
+  Max: 38
+
+# Offense count: 5
+Metrics/CyclomaticComplexity:
+  Max: 8
+
+# Offense count: 1
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes.
+# URISchemes: http, https
+Metrics/LineLength:
+  Max: 142
+
+# Offense count: 12
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 27
+
+# Offense count: 2
+# Configuration parameters: CountComments.
+Metrics/ModuleLength:
+  Max: 499
+
+# Offense count: 4
+Metrics/PerceivedComplexity:
+  Max: 8

data/.travis.yml

@@ -9,3 +9,8 @@ rvm:
 notifications:
   slack:
     secure: Zr3mKCiTb0vaTD4MPtTG8BbyYyErFuoxioM25QyrqePKVkDFeZC1MtGmg5klQQrJiWTKZPa/zB8NAHYkoUxg9I+z15JK0hYfz9KRubEpCrXCaqTC9Vzq88kJ3LN8YsTyBF66izaBH2KLsOfaJRxwplFzZqgpg4GG2DUBPtrGtes=
+before_install: gem install bundler -v 1.10.6
+script: bundle exec rake rspec_rubocop
+matrix:
+  allow_failures:
+    - rvm: jruby

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Change Log
 ## Unreleased
 
+## 0.9.0
+### Added
+* Added `Contentful::Resource::CustomResource` to automatically map fields to accessors [#79](https://github.com/contentful/contentful.rb/issues/79)
+* Added `#raw` to `Contentful::Resource` for easier Marshalling
+* Added documentation regarding locales
+
+### Changed
+* Changed Documentation Format to YARD
+
+### Fixed
+* Fixed Marshalling for Custom Resource Classes [#80](https://github.com/contentful/contentful.rb/issues/80)
+
 ## 0.8.0
 ### Changed
 * Unified Locale Handling [#73](https://github.com/contentful/contentful.rb/issues/73)

data/Guardfile

@@ -1,42 +1,24 @@
-# A sample Guardfile
-# More info at https://github.com/guard/guard#readme
+group :green_red_refactor, halt_on_fail: true do
+  guard :rspec, cmd: "bundle exec rspec" do
+    require "guard/rspec/dsl"
+    dsl = Guard::RSpec::Dsl.new(self)
 
-## Uncomment and set this to only include directories you want to watch
-# directories %w(app lib config test spec features) \
-#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+    # Feel free to open issues for suggestions and improvements
 
-## Note: if you are using the `directories` clause above and you are not
-## watching the project directory ('.'), then you will want to move
-## the Guardfile to a watched dir and symlink it back, e.g.
-#
-#  $ mkdir config
-#  $ mv Guardfile config/
-#  $ ln -s config/Guardfile .
-#
-# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+    # RSpec files
+    rspec = dsl.rspec
+    watch(rspec.spec_helper) { rspec.spec_dir }
+    watch(rspec.spec_support) { rspec.spec_dir }
+    watch(rspec.spec_files)
 
-# Note: The cmd option is now required due to the increasing number of ways
-#       rspec may be run, below are examples of the most common uses.
-#  * bundler: 'bundle exec rspec'
-#  * bundler binstubs: 'bin/rspec'
-#  * spring: 'bin/rspec' (This will use spring if running and you have
-#                          installed the spring binstubs per the docs)
-#  * zeus: 'zeus rspec' (requires the server to be started separately)
-#  * 'just' rspec: 'rspec'
+    # Ruby files
+    ruby = dsl.ruby
+    dsl.watch_spec_files_for(ruby.lib_files)
+  end
 
-guard :rspec, cmd: "bundle exec rspec" do
-  require "guard/rspec/dsl"
-  dsl = Guard::RSpec::Dsl.new(self)
+  guard :yard, cmd: "yard doc" do
+  end
 
-  # Feel free to open issues for suggestions and improvements
-
-  # RSpec files
-  rspec = dsl.rspec
-  watch(rspec.spec_helper) { rspec.spec_dir }
-  watch(rspec.spec_support) { rspec.spec_dir }
-  watch(rspec.spec_files)
-
-  # Ruby files
-  ruby = dsl.ruby
-  dsl.watch_spec_files_for(ruby.lib_files)
+  guard :rubocop, cmd: "rubocop" do
+  end
 end

data/README.md

@@ -100,6 +100,27 @@ Dynamic entries will have getter classes for the fields and do type conversions
 
 The `:auto` mode will fetch all content types on initialization. If you want to do it by hand later, you will need to set the option to `:manual` and call `client.update_dynamic_entry_cache!` to initialize all dynamic entries.
 
+#### Using different locales
+
+Entries can have multiple locales, by default, the client only fetches the entry with only its default locale.
+If you want to fetch a different locale you can do the following:
+
+```ruby
+entries = client.entries(locale: 'de-DE')
+```
+
+Then all the fields will be fetched for the requested locale.
+
+Contentful Delivery API also allows to fetch all locales, you can do so by doing:
+
+```ruby
+entries = client.entries(content_type: 'cat', locale: '*')
+
+# assuming the entry has a field called name
+my_spanish_name = entries.first.fields('es-AR')[:name]
+```
+
+When requesting multiple locales, the object accessor shortcuts only work for the default locale.
 
 ### Arrays
 
@@ -277,6 +298,19 @@ client = Contentful::Client.new(
 client.entry('nyancat') # is instance of Cat
 ```
 
+If you want to use the `property :field_name` syntax, you can do it the following way:
+
+```ruby
+class Cat < Contentful::Entry
+  include Contentful::Resource::CustomResource
+
+  property :name
+  property :lives
+  property :bestFriend
+  # ...
+end
+```
+
 ## Synchronization
 
 The client also includes a wrapper for the synchronization endpoint. You can initialize it with the options described in the [Delivery API Documentation](https://www.contentful.com/developers/documentation/content-delivery-api/#sync) or an URL you received from a previous sync:

data/Rakefile

@@ -24,5 +24,10 @@ Gem::Tasks.new
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new
 
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new
+
+task rspec_rubocop: %w(spec rubocop)
+
 task test: :spec
 task default: :spec

data/contentful.gemspec

@@ -24,6 +24,9 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency 'guard'
   gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'guard-rubocop'
+  gem.add_development_dependency 'guard-yard'
+  gem.add_development_dependency 'rubocop'
   gem.add_development_dependency 'rspec', '~> 2'
   gem.add_development_dependency 'rr'
   gem.add_development_dependency 'vcr'

data/lib/contentful.rb

@@ -1,3 +1,4 @@
 require 'contentful/version'
 require 'contentful/support'
 require 'contentful/client'
+require 'contentful/resource/custom_resource'

data/lib/contentful/array.rb

@@ -3,9 +3,10 @@ require_relative 'resource/array_like'
 
 module Contentful
   # Resource Class for Arrays (e.g. search results)
-  # https://www.contentful.com/developers/documentation/content-delivery-api/#arrays
-  # It also provides an #each method and includes Ruby's Enumerable module (gives you methods like #min, #first, etc)
+  # @see _ https://www.contentful.com/developers/documentation/content-delivery-api/#arrays
+  # @note It also provides an #each method and includes Ruby's Enumerable module (gives you methods like #min, #first, etc)
   class Array
+    # @private
     DEFAULT_LIMIT = 100
 
     include Contentful::Resource
@@ -18,6 +19,8 @@ module Contentful
     property :items
 
     # Simplifies pagination
+    #
+    # @return [Contentful::Array, false]
     def next_page
       if request
         new_skip    = (skip || 0) + (limit || DEFAULT_LIMIT)

data/lib/contentful/asset.rb

@@ -9,20 +9,23 @@ module Contentful
     include Contentful::Resource::SystemProperties
     include Contentful::Resource::AssetFields
 
-    # Returns the image url of an asset
-    # Allows you to pass in the following options for image resizing:
-    #   :width
-    #   :height
-    #   :format
-    #   :quality
-    # See https://www.contentful.com/developers/documentation/content-delivery-api/#image-asset-resizing
+    # Generates a URL for the Contentful Image API
+    #
+    # @param [Hash] options
+    # @option options [Integer] :width
+    # @option options [Integer] :height
+    # @option options [String] :format
+    # @option options [String] :quality
+    # @see _ https://www.contentful.com/developers/documentation/content-delivery-api/#image-asset-resizing
+    #
+    # @return [String] Image API URL
     def image_url(options = {})
       query = {
-        w:   options[:w]  || options[:width],
-        h:   options[:h]  || options[:height],
-        fm:  options[:fm] || options[:format],
-        q:   options[:q]  || options[:quality],
-        f:   options[:f]  || options[:focus],
+        w: options[:w] || options[:width],
+        h: options[:h] || options[:height],
+        fm: options[:fm] || options[:format],
+        q: options[:q] || options[:quality],
+        f: options[:f] || options[:focus],
         fit: options[:fit]
       }.reject { |_k, v| v.nil? }
 

data/lib/contentful/client.rb

@@ -11,6 +11,7 @@ module Contentful
   # for querying resources from this space.
   # See README for details
   class Client
+    # Default configuration for Contentful::Client
     DEFAULT_CONFIGURATION = {
       secure: true,
       raise_errors: true,
@@ -35,6 +36,7 @@ module Contentful
     attr_reader :configuration, :dynamic_entry_cache, :logger, :proxy
 
     # Wraps the actual HTTP request via proxy
+    # @private
     def self.get_http(url, query, headers = {}, proxy = {})
       if proxy[:host]
         HTTP[headers].via(proxy[:host], proxy[:port], proxy[:username], proxy[:password]).get(url, params: query)
@@ -43,6 +45,25 @@ module Contentful
       end
     end
 
+    # @see _ https://github.com/contentful/contentful.rb#client-configuration-options
+    # @param [Hash] given_configuration
+    # @option given_configuration [String] :space Required
+    # @option given_configuration [String] :access_token Required
+    # @option given_configuration [String] :api_url Modifying this to 'preview.contentful.com' gives you access to our Preview API
+    # @option given_configuration [String] :api_version
+    # @option given_configuration [String] :default_locale
+    # @option given_configuration [String] :proxy_host
+    # @option given_configuration [String] :proxy_username
+    # @option given_configuration [String] :proxy_password
+    # @option given_configuration [Number] :proxy_port
+    # @option given_configuration [Boolean] :gzip_encoded
+    # @option given_configuration [Boolean] :raw_mode
+    # @option given_configuration [false, ::Logger] :logger
+    # @option given_configuration [::Logger::DEBUG, ::Logger::INFO, ::Logger::WARN, ::Logger::ERROR] :log_level
+    # @option given_configuration [Boolean] :raise_errors
+    # @option given_configuration [::Array<String>] :dynamic_entries
+    # @option given_configuration [::Hash<String, Contentful::Resource>] :resource_mapping
+    # @option given_configuration [::Hash<String, Contentful::Resource>] :entry_mapping
     def initialize(given_configuration = {})
       @configuration = default_configuration.merge(given_configuration)
       normalize_configuration!
@@ -56,11 +77,13 @@ module Contentful
       end
     end
 
+    # @private
     def setup_logger
       @logger = configuration[:logger]
       logger.level = configuration[:log_level] if logger
     end
 
+    # @private
     def proxy_params
       {
         host: configuration[:proxy_host],
@@ -71,65 +94,85 @@ module Contentful
     end
 
     # Returns the default configuration
+    # @private
     def default_configuration
       DEFAULT_CONFIGURATION.dup
     end
 
     # Gets the client's space
-    # Takes an optional hash of query options
-    # Returns a Contentful::Space
+    #
+    # @param [Hash] query
+    #
+    # @return [Contentful::Space]
     def space(query = {})
       Request.new(self, '', query).get
     end
 
     # Gets a specific content type
-    # Takes an id and an optional hash of query options
-    # Returns a Contentful::ContentType
+    #
+    # @param [String] id
+    # @param [Hash] query
+    #
+    # @return [Contentful::ContentType]
     def content_type(id, query = {})
       Request.new(self, '/content_types', query, id).get
     end
 
     # Gets a collection of content types
-    # Takes an optional hash of query options
-    # Returns a Contentful::Array of Contentful::ContentType
+    #
+    # @param [Hash] query
+    #
+    # @return [Contentful::Array<Contentful::ContentType>]
     def content_types(query = {})
       Request.new(self, '/content_types', query).get
     end
 
     # Gets a specific entry
-    # Takes an id and an optional hash of query options
-    # Returns a Contentful::Entry
+    #
+    # @param [String] id
+    # @param [Hash] query
+    #
+    # @return [Contentful::Entry]
     def entry(id, query = {})
       Request.new(self, '/entries', query, id).get
     end
 
     # Gets a collection of entries
-    # Takes an optional hash of query options
-    # Returns a Contentful::Array of Contentful::Entry
+    #
+    # @param [Hash] query
+    #
+    # @return [Contentful::Array<Contentful::Entry>]
     def entries(query = {})
       Request.new(self, '/entries', query).get
     end
 
     # Gets a specific asset
-    # Takes an id and an optional hash of query options
-    # Returns a Contentful::Asset
+    #
+    # @param [String] id
+    # @param [Hash] query
+    #
+    # @return [Contentful::Asset]
     def asset(id, query = {})
       Request.new(self, '/assets', query, id).get
     end
 
     # Gets a collection of assets
-    # Takes an optional hash of query options
-    # Returns a Contentful::Array of Contentful::Asset
+    #
+    # @param [Hash] query
+    #
+    # @return [Contentful::Array<Contentful::Asset>]
     def assets(query = {})
       Request.new(self, '/assets', query).get
     end
 
     # Returns the base url for all of the client's requests
+    # @private
     def base_url
       "http#{configuration[:secure] ? 's' : ''}://#{configuration[:api_url]}/spaces/#{configuration[:space]}"
     end
 
     # Returns the headers used for the HTTP requests
+    # @private
     def request_headers
       headers = { 'User-Agent' => "RubyContentfulGem/#{Contentful::VERSION}" }
       headers['Authorization'] = "Bearer #{configuration[:access_token]}" if configuration[:authentication_mechanism] == :header
@@ -139,6 +182,7 @@ module Contentful
     end
 
     # Patches a query hash with the client configurations for queries
+    # @private
     def request_query(query)
       if configuration[:authentication_mechanism] == :query_string
         query['access_token'] = configuration[:access_token]
@@ -149,26 +193,28 @@ module Contentful
     # Get a Contentful::Request object
     # Set second parameter to false to deactivate Resource building and
     # return Response objects instead
+    #
+    # @private
     def get(request, build_resource = true)
       url = request.absolute? ? request.url : base_url + request.url
       logger.info(request: { url: url, query: request.query, header: request_headers }) if logger
       response = Response.new(
-          self.class.get_http(
-              url,
-              request_query(request.query),
-              request_headers,
-              proxy_params
-          ), request
+        self.class.get_http(
+          url,
+          request_query(request.query),
+          request_headers,
+          proxy_params
+        ), request
       )
 
       return response if !build_resource || configuration[:raw_mode]
       logger.debug(response: response) if logger
       result = configuration[:resource_builder].new(
-          self,
-          response,
-          configuration[:resource_mapping],
-          configuration[:entry_mapping],
-          configuration[:default_locale]
+        self,
+        response,
+        configuration[:resource_mapping],
+        configuration[:entry_mapping],
+        configuration[:default_locale]
       ).run
 
       fail result if result.is_a?(Error) && configuration[:raise_errors]
@@ -177,6 +223,7 @@ module Contentful
 
     # Use this method together with the client's :dynamic_entries configuration.
     # See README for details.
+    # @private
     def update_dynamic_entry_cache!
       @dynamic_entry_cache = Hash[
                              content_types(limit: 1000).map do |ct|
@@ -190,13 +237,18 @@ module Contentful
 
     # Use this method to manually register a dynamic entry
     # See examples/dynamic_entries.rb
+    # @private
     def register_dynamic_entry(key, klass)
       @dynamic_entry_cache[key.to_sym] = klass
     end
 
     # Create a new synchronisation object
-    # Takes sync options or a sync_url
-    # You will need to call #each_page or #first_page on it
+    #
+    # @param [Hash, String] options Options or Sync URL
+    #
+    # @note You will need to call #each_page or #first_page on it
+    #
+    # @return [Contentful::Sync]
     def sync(options = { initial: true })
       Sync.new(self, options)
     end
@@ -209,33 +261,23 @@ module Contentful
     end
 
     def validate_configuration!
-      if configuration[:space].empty?
-        fail ArgumentError, 'You will need to initialize a client with a :space'
-      end
+      fail ArgumentError, 'You will need to initialize a client with a :space' if configuration[:space].empty?
 
-      if configuration[:access_token].empty?
-        fail ArgumentError, 'You will need to initialize a client with an :access_token'
-      end
+      fail ArgumentError, 'You will need to initialize a client with an :access_token' if configuration[:access_token].empty?
 
-      if configuration[:api_url].empty?
-        fail ArgumentError, 'The client configuration needs to contain an :api_url'
-      end
+      fail ArgumentError, 'The client configuration needs to contain an :api_url' if configuration[:api_url].empty?
 
-      if configuration[:default_locale].empty?
-        fail ArgumentError, 'The client configuration needs to contain a :default_locale'
-      end
+      fail ArgumentError, 'The client configuration needs to contain a :default_locale' if configuration[:default_locale].empty?
 
-      unless configuration[:api_version].to_i >= 0
-        fail ArgumentError, 'The :api_version must be a positive number or nil'
-      end
+      fail ArgumentError, 'The :api_version must be a positive number or nil' unless configuration[:api_version].to_i >= 0
 
-      unless [:header, :query_string].include? configuration[:authentication_mechanism]
-        fail ArgumentError, 'The authentication mechanism must be :header or :query_string'
-      end
+      fail ArgumentError, 'The authentication mechanism must be :header or :query_string' unless [:header, :query_string].include?(
+        configuration[:authentication_mechanism]
+      )
 
-      unless [:auto, :manual].include? configuration[:dynamic_entries]
-        fail ArgumentError, 'The :dynamic_entries mode must be :auto or :manual'
-      end
+      fail ArgumentError, 'The :dynamic_entries mode must be :auto or :manual' unless [:auto, :manual].include?(
+        configuration[:dynamic_entries]
+      )
     end
   end
 end