adwords4r 15.0.1 → 15.1.0

data/ChangeLog.txt

@@ -1,3 +1,24 @@
+15.1.0
+- Added downloadCsvReport extension to the Report Service, downloads a report as CSV data.
+- Added getMethodUsage extension to the Info Service, returns a breakdown of API usage per method.
+- Added getClientUnitsUsage extension to the Info Service, returns a smart breakdown of API usage per account.
+- Service wrappers are now generated during the "rake generate" step of setup, instead of at runtime.
+  The files are created in the lib/adwords4r/v* directories.
+- Added client-side type and arity safety checks for API calls.
+  An ArgumentError will now be thrown if an API call gets an invalid number of arguments or arguments of an incorrect type.
+- Added CSV files with various lists of information (categories, countries, etc.) and utility methods to retrieve them.
+  They can be found in the newly-created AdWords::Utils module.
+- Added several subclasses of ApiError to allow for finer exception handling.
+  The correct subclass gets instanced automatically whenever a SOAP fault occurs.
+- Added unit tests for the client library functionality.
+- Added RDoc comments to client library and an RDoc generation task to the Rakefile.
+  Pre-generated documentation is also included in the doc/ directory.
+- Added unit_spend example and extended the reports one.
+- Fixed packaging issues.
+- Fixed bug in multiple_versions example.
+- Several additions and changes to the Readme.
+- Cleaned up Rakefile.
+
 15.0.1
 - Bugfix: added generation of ApiError exceptions upon SOAP faults.
 
@@ -19,8 +40,8 @@
   This allows for correct tracking with multiple AdWords::API objects.
   The methods have been renamed total_units and last_units to fit with the getter conventions.
 - Made code style more coherent.
-- Updated v13 code samples to work with new client library model.
-- Added v200902 and multiple version code samples.
+- Updated v13 examples to work with new client library model.
+- Added v200902 and multiple version examples.
 
 14.0.0
 - Sérgio Gomes (api.sgomes@gmail.com) takes over as maintainer of this project.
@@ -69,22 +90,38 @@
 - used soap4r v1.5.6 to generate the API files from the WSDL
 - added soap4r v1.5.6 and http-access2 v2.0.5 as gem dependencies
 - cleaned up some of the kludges that were needed for older soap4r libraries
+
 0.8
 - Ryan Leavengood takes over as maintainer of this project
 - added support for APIs v7, v8 and v9
 - removed support for v4 and v5
 - updated the examples amd made it so they will use the adwords4r in their parent directory
+
 0.7
 - added support for API v6
 - uncommented clientEmail in sample property file
+
 0.6
 - added support for API v5
 - added support for alternateUrl header, in order to work with sandbox
 - tested with sandbox
-0.5 Now supports AdWords API v4. Got rid of yaml dependency. Changed properties file name for default credentials to adwords.properties. Enhanced the readme.txt a bit. Added a few samples.
-0.4 Now all generated classes are within the Adwords module. Will make it easier to use that in Rails. Support for gen classes in a module is not implemented in soap4r for doc/literal style (it works for rpc/encoded). I logged a bug for soap4r. In the meantime I had to fix adwords4r from my module using module_eval to patch the Mapping class.
-0.3 fixed the bug in InfoService and many others. I fix the wsdl before generation.
-0.2 added packaging, made it a gem, and added a setup program, for easy installation in all configurations (gem and non gem).
+
+0.5
+- Now supports AdWords API v4.
+- Got rid of yaml dependency.
+- Changed properties file name for default credentials to adwords.properties.
+- Enhanced the readme.txt a bit. Added a few samples.
+
+0.4
+- Now all generated classes are within the Adwords module. Will make it easier to use that in Rails.
+- Support for gen classes in a module is not implemented in soap4r for doc/literal style (it works for rpc/encoded). I logged a bug for soap4r. In the meantime I had to fix adwords4r from my module using module_eval to patch the Mapping class.
+
+0.3
+- fixed the bug in InfoService and many others. I fix the wsdl before generation.
+
+0.2
+- added packaging, made it a gem, and added a setup program, for easy installation in all configurations (gem and non gem).
+
 0.1 -first version, not fully tested
-works for Campaigns
+- works for Campaigns
 

data/Rakefile

@@ -1,156 +1,274 @@
+#!/usr/bin/ruby
+#
+# Copyright 2009, Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Rakefile for adwords4r.
+
+# A little trick so we can load things from the lib/ directory without having
+# to patch the "require" statements in the files
+$LOAD_PATH << File.join(File.dirname(__FILE__), 'lib')
+
 require 'fileutils'
 require 'net/https'
 require 'logger'
-require 'rake/clean'
-
 require 'rubygems'
 gem 'rake'
 require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/clean'
+require 'rake/testtask'
 gem 'soap4r'
 require 'wsdl/soap/wsdl2ruby'
 require 'xsd/codegen/classdef'
+require 'adwords4r/services'
+require 'adwords4r/apiextensions'
 
-require 'lib/adwords4r/services'
-
-# Determine the current version of the software
-
-CLOBBER.include('pkg')
-
-CURRENT_VERSION = '15.0.1'
+# Configure some constants and built-in tasks
+CURRENT_VERSION = '15.1.0'
 PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
 
-SRC_RB = FileList['lib/**/*.rb']
-
 WSDLDIR = 'wsdl'
 LIBDIR = 'lib'
-GENDIR = LIBDIR + '/adwords4r'
+DOCDIR = 'doc'
+TESTDIR = 'test'
+GENDIR = File.join(LIBDIR, 'adwords4r')
+
+SRC_RB = FileList["#{LIBDIR}/**/*.rb"]
 
 logger = Logger.new(STDERR)
 
 CLEAN.include(WSDLDIR)
-AdWords::Service.get_versions.each do |v|
-  vname = "v#{v}"
-  CLEAN.include(File.join(GENDIR, vname))
+CLEAN.include(DOCDIR)
+AdWords::Service.get_versions.each do |version|
+  version_name = "v#{version}"
+  CLEAN.include(File.join(GENDIR, version_name))
 end
 
+CLOBBER.include('pkg')
+
+# ====================================================================
+# Create a default task to prepare library for usage.
 desc "gets the wsdl and generates the classes"
 task :default => [:getwsdl, :generate]
 
+# ====================================================================
+# Create a task to retrieve the WSDL files for the services.
 desc "gets the wsdl files for AdWords services"
 task :getwsdl do
-  AdWords::Service.get_versions.each do |v|
-    vname = "v#{v}"
-    mkdir_p File.join(WSDLDIR, vname)
-    AdWords::Service.get_services(v).each do |s|
-      if v.to_i <= 13
+  AdWords::Service.get_versions.each do |version|
+    version_name = "v#{version}"
+    mkdir_p File.join(WSDLDIR, version_name)
+    AdWords::Service.get_services(version).each do |service|
+      if version <= 13
         save(getfile("adwords.google.com",
-                     "/api/adwords/#{vname}/#{s}Service?wsdl"),
-             get_wsdl_file_name(vname, s))
+                     "/api/adwords/#{version_name}/#{service}Service?wsdl"),
+             get_wsdl_file_name(version_name, service))
       else
         save(getfile("adwords-sandbox.google.com",
-                     "/api/adwords/cm/#{vname}/#{s}Service?wsdl"),
-             get_wsdl_file_name(vname, s))
+                     "/api/adwords/cm/#{version_name}/#{service}Service?wsdl"),
+             get_wsdl_file_name(version_name, service))
       end
     end
   end
 end
 
+# Return the full file name of the WSDL file for a given version and service
+def get_wsdl_file_name(version_name, service)
+  File.join(WSDLDIR, version_name, service) + '.wsdl'
+end
+
+# Download a file, given a remote host and path (assume HTTPS)
+def getfile(host, path)
+  puts "getting https://#{host}#{path}"
+  https = Net::HTTP.new(host, 443)
+  https.use_ssl = true
+  https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+  https.start { |w| w.get2(path).body }
+end
+
+# Apply fixes to the WSDL content in order to make it understandable for the
+# soap4r code generator. The fixes are applied to the original object.
+def fix_wsdl!(wsdl)
+  ['type', 'base'].each do |name|
+    ['long', 'string', 'date', 'int', 'boolean'].each do |type|
+      # Fix this attribute over the entire document
+      wsdl.gsub!(Regexp.new("#{name}=\"#{type}\""), "#{name}=\"xsd:#{type}\"")
+    end
+  end
+  schema_ns = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
+  if wsdl !~ Regexp.new(schema_ns)
+    wsdl.gsub!(/(<wsdl:definitions[^>]*)>/, '\1 ' + schema_ns + '>')
+  end
+  return wsdl
+end
+
+# Saves this document to the specified path.
+# Doesn't create the file if a 404 error page is returned.
+def save(content, path)
+  if content !~ /<H2>Error 404<\/H2>/
+    File::open(path, 'w') {|f| f.write(fix_wsdl!(content))}
+  end
+end
+
+# ====================================================================
+# Create a task to generate all the service classes.
 desc "generates AdWords classes from the wsdl files"
 task :generate do
-  AdWords::Service.get_versions.each do |v|
-    vname = "v#{v}"
-    gendir = "#{LIBDIR}/adwords4r/#{vname}"
+  AdWords::Service.get_versions.each do |version|
+    version_name = "v#{version}"
+    gendir = File.join(LIBDIR, 'adwords4r', version_name)
     mkdir_p gendir
-    AdWords::Service.get_services(v).each do |name|
+    AdWords::Service.get_services(version).each do |service|
+      # Generate SOAP classes with soap4r
+      service_name = service + 'Service'
       worker = WSDL::SOAP::WSDL2Ruby.new
       worker.logger = logger
-      worker.location = get_wsdl_file_name(vname,name)
+      worker.location = get_wsdl_file_name(version_name, service)
       worker.basedir = gendir
-      worker.opt.update(get_wsdl_opt(vname,name))
+      worker.opt.update(get_wsdl_opt(version_name, service_name))
       worker.run
-      fix_import(v, File.join(gendir, "#{name}Driver.rb"))
-      fix_import(v, File.join(gendir, "#{name}MappingRegistry.rb"))
-      fix_import(v, File.join(gendir, "#{name}.rb"))
+
+      # Fix the "require" statements so that they work in the client library's
+      # directory structure
+      fix_import(version_name, File.join(gendir, "#{service_name}Driver.rb"))
+      fix_import(version_name,
+          File.join(gendir, "#{service_name}MappingRegistry.rb"))
+      fix_import(version_name, File.join(gendir, "#{service_name}.rb"))
+
+      # Fix the comments in the file so that we get better-looking RDoc, and
+      # only for the things we want
+      fix_rdoc(File.join(gendir, "#{service_name}.rb"))
+
+      # Generate the wrapper files
+      eval("require '#{File.join(gendir, "#{service_name}Driver.rb")}'")
+      wrapper_file = File.join(gendir, "#{service_name}Wrapper.rb")
+      File.open(wrapper_file, 'w') do |file|
+        file.write(AdWords::Service.generate_wrapper_class(version, service))
+      end
+      puts "Generated #{version_name} #{service_name} wrapper: #{wrapper_file}"
+    end
+  end
+end
+
+# Fix "require" statements for client lib usage
+def fix_import(version_name, file)
+  tempfile = file + '.tmp'
+  outfile = File.new(tempfile, 'w')
+  File.open(file, 'r') do |infile|
+    infile.each do |line|
+      if (line =~ /require.*Service.*\.rb/)
+        outfile << line.gsub(/require '(.*)Service(.*)\.rb'/,
+            "require 'adwords4r/#{version_name}/\\1Service\\2'")
+      else
+        outfile << line
+      end
     end
   end
+  outfile.close
+  File.rename(tempfile, file)
 end
 
-def fix_import(version, file)
-  vname = "v#{version}"
+# Fix RDoc comments in the generated *Service.rb files
+def fix_rdoc(file)
   tempfile = file + '.tmp'
-  outfile = File.new(tempfile,"w")
-  File.open(file, "r") do |infile|
-    infile.each do |l|
-      if (l =~ /require.*Service.*\.rb/) then
-        outfile.puts l.gsub(/require '(.*)Service(.*)\.rb'/,
-                            "require 'adwords4r/#{vname}/\\1Service\\2'")
+  outfile = File.new(tempfile, 'w')
+  should_doc = true
+  File.open(file, 'r') do |infile|
+    infile.each do |line|
+      if (line =~ /# \{.*\}[A-Z]\w*/)
+        # This is a regular class. Document and clean up how it's displayed.
+        should_doc = true
+        outfile << line.gsub(/\{.*\}(.*)/, "\\1")
+      elsif (line =~ /# \{.*\}[a-z]\w*/)
+        # This is a method wrapping class. Do not document, but still clean up
+        # its comment.
+        should_doc = false
+        outfile << line.gsub(/\{.*\}(.*)/, "\\1")
+      elsif (line =~ /#   \w+/)
+        # Itemize member variables
+        outfile << line.gsub(/#   (.*)/, "# - \\1")
+      elsif (line =~ /class [A-Z].*/)
+        if should_doc
+          outfile << line
+        else
+          # Avoid documenting the method classes, since they're made invisible
+          # thanks to our service wrappers
+          outfile << line.gsub(/(.*)(\w)/, "\\1\\2 #:nodoc: all")
+        end
       else
-        outfile.puts l
+        outfile << line
       end
     end
   end
   outfile.close
   File.rename(tempfile, file)
-end 
+end
 
-def get_wsdl_opt(v,s)
+# Create options to be used for class generation from WSDL
+def get_wsdl_opt(version_name, service_name)
   optcmd= {}
-  s << "Service"
-  optcmd['classdef'] = s
+  optcmd['classdef'] = service_name
   optcmd['force'] = true
   optcmd['mapping_registry'] = true
   optcmd['driver'] = nil
 
   # Causes soap4r to wrap the classes it outputs into the given modules
-  optcmd['module_path'] = ['AdWords', v.capitalize, s]
+  optcmd['module_path'] = ['AdWords', version_name.capitalize, service_name]
   return optcmd
 end
 
-def get_wsdl_file_name(v,s)
-  "#{WSDLDIR}/#{v}/#{s}.wsdl"
-end
-
-def getfile(host, path)
-  puts "getting https://#{host}#{path}"
-  https = Net::HTTP.new(host, 443)
-  https.use_ssl = true
-  https.verify_mode = OpenSSL::SSL::VERIFY_NONE
-  https.start { |w| w.get2(path).body }
-end
-
-def fix_attribute(text, name, type)
-  text.gsub!(Regexp.new("#{name}=\"#{type}\""),"#{name}=\"xsd:#{type}\"")
-end
-
-def fix_wsdl(wsdl)
-  ['type', 'base'].each {|name|
-    ['long', 'string', 'date', 'int', 'boolean'].each {|type|
-      fix_attribute(wsdl, name, type)}}
-  schema_ns = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
-  if wsdl !~ Regexp.new(schema_ns)
-    wsdl.gsub!(/(<wsdl:definitions[^>]*)>/, '\1 ' + schema_ns + '>')
+# ====================================================================
+# Create a task to build the RDOC documentation tree.
+Rake::RDocTask.new("rdoc") do |rdoc|
+  # Try to use SDoc to generate the docs
+  begin
+    require 'sdoc'
+    rdoc.options << '--fmt' << 'shtml'
+    rdoc.template = 'direct'
+  rescue LoadError
+    # Do nothing, give up on SDoc and continue with whatever is the default.
   end
-  return wsdl
+  rdoc.rdoc_dir = DOCDIR
+  rdoc.title = 'adwords4r -- Client library for the AdWords API'
+  rdoc.main = 'Readme.txt'
+  rdoc.rdoc_files.include('Readme.txt', 'License.txt', 'ChangeLog.txt')
+  rdoc.rdoc_files.include("#{LIBDIR}/*.rb", "#{LIBDIR}/adwords4r/*.rb")
+  rdoc.rdoc_files.include("#{LIBDIR}/adwords4r/v*/*Wrapper.rb")
+  rdoc.rdoc_files.include("#{LIBDIR}/adwords4r/v*/*Service.rb")
+  rdoc.rdoc_files.exclude("#{LIBDIR}/adwords4r/soap4rpatches.rb")
 end
 
-# Saves this document to the specified @var path.
-# doesn't create the file if contains markup for google 404 page
-def save(content, path)
-  if content !~ /<H2>Error 404<\/H2>/
-    File::open(path, 'w') {|f| f.write(fix_wsdl(content))}
-  end
+# ====================================================================
+# Create a task to perform the unit testing.
+Rake::TestTask.new("test") do |test|
+  test.libs << TESTDIR
+  test.pattern = "#{TESTDIR}/test_*.rb"
+  test.verbose = true
 end
 
 # ====================================================================
 # Create a task that will package the Rake software into distributable
 # gem files.
-
 PKG_FILES = FileList[
   '*.*',
   'Rakefile',
-  'lib/**/*.rb',
+  "#{LIBDIR}/**/*.rb",
+  "#{LIBDIR}/adwords4r/data/*.*",
   'examples/**/*.rb',
-  'scripts/**/*.rb'
+  "#{DOCDIR}/**/*.*",
+  "#{TESTDIR}/**/*.*"
 ]
 
 PKG_FILES.exclude(/\._/)
@@ -160,33 +278,36 @@ if ! defined?(Gem)
 else
   spec = Gem::Specification.new do |s|
 
-    #### Basic information.
-
+    # Basic information
     s.name = 'adwords4r'
     s.version = PKG_VERSION
-    s.summary = "Client library for the AdWords API."
-    s.description = %{\
-Adwords4r provides an easy to use way to access the AdWords API in Ruby.\
-Currently the following AdWords API versions are supported:\
-\
-* V13\
-* V200902 (sandbox)
-}
+    s.summary = 'Client library for the AdWords API.'
+    s.description = <<-EOS
+Adwords4r provides an easy to use way to access the AdWords API in Ruby.
+Currently the following AdWords API versions are supported:
+  * V13
+  * V200902 (sandbox)
+    EOS
 
+    # Files and dependencies
     s.files = PKG_FILES.to_a
-    s.require_path = 'lib'
-    s.autorequire = 'adwords4r'
+    s.require_path = LIBDIR
+    s.add_dependency('soap4r', '= 1.5.8')
+    s.add_dependency('httpclient', '>= 2.1.2')
 
-    s.has_rdoc = false
+    # RDoc information
+    s.has_rdoc = true
+    s.extra_rdoc_files = ['Readme.txt']
+    s.rdoc_options << '--main' << 'Readme.txt'
 
-    s.author =
-        "Sergio Gomes, Jeffrey Posnick, Patrick Chanezon, Ryan Leavengood"
-    s.email = "api.sgomes@gmail.com"
-    s.homepage = "http://code.google.com/p/google-api-adwords-ruby/"
+    # Metadata
+    s.authors = ['Sergio Gomes', 'Jeffrey Posnick', 'Patrick Chanezon',
+                 'Ryan Leavengood']
+    s.email = 'api.sgomes@gmail.com'
+    s.homepage = 'http://code.google.com/p/google-api-adwords-ruby/'
+    s.rubyforge_project = 'adwords4r'
     s.requirements << 'soap4r v1.5.8'
     s.requirements << 'httpclient v2.1.2 or greater'
-    s.add_dependency('soap4r', '= 1.5.8')
-    s.add_dependency('httpclient', '>= 2.1.2')
   end
 
   Rake::GemPackageTask.new(spec) do |t|