sheets_v4 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ed35f7562643f623e68d6ad41c497f1d92ea7b2d77f4b6f0d5e02586109897
-  data.tar.gz: 6687dfc41d70870694a2085e749d803f7062de8d2486866e4e44ea54b1eec95f
+  metadata.gz: aaee6f486ac124cdefd974acfe3f18357ade8e9f90655a46e746ebfad53a391b
+  data.tar.gz: 0f3c1e513b45a841052be82817e5bcf157aba492282999f401bb069e048e2263
 SHA512:
-  metadata.gz: 00334f58b9080916f1239671e106292742a00bbd931582577ae8a0664c25ea83f1ecaf5154996a0f28deffe9e8aaf58e4963dd94160095853d7d3454ef9e1b82
-  data.tar.gz: a89714057c1aa145ce2b5eaa5a05776b8593c76d6e944b1b2b868b1ddd16a4247bf05ac13b218b74addb0204a3644cb6657e30e2331e725ca68467359cfd66a9
+  metadata.gz: c3762e42b88065e6bc76e5e749d629dc02073c2584053a9c979fd8b46196e70e155c2f06d87a768b511a93b30d38d09c5da6592ef875a9fb70cb7bd97b67ed7a
+  data.tar.gz: 64bed7345bcc3ee05d204b47770b297e8a53d05cc1deb6611bd114197cb46690df2683549e772b7b9453fbf158eba492efc05faf93e966047f57055e9d203d87

data/CHANGELOG.md

@@ -4,6 +4,16 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## v0.8.0 (2023-10-15)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.7.0..v0.8.0)
+
+Changes since v0.7.0:
+
+* d8f695c Add extensions to Google::Apis::SheetsV4 classes (#26)
+* ed2dc0e Show the cop names on Rubocop offenses when Rubocop is run from Rake (#25)
+* c5bfcc1 Group the SheetsV4 methods in the Yard Docs to make them easier to find (#24)
+
 ## v0.7.0 (2023-10-08)
 
 [Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.6.0..v0.7.0)

data/README.md

@@ -25,6 +25,10 @@ Unofficial helpers for the Google Sheets V4 API
     * [Method 2: constructing requests using hashes](#method-2-constructing-requests-using-hashes)
     * [Which method should be used?](#which-method-should-be-used)
   * [Validating requests](#validating-requests)
+  * [Google Extensions](#google-extensions)
+    * [SheetsService Extensions](#sheetsservice-extensions)
+    * [Spreadsheet Extensions](#spreadsheet-extensions)
+    * [Sheet Extensions](#sheet-extensions)
   * [Working with dates and times](#working-with-dates-and-times)
   * [Colors](#colors)
 * [Development](#development)
@@ -274,6 +278,36 @@ request:
 SheetsV4.validate_api_object(schema: 'batch_update_spreadsheet_request', object: requests)
 ```
 
+### Google Extensions
+
+The `SheetsV4::GoogleExtensions` module provides extensions to the `Google::Apis::SheetsV4`
+classes to simplify use of the SheetsV4 API.
+
+These extensions are not loaded by default and are not required to use other parts
+of this Gem. To enable these extension, you must:
+
+```Ruby
+require 'sheets_v4/google_extensions'
+```
+
+#### SheetsService Extensions
+
+Functionality is added to `get_spreadsheet` to set the `sheets_service` attribute on
+the returned spreadsheet and set the `sheets_service` and `spreadsheet` attributes
+on the sheets contained in the spreadsheet.
+
+This can simplify complex spreadsheet updates because you won't have to pass a
+sheets_service, spreadsheet, and sheet objects separately.
+
+#### Spreadsheet Extensions
+
+The `sheets_service` attribute is added and is set by `SheetsService#get_spreadsheet`.
+
+#### Sheet Extensions
+
+The `sheets_service` and `spreadsheet` attributes are added. Both are set when the
+sheet's spreadsheet is loaded by `SheetsService#get_spreadsheet`.
+
 ### Working with dates and times
 
 Google Sheets, similar to other spreadsheet programs, stores dates and date-time

data/Rakefile

@@ -50,6 +50,9 @@ require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new do |t|
   t.options = %w[
+    --display-cop-names
+    --display-style-guide
+    --extra-details
     --format progress
     --format json --out rubocop-report.json
   ]

data/lib/sheets_v4/google_extensions/sheet.rb

@@ -0,0 +1,32 @@
+# Copyright (c) 2022 Yahoo
+# frozen_string_literal: true
+
+require 'google/apis/sheets_v4'
+require 'googleauth'
+
+module SheetsV4
+  module GoogleExtensions
+    # The SheetsService class implements handling credentials on top of the
+    # Google::Apis::SheetsV4::SheetsService class.
+    #
+    # @api public
+    #
+    module Sheet
+      # The sheets_service object used to create this sheet
+      #
+      # @example
+      #   sheets_service = sheet.sheets_service
+      #
+      # @return [Google::Apis::SheetsV4::SheetsService]
+      attr_reader :sheets_service
+
+      # The spreadsheet object that contains this sheet
+      #
+      # @example
+      #   spreadsheet = sheet.spreadsheet
+      #
+      # @return [Google::Apis::SheetsV4::Spreadsheet]
+      attr_reader :spreadsheet
+    end
+  end
+end

data/lib/sheets_v4/google_extensions/sheets_service.rb

@@ -0,0 +1,99 @@
+# Copyright (c) 2022 Yahoo
+# frozen_string_literal: true
+
+module SheetsV4
+  module GoogleExtensions
+    # This module extends the `Google::Apis::SheetsV4::SheetsService` class to add
+    # attributes to the `Google::Apis::SheetsV4::Spreadsheet` and `Google::Apis::SheetsV4::Sheet`
+    # classes that reference the `SheetsService` instance used to retrieve them.
+    #
+    # Similarly, an attribute is added to the `Google::Apis::SheetsV4::Sheet` class
+    # that references the `Google::Apis::SheetsV4::Spreadsheet` instance that contains it.
+    #
+    # This allows getting the `SheetsService` object from a spreadsheet or sheet object,
+    # making it unnecessary to pass the `SheetsService` object around with the spreadsheet
+    # and its sheets.
+    #
+    # @example
+    #   require 'sheets_v4/google_extensions'
+    #   sheets_service = SheetsV4::SheetsService.new
+    #   spreadsheet = sheets_service.get_spreadsheet('1nT_q0TrQzC3dLZXuI3K9V5P3mArBVZpVd_vRsOpvcyk')
+    #
+    #   spreadsheet.sheets_service == sheets_service # => true
+    #   spreadsheet.sheets.each do |sheet|
+    #     sheet.sheets_service == sheets_service # => true
+    #     sheet.spreadsheet == spreadsheet # => true
+    #   end
+    #
+    # @api public
+    #
+    module SheetsService
+      # Replace the prepending class's `get_spreadsheet` implementation
+      #
+      # When this module is prepended to a class, class's `get_spreadsheet` method
+      # is replaced wity `new_get_spreadsheet` method from this module.  The class's
+      # original `get_spreadsheet` method is renamed to `original_get_spreadsheet`.
+      #
+      # @example
+      #   Google::Apis::SheetsV4::SheetsService.prepend(
+      #     SheetsV4::GoogleExtensions::SheetsService
+      #   )
+      #
+      # @return [void]
+      #
+      # @private
+      #
+      def self.prepended(prepended_to_class)
+        prepended_to_class.send(:alias_method, :original_get_spreadsheet, :get_spreadsheet)
+        prepended_to_class.send(:remove_method, :get_spreadsheet)
+        prepended_to_class.send(:alias_method, :get_spreadsheet, :new_get_spreadsheet)
+      end
+
+      # @!method get_spreadsheet(spreadsheet_id, include_grid_data, ranges, fields, quota_user, options, &block)
+      #
+      #   @api public
+      #
+      #   Gets an existing spreadsheet
+      #
+      #   Creates a spreadsheet object by calling the original
+      #   Google::Apis::SheetsV4::SheetsService#get_spreadsheet method and then does
+      #   the following:
+      #
+      #   * Sets the `sheets_service` attribute for the returned spreadsheet.
+      #   * Sets the `sheets_service` and `spreadsheet` attributes all the sheets contained in the spreadsheet.
+      #
+      #   See the documentation for Google::Apis::SheetsV4::SheetsService#get_spreadsheet for
+      #   details on the parameters and return value.
+      #
+      #   @example Get a spreadsheet object and output new attributes:
+      #     require 'sheets_v4'
+      #     require 'sheets_v4/google_extensions'
+      #
+      #     sheets_service = SheetsV4::SheetsService.new
+      #     spreadsheet_id = '1nT_q0TrQzC3dLZXuI3K9V5P3mArBVZpVd_vRsOpvcyk'
+      #
+      #     spreadsheet = sheets_service.get_spreadsheet(spreadsheet_id)
+      #
+      #   @return [Google::Apis::SheetsV4::Spreadsheet] the spreadsheet whose ID is `spreadsheet_id`
+
+      # Replaces the `get_spreadsheet` method implementation in the prepended class
+      #
+      # @example
+      #   spreadsheet = sheets_service.new_get_spreadsheet(spreadsheet_id)
+      #
+      # @private
+      #
+      # @return [Google::Apis::SheetsV4::Spreadsheet]
+      #
+      def new_get_spreadsheet(...)
+        original_get_spreadsheet(...)&.tap do |spreadsheet|
+          spreadsheet.instance_variable_set(:@sheets_service, self)
+          spreadsheet.sheets.each do |sheet|
+            sheet.instance_variable_set(:@sheets_service, self)
+            sheet.instance_variable_set(:@spreadsheet, spreadsheet)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sheets_v4/google_extensions/spreadsheet.rb

@@ -0,0 +1,24 @@
+# Copyright (c) 2022 Yahoo
+# frozen_string_literal: true
+
+require 'google/apis/sheets_v4'
+require 'googleauth'
+
+module SheetsV4
+  module GoogleExtensions
+    # The SheetsService class implements handling credentials on top of the
+    # Google::Apis::SheetsV4::SheetsService class.
+    #
+    # @api public
+    #
+    module Spreadsheet
+      # The sheets_service object used to create this spreadsheet
+      #
+      # @example
+      #   sheets_service = spreadsheet.sheets_service
+      #
+      # @return [Google::Apis::SheetsV4::SheetsService]
+      attr_reader :sheets_service
+    end
+  end
+end

data/lib/sheets_v4/google_extensions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  # The Google extensions are additions directly to Google::Apis::SheetsV4 classes
+  #
+  # These additions are optional and provide convenience methods and attributes
+  # that simplify use of the Google Sheets API.
+  #
+  # To use these extensions, require the `sheets_v4/google_extensions` file.
+  #
+  # @example
+  #   require 'sheets_v4/google_extensions'
+  #
+  module GoogleExtensions; end
+end
+
+require_relative 'google_extensions/sheets_service'
+require_relative 'google_extensions/spreadsheet'
+require_relative 'google_extensions/sheet'
+
+# @private
+module Google
+  module Apis
+    # Add SheetsV4 extensions to Google::Apis::SheetsV4 classes
+    module SheetsV4
+      # Add SheetsV4 extensions to Google::Apis::SheetsV4::SheetsService
+      class SheetsService
+        prepend ::SheetsV4::GoogleExtensions::SheetsService
+      end
+
+      # Add SheetsV4 extensions to Google::Apis::SheetsV4::Spreadsheet
+      class Spreadsheet
+        prepend ::SheetsV4::GoogleExtensions::Spreadsheet
+      end
+
+      # Add SheetsV4 extensions to Google::Apis::SheetsV4::Sheet
+      class Sheet
+        prepend ::SheetsV4::GoogleExtensions::Sheet
+      end
+    end
+  end
+end

data/lib/sheets_v4/version.rb

@@ -2,5 +2,5 @@
 
 module SheetsV4
   # The version of this gem
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

data/lib/sheets_v4.rb

@@ -57,6 +57,8 @@ module SheetsV4
       end
     end
 
+    # @!group Validation
+
     # Validate the object using the named JSON schema
     #
     # The JSON schemas are loaded from the Google Disocvery API. The schemas names are
@@ -90,6 +92,8 @@ module SheetsV4
       SheetsV4::ApiObjectValidation::LoadSchemas.new(logger:).call.keys.sort
     end
 
+    # @!group Colors
+
     # Given the name of the color, return a Google Sheets API color object
     #
     # Available color names are listed using `SheetsV4.color_names`.
@@ -117,6 +121,8 @@ module SheetsV4
     #
     def color_names = SheetsV4::Color::COLORS.keys
 
+    # @!group Date and DateTime Conversions
+
     # @!attribute [rw] default_spreadsheet_tz
     #
     # Set the default time zone for date and time conversions

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sheets_v4
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - James Couball
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 2023-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -268,6 +268,10 @@ files:
 - lib/sheets_v4/color.rb
 - lib/sheets_v4/convert_dates_and_times.rb
 - lib/sheets_v4/create_credential.rb
+- lib/sheets_v4/google_extensions.rb
+- lib/sheets_v4/google_extensions/sheet.rb
+- lib/sheets_v4/google_extensions/sheets_service.rb
+- lib/sheets_v4/google_extensions/spreadsheet.rb
 - lib/sheets_v4/validate_api_objects.rb
 - lib/sheets_v4/validate_api_objects/validate_api_object.rb
 - lib/sheets_v4/version.rb