google_sheets 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0513b5f7ab0fcb68e08c1d80130fc6462c2905553ade3289c77c326c2f5fcc1
-  data.tar.gz: e50f4db63195185d320d6106d5a82fcaf77585f161284099d8d93b8ac2ab53c2
+  metadata.gz: 4272935e8e6148c9003b8b9cce980c17b4fad1f618a8783d414e74599c3a9a81
+  data.tar.gz: c9bb34301243f5e883226002395ab0b827d3b8ea0cdf3a37ad7a70afde78c263
 SHA512:
-  metadata.gz: 160336d9e34ebe9e3c4c00c5425cf7a170305d451d3d942d0593f984a481449354542aba2d4243f2e9fd6d0f499f60f1a27fc4858d27c4390923302981b28d90
-  data.tar.gz: 60eb1a779b362f57ab79d2424485118e502d39331339e90d1ed222a4edd34c45a6f9a3f38d3cbc6f54749b3bcd12423b008cfc76b075efdbd307af8045fd5370
+  metadata.gz: c268f6821bfa7a75059853b691b89ca3103720f1dfb8bbb23c3dc7c90fcff9f8f598a356ad0099d5a642194a848c7e8306a1069b28991def6efc2f4e9934e937
+  data.tar.gz: 7efda40322d3a6af693862c97959363b994d0ddf066fb610c18ae7638f644d261815f0d9bfe90ec3b98d177b915efebef1a5571bb75f7bd0afa27a47a8f27f9c

data/README.md

@@ -2,11 +2,11 @@
 
 Since I only ever used that gem for creating/reading spreadsheets, I created this simple gem for just that, but using the v4 API.
 
-* [Installing](#installing)
+* [Installing](#Installing)
 * [Getting started](#getting-started)
 * [GitHub](http://github.com/shmay/google_sheets)
 
-## <a name="installing">Installing</a>
+<h3 id='installing'>Installing</h3>
 
 Add this line to your application's Gemfile & `bundle install`:
 
@@ -17,12 +17,12 @@ gem 'google_sheets'
 Or install it yourself:
 
 ```
-$ gem install google_drive
+$ gem install google_sheets
 ```
 
-### Authorization
+<h3 id='authorization'>Authorization</h3>
 
-The authorization process is taken from Google's [own tutorial](https://developers.google.com/sheets/api/quickstart/ruby#step_3_set_up_the_sample).
+The authorization process is taken from Google's [own tutorial](https://developers.google.com/sheets/api/quickstart/ruby#step_3_set_up_the_sample).  Take a look at [session.rb](lib/google_sheets/session.rb) - it closely resembles the authorization code in that tutorial.
 
 You'll need to create a project and enable the GSheets API, as detailed [in step 1 of that tutorial](https://developers.google.com/sheets/api/quickstart/ruby#step_1_turn_on_the_api_name).
 
@@ -52,7 +52,7 @@ session = GoogleSheets::Session.start_session(
 )
 ```
 
-### Getting Started
+<h3 id='getting-started'>Getting Started</h3>
 
 Once you're authorized, you can read, create, and delete sheets within a spreadsheet.
 
@@ -72,9 +72,7 @@ sheet1 = spreadsheet.sheets[0]
 sheet1.values
 # => [['first, 'last', 'age'], ['bob', 'jones', '92'], ['steve', 'johnson', '22']]
 
-values = [[1,2],[3,4]]
-
-sheet2 = spreadsheet.add_sheet('what', values: values)
+sheet2 = spreadsheet.add_sheet('what', values: [[1,2],[3,4]])
 
 spreadsheet.sheets.map &:title
 # => ['Sheet1', 'yoyo1', 'what']
@@ -89,6 +87,7 @@ spreadsheet.sheets.map &:title
 # it uses the top row as the keys
 # fyi, this will also convert the values to UTF-8
 # sometimes gsheets values come in as ASCII
+
 sheet1.to_json
 # =>
 #  [
@@ -103,6 +102,7 @@ sheet1.to_json
 #       age: '22'
 #     }
 #  ]
+
 ```
 
 Or just look at [the spec](spec/test_all_the_things_spec.rb) to see it in action.

data/lib/google_sheets/session.rb

@@ -10,28 +10,30 @@ require 'google_sheets/spreadsheet'
 
 module GoogleSheets
   class Session
-    OOB_URI = 'urn:ietf:wg:oauth:2.0:oob'.freeze
-    # APPLICATION_NAME = 'Google Sheets API Ruby Quickstart'.freeze
-    # CLIENT_SECRETS_FILENAME = 'client_secret.json'.freeze
-    CREDENTIALS_FILENAME = 'token.yaml'.freeze
+    OOB_URI = 'urn:ietf:wg:oauth:2.0:oob'
+    CREDENTIALS_FILENAME = 'token.yaml'
     SCOPE = Google::Apis::SheetsV4::AUTH_SPREADSHEETS
 
+    # Accepts a [Google::Apis::SheetsV4::SheetsService](https://www.rubydoc.info/github/google/google-api-ruby-client/Google/Apis/SheetsV4/SheetsService)
+    # through which we can read/write gsheets
     def initialize service
       @service = service
     end
 
+    # instantiates and returns a Spreadsheet object from a key
+    # @return [GoogleSheets::Spreadsheet]
     def spreadsheet_from_key key
       Spreadsheet.new @service, key
     end
 
-    ### AUTH CODE TAKEN FROM: https://developers.google.com/sheets/api/quickstart/ruby#step_3_set_up_the_sample
+    # This code is heavily borrowed from https://developers.google.com/sheets/api/quickstart/ruby#step_3_set_up_the_sample
     #
     ##
     # Ensure valid credentials, either by restoring from the saved credentials
     # files or intitiating an OAuth2 authorization. If authorization is required,
     # the user's default browser will be launched to approve the request.
     #
-    # @return [Google::Auth::UserRefreshCredentials] OAuth2 credentials
+    # @return [Google::Auth::UserRefreshCredentials](https://www.rubydoc.info/gems/googleauth/0.5.0/Google/Auth/UserRefreshCredentials) OAuth2 credentials
     def self.authorize client_id, client_secret, token_path
       credentials_hash = {
         "installed" =>
@@ -63,6 +65,12 @@ module GoogleSheets
       credentials
     end
 
+    private_class_method :authorize
+
+    ##
+    # Everything starts from this method - authorizes the user and creates a Session object, through which we can read spreadsheets.
+    #
+    # @return [GoogleSheets::Session]
     def self.start_session client_id:, client_secret:, token_path: '.'
       # Initialize the API
       service = Google::Apis::SheetsV4::SheetsService.new

data/lib/google_sheets/sheet.rb

@@ -1,6 +1,13 @@
+# frozen_string_literal
+
 module GoogleSheets
   class Sheet
-    attr_reader :properties, :title
+    # [Google::Apis::SheetsV4::SheetProperties](https://www.rubydoc.info/github/google/google-api-ruby-client/Google/Apis/SheetsV4/SheetProperties) in hash form
+    # @return [Hash]
+    attr_reader :properties
+    # title of the sheet
+    # @return [String]
+    attr_reader :title
     attr_writer :values
 
     def initialize service, sheet, spreadsheet
@@ -11,14 +18,20 @@ module GoogleSheets
       @title = @properties[:title]
     end
 
+    # The internal ID of the sheet. From Google.
+    # @return [Integer]
     def id
       @properties[:sheet_id]
     end
 
+    # Returns an Array of string values, EG: [['one', 'two'], ['three', 'four']]
+    # @return [Array(String)]
     def values
       @values ||= @service.get_spreadsheet_values(@spreadsheet.key, @title).values
     end
 
+    # Deletes a sheet from a spreadsheet
+    # @return [Sheet]
     def delete!
       delete_sheet_request = Google::Apis::SheetsV4::DeleteSheetRequest.new
       delete_sheet_request.sheet_id = self.id
@@ -36,6 +49,10 @@ module GoogleSheets
       self
     end
 
+    # Converts the spreadsheet to an array of hashes, using the top row as the keys
+    #
+    # EG `[['name', 'age'], ['john', '20']] => [{name: 'john', age: '20'}]`
+    # @return [Array(Hash)]
     def to_json
       top_row = values[0].map &:to_sym
       hashify_data(values[1..-1], top_row)

data/lib/google_sheets/spreadsheet.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal
+
 module GoogleSheets
   class Spreadsheet
+    # the spreadsheet key
+    # @return [String]
     attr_reader :key
 
     def initialize service, key
@@ -8,13 +12,16 @@ module GoogleSheets
       load_spreadsheet
     end
 
+    # loads the spreadsheet from google sheets
     def load_spreadsheet
       @spreadsheet = @service.get_spreadsheet(@key)
       @properties = @spreadsheet.properties.to_h
     end
 
+    # reloads the spreadsheet, effectively uncaching everything
     alias refresh! load_spreadsheet
 
+    # @return [Array(Sheet)]
     def sheets
       @sheets ||= @spreadsheet.sheets.map do |sheet|
         Sheet.new(@service, sheet, self)
@@ -22,6 +29,7 @@ module GoogleSheets
     end
 
     # HT this SO answer: https://stackoverflow.com/a/49886382/548170
+    # @return [Sheet]
     def add_sheet title, values: []
       add_sheet_request = Google::Apis::SheetsV4::AddSheetRequest.new
       add_sheet_request.properties = Google::Apis::SheetsV4::SheetProperties.new
@@ -48,6 +56,8 @@ module GoogleSheets
       sheet
     end
 
+    private
+
     def append_to_sheet title, values
       # The A1 notation of a range to search for a logical table of data.
       # Values will be appended after the last row of the table.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google_sheets
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Kyle Murphy