numerousapp 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3a77c2d75609a18065360ad1de49b131a8ce75e
-  data.tar.gz: 476884887a6b37b9cf3c4f9bafc37124e62d996a
+  metadata.gz: 5bc753ba4ac5af22bec9d355a0450327a4c0415c
+  data.tar.gz: e5e47a6f1f2a339338bdb5fe60a66366f33fa610
 SHA512:
-  metadata.gz: 83f23c276bbe85ae08b7f39a0b7654c3f3d27b113297e697fc59b0a060b818f1ba5f21f5bd912073bcd78649499db51124bc5944d177657c84b1072e0f34148c
-  data.tar.gz: c7f931711ca03bbc166010e95073b95984c211f5d5e25a3ea511dab521ed03d3641a8eb92a6f0eed394d6b1d356ec52a6ddc108a247cc514ed385477d9a93fb2
+  metadata.gz: aba6414701c7c0ddf0e33379f3dc35a3b48070587e535be8e57ceea8247f564cc2a8a9429ac67c32dd0a028faf2ee313d548c41f18a1dbb3943ff17e9df775d1
+  data.tar.gz: bfbae46781b680556c3cec93a0f380d7a765443c54b9d672a6d0ca54bf4c71b4ca6bce24241a431e0b626a1f2522a31f49f0ef8f9aaf0136f853d65df149cdf1

data/lib/numerousapp.rb

@@ -9,10 +9,10 @@
 # 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
@@ -26,7 +26,7 @@
 #   Numerous
 #     -- server-level operations: get user parameters,  create metric, etc
 #
-#   NumerousMetric 
+#   NumerousMetric
 #     -- individual metrics: read/write/like/comment, etc
 #
 #   NumerousClientInternals
@@ -72,31 +72,29 @@ end
 
 #
 # A NumerousMetricConflictError occurs when you write to a metric
-# and specified "only if changed" and your value 
+# and specified "only if changed" and your value
 # was (already) the current value
-# 
+#
 class NumerousMetricConflictError < NumerousError
 end
 
 #
-# == NumerousClientInternals 
+# == NumerousClientInternals
 #
 # Handles details of talking to the numerousapp.com server, including
 # the (basic) authentication, handling chunked APIs, json vs multipart APIs,
-# fixing up a few server response quirks, and so forth. It is not meant 
+# fixing up a few server response quirks, and so forth. It is not meant
 # for use outside of Numerous and NumerousMetric.
 #
 class NumerousClientInternals
 
-
-
     #
     # @param apiKey [String] API authentication key
     # @param server [String] Optional (keyword arg). Server name.
     # @param throttle [Proc] Optional throttle policy
     # @param throttleData [Any] Optional data for throttle
     #
-    # @!attribute agentString 
+    # @!attribute agentString
     #    @return [String] User agent string sent to the server.
     #
     # @!attribute [r] serverName
@@ -114,7 +112,7 @@ class NumerousClientInternals
 
         @serverName = server
         @auth = { user: apiKey, password: "" }
-        u = URI.parse("https://"+server) 
+        u = URI.parse("https://"+server)
         @http = Net::HTTP.new(server, u.port)
         @http.use_ssl = true    # always required by NumerousApp
 
@@ -135,7 +133,12 @@ class NumerousClientInternals
         # and the default policy uses the "data" (40) as the voluntary backoff point
         #
         @arbitraryMaximumTries = 10
-        @throttlePolicy = [ThrottleDefault, 40, nil]
+        voluntary = { voluntary: 40}
+        # you can keep the dflt throttle but just alter the voluntary param, this way:
+        if throttleData and not throttle
+            voluntary = throttleData
+        end
+        @throttlePolicy = [ThrottleDefault, voluntary, nil]
         if throttle
             @throttlePolicy = [throttle, throttleData, @throttlePolicy]
         end
@@ -148,9 +151,14 @@ class NumerousClientInternals
     attr_reader :serverName, :debugLevel
     attr_reader :statistics
 
+    def to_s()
+        oid = (2 * self.object_id).to_s(16)
+        return "<Numerous {#{@serverName}} @ 0x#{oid}>"
+    end
+
     # Set the debug level
     #
-    # @param [Fixnum] lvl 
+    # @param [Fixnum] lvl
     #   The desired debugging level. Greater than zero turns on debugging.
     # @return [Fixnum] the previous debugging level.
     def debug(lvl=1)
@@ -174,7 +182,7 @@ class NumerousClientInternals
 
     protected
 
-    VersionString = '20150125-1.0.1'
+    VersionString = '20150215-1.0.2'
 
     MethMap = {
         GET: Net::HTTP::Get,
@@ -251,7 +259,7 @@ class NumerousClientInternals
 
 
     # ALL api exchanges with the Numerous server go through here except
-    # for getRedirect() which is a special case (hack) for photo URLs 
+    # for getRedirect() which is a special case (hack) for photo URLs
     #
     # Any single request/response uses this; chunked APIs use
     # the iterator classes (which in turn come back and use this repeatedly)
@@ -270,7 +278,7 @@ class NumerousClientInternals
     # in a url and it will take precedence over the basePath if any is present
     #
     # You can pass in a dictionary jdict which will be json-ified
-    # and sent as Content-Type: application/json. Or you can pass in 
+    # and sent as Content-Type: application/json. Or you can pass in
     # a multipart dictionary ... this is used for posting photos
     # You should not specify both jdict and multipart
     #
@@ -289,7 +297,7 @@ class NumerousClientInternals
             # need to add logic. XXX TODO XXX
             path = URI.parse(url).request_uri
         end
-                
+
         rq = MethMap[api[:httpMethod]].new(path)
         rq.basic_auth(@auth[:user], @auth[:password])
         rq['user-agent'] = @agentString
@@ -333,7 +341,19 @@ class NumerousClientInternals
         @arbitraryMaximumTries.times do |attempt|
 
             @statistics[:serverRequests] += 1
+            t0 = Time.now
             resp = @http.request(rq)
+            et = Time.now - t0
+            # We report the elapsed round-trip time, either as a scalar (default)
+            # OR if you preset the :serverResponseTimes to be an array of length N
+            # then we keep the last N response times, thusly:
+            begin
+                times = @statistics[:serverResponseTimes]
+                times.insert(0, et)
+                times.pop()
+            rescue NoMethodError         # just a scalar
+                @statistics[:serverResponseTimes] = et
+            end
 
             if @debugLevel > 0
                 puts "Response headers:\n"
@@ -377,7 +397,7 @@ class NumerousClientInternals
                 # On some requests that return "nothing" the server
                 # returns {} ... on others it literally returns nothing.
                 if (not resp.body) or resp.body.length == 0
-                    rj = {} 
+                    rj = {}
                 else
                     # this isn't supposed to happen... server bug?
                     raise e
@@ -460,13 +480,13 @@ class NumerousClientInternals
                 filterInfo[:prev] = filterInfo[:current]
                 filterInfo[:current] = {}
             end
-            
+
             list = v[api[:list]]
             nextURL = v[api[:next]]
 
             # hand them out
             if list             # can be nil for a variety of reasons
-                list.each do |i| 
+                list.each do |i|
 
                     # A note about duplicate filtering
                     #
@@ -563,6 +583,9 @@ class NumerousClientInternals
 
         if attempt > 0
             stats[:throttleMultipleAttempts] += 1
+            if attempt > stats[:throttleMaxAttempt]
+                stats[:throttleMaxAttempt] = attempt
+            end
         end
 
         backarray = [ 2, 5, 15, 30, 60 ]
@@ -586,12 +609,12 @@ class NumerousClientInternals
             # note that some errors don't communicate rateleft so we have to
             # check for that as well (will be -1 here if wasn't sent to us)
             #
-            # at constructor time our "throttle data" (td) was set up as the
+            # at constructor time our "throttle data" (td) was set up with the
             # voluntary arbitrary limit
-            if rateleft >= 0 and rateleft < td
+            if rateleft >= 0 and rateleft < td[:voluntary]
                 stats[:throttleVoluntaryBackoff] += 1
                 # arbitrary .. 1 second if more than half left, 3 seconds if less
-                if (rateleft*2) > td
+                if (rateleft*2) > td[:voluntary]
                     sleep(1)
                 else
                     sleep(3)
@@ -631,18 +654,18 @@ end
 # Hash of <string-key, value> pairs and returned from the appropriate methods.
 #
 # For some operations the server returns only a success/failure code.
-# In those cases there is no useful return value from the method; the 
+# In those cases there is no useful return value from the method; the
 # method succeeds or else raises an exception (containing the failure code).
 #
 # For the collection operations the server returns a JSON array of dictionary
 # representations, possibly "chunked" into multiple request/response operations.
-# The enumerator methods (e.g., "metrics") implement lazy-fetch and hide 
+# The enumerator methods (e.g., "metrics") implement lazy-fetch and hide
 # the details of the chunking from you. They simply yield each individual
 # item (string-key Hash) to your block.
 #
 # === Exception handling
 #
-# Almost every API that interacts with the server will potentially 
+# Almost every API that interacts with the server will potentially
 # raise a {NumerousError} (or subclass thereof). This is not noted specifically
 # in the doc for each method unless it might be considered a "surprise"
 # (e.g., ping always returns true else raises an exception). Rescue as needed.
@@ -651,15 +674,15 @@ end
 class Numerous  < NumerousClientInternals
 
     # path info for the server-level APIs: create a metric, get user info, etc
-    APIInfo = {        
+    APIInfo = {
       # POST to this to create a metric
-      create: { 
+      create: {
           path: '/v1/metrics',
           POST: { successCodes: [ 201 ] }
       },
 
       # GET a users metric collection
-      metricsCollection: { 
+      metricsCollection: {
           path: '/v2/users/%{userId}/metrics',
           defaults: { userId: 'me' },
           GET: { next: 'nextURL', list: 'metrics' }
@@ -721,7 +744,7 @@ class Numerous  < NumerousClientInternals
     #
     # All metrics for the given user (default is your own)
     #
-    # @param [String] userId 
+    # @param [String] userId
     #    optional - numeric id (represented as a string) of user
     # @yield [m] metrics
     # @yieldparam m [Hash] String-key representation of one metric
@@ -735,7 +758,7 @@ class Numerous  < NumerousClientInternals
     #
     # All subscriptions for the given user (default is your own)
     #
-    # @param [String] userId 
+    # @param [String] userId
     #    optional - numeric id (represented as a string) of user
     # @yield [s] subscriptions
     # @yieldparam s [Hash] String-key representation of one subscription
@@ -744,7 +767,7 @@ class Numerous  < NumerousClientInternals
     def subscriptions(userId:nil, &block)
         chunkedIterator(APIInfo[:subscriptions], { userId: userId }, block)
         return self
-    end    
+    end
 
 
     #
@@ -754,7 +777,7 @@ class Numerous  < NumerousClientInternals
     #
     # @param [Fixnum] count
     #    optional - number of metrics to return
-    # @return [Array] Array of hashes (metric string dicts). Each element 
+    # @return [Array] Array of hashes (metric string dicts). Each element
     #    represents a particular popular metric.
     #
     def mostPopular(count:nil)
@@ -765,7 +788,7 @@ class Numerous  < NumerousClientInternals
     #
     # Verify connectivity to the server
     #
-    # @return [true] Always returns true connectivity if ok. 
+    # @return [true] Always returns true connectivity if ok.
     #     Raises an exception otherwise.
     # @raise [NumerousAuthError] Your credentials are no good.
     # @raise [NumerousError] Other server (or network) errors.
@@ -781,10 +804,10 @@ class Numerous  < NumerousClientInternals
     # @param label [String] Required. Label for the metric.
     # @param value [Fixnum,Float] Optional (keyword arg). Initial value.
     # @param attrs [Hash] Optional (keyword arg). Initial attributes.
-    # @return [NumerousMetric] 
+    # @return [NumerousMetric]
     #
     # @example Create a metric with label 'bozo' and set value to 17
-    #  nr = Numerous.new('nmrs_3vblahblah') 
+    #  nr = Numerous.new('nmrs_3vblahblah')
     #  m = nr.createMetric('bozo')
     #  m.write(17)
     #
@@ -810,7 +833,7 @@ class Numerous  < NumerousClientInternals
     #
     # Instantiate a metric object to access a metric from the server.
     # @return [NumerousMetric] metric object
-    # @param id [String] 
+    # @param id [String]
     #     Required. Metric ID (something like '2319923751024'). NOTE: If id
     #     is bogus this will still "work" but (of course) errors will be
     #     raised when you do something with the metric.
@@ -827,9 +850,8 @@ class Numerous  < NumerousClientInternals
     # instead of an ID, and can even process it as a regexp.
     #
     # @param [String] labelspec The name (label) or regexp
-    # @param [String] matchType 'FIRST' or 'BEST' or 'ONE' or 'STRING' (not regexp)
-    # @param [Numerous] nr 
-    #    The {Numerous} object that will be used to access this metric.
+    # @param [String] matchType 'FIRST','BEST','ONE','STRING' or 'ID'
+    #
     def metricByLabel(labelspec, matchType:'FIRST')
         def raiseConflict(s1,s2)
             raise NumerousMetricConflictError.new("Multiple matches", 409, [s1, s2])
@@ -840,10 +862,22 @@ class Numerous  < NumerousClientInternals
         if not matchType
             matchType = 'FIRST'
         end
-        if not ['FIRST', 'BEST', 'ONE', 'STRING'].include?(matchType)
+        if not ['FIRST', 'BEST', 'ONE', 'STRING', 'ID'].include?(matchType)
             raise ArgumentError
         end
 
+        # Having 'ID' as an option simplifies some automated use cases
+        # (e.g., test vectors) because you can just pair ids and matchTypes
+        # and simply always call ByLabel even for native (nonlabel) IDs
+        # We add the semantics that the result is validated as an actual ID
+        if matchType == 'ID'
+            rv = metric(labelspec)
+            if not rv.validate()
+                rv = nil
+            end
+            return rv
+        end
+
         # if you specified STRING and sent a regexp... or vice versa
         if matchType == 'STRING' and labelspec.instance_of?(Regexp)
             labelspec = labelspec.source
@@ -962,7 +996,7 @@ class Numerous  < NumerousClientInternals
     	    # replace() bcs there might be a trailing newline on naked creds
     	    # (usually happens with a file or stdin)
     	    j[credsAPIKey] = s.sub("\n",'')
-        end 
+        end
 
     	return j[credsAPIKey]
     end
@@ -985,12 +1019,12 @@ end
 # will return just the naked number unless you ask it for the entire dictionary)
 #
 # For some operations the server returns only a success/failure code.
-# In those cases there is no useful return value from the method; the 
+# In those cases there is no useful return value from the method; the
 # method succeeds or else raises an exception (containing the failure code).
 #
 # For the collection operations the server returns a JSON array of dictionary
 # representations, possibly "chunked" into multiple request/response operations.
-# The enumerator methods (e.g., "events") implement lazy-fetch and hide 
+# The enumerator methods (e.g., "events") implement lazy-fetch and hide
 # the details of the chunking from you. They simply yield each individual
 # item (string-key Hash) to your block.
 #
@@ -1004,7 +1038,7 @@ class NumerousMetric < NumerousClientInternals
     # Constructor for a NumerousMetric
     #
     # @param [String] id The metric ID string.
-    # @param [Numerous] nr 
+    # @param [Numerous] nr
     #    The {Numerous} object that will be used to access this metric.
     #
     # "id" should normally be the naked metric id (as a string).
@@ -1027,29 +1061,54 @@ class NumerousMetric < NumerousClientInternals
     # the presence of a '/' indicates a non-naked metric ID. This
     # seems a reasonable assumption given that IDs have to go into URLs
     #
+    # "id" can be a hash representing a metric or a subscription.
+    # We will take (in order) key 'metricId' or key 'id' as the id.
+    # This is convenient when using the metrics() or subscriptions() iterators.
+    #
+    # "id" can be an integer representing a metric ID. Not recommended
+    # though it's handy sometimes in cut/paste interactive testing/use.
+    #
 
     def initialize(id, nr)
+        actualId = nil
         begin
-            if id.include? '/'
-                fields = id.split('/')
-                if fields[-2] == "m"
-                    id = fields[-1].to_i(36)
-                else
-                    id = fields[-1]
-                end
+            fields = id.split('/')
+            if fields.length() == 1
+                actualId = fields[0]
+            elsif fields[-2] == "m"
+                actualId = fields[-1].to_i(36)
+            else
+                actualId = fields[-1]
             end
         rescue NoMethodError
-            id = id.to_s
         end
 
-        @id = id
-        @nr = nr
+        if not actualId
+            # it's not a string, see if it's a hash
+             actualId = id['metricId'] || id['id']
+        end
+
+        if not actualId
+            # well, see if it looks like an int
+            i = id.to_i     # allow this to raise exception if id bogus type here
+            if i == id
+                actualId = i.to_s
+            end
+        end
+
+        if not actualId
+            raise ArgumentError("invalid id")
+        else
+            @id = actualId.to_s    # defensive in case bad fmt in hash
+            @nr = nr
+            @cachedHash = nil
+        end
     end
     attr_reader :id
     attr_reader :nr
 
 
-    APIInfo = {                             
+    APIInfo = {
       # read/update/delete a metric
       metric: {
         path: '/v1/metrics/%{metricId}' ,
@@ -1151,6 +1210,67 @@ class NumerousMetric < NumerousClientInternals
     end
     private :getAPI
 
+    # for things, such as [ ], that need a cached copy of the metric's values
+    def ensureCache()
+        begin
+            if not @cachedHash
+                ignored = read()    # just reading brings cache into being
+            end
+        rescue NumerousError => x
+            raise x             # definitely pass these along
+        rescue => x             # anything else turn into a NumerousError
+            # this is usually going to be all sorts of random low-level
+            # network problems (if the network fails at the exact wrong time)
+            details = { exception: x }
+            raise NumerousError.new("Could not obtain metric state", 0, details)
+        end
+    end
+    private :ensureCache
+
+    # access cached copy of metric via [ ]
+    def [](idx)
+        ensureCache()
+        return @cachedHash[idx]
+    end
+
+    # enumerator metric.each { |k, v| ... }
+    def each()
+        ensureCache()
+        @cachedHash.each { |k, v| yield(k, v) }
+    end
+
+    # produce the keys of a metric as an array
+    def keys()
+        ensureCache()
+        return @cachedHash.keys
+    end
+
+    # string representation of a metric
+    def to_s()
+       # there's nothing important/magic about the object id displayed; however
+       # to make it match the native to_s we (believe it or not) need to multiply
+       # the object_id return value by 2. This is obviously implementation specific
+       # (and makes no difference to anyone; but this way it "looks right" to humans)
+       objid = (2*self.object_id).to_s(16)   # XXX wow lol
+       rslt = "<NumerousMetric @ 0x#{objid}: "
+       begin
+           ensureCache()
+           lbl = self['label']
+           val = self['value']
+           rslt += "'#{self['label']}' [#@id] = #{val}>"
+       rescue NumerousError => x
+           puts(x.code)
+           if x.code == 400
+               rslt += "**INVALID-ID** '#@id'>"
+           elsif x.code == 404
+               rslt += "**ID NOT FOUND** '#@id'>"
+           else
+               rslt += "**SERVER-ERROR** '#{x.message}'>"
+           end
+       end
+       return rslt
+    end
+
     #
     # Read the current value of a metric
     # @param [Boolean] dictionary
@@ -1162,13 +1282,14 @@ class NumerousMetric < NumerousClientInternals
     def read(dictionary: false)
         api = getAPI(:metric, :GET)
         v = @nr.simpleAPI(api)
+        @cachedHash = v.clone
         return (if dictionary then v else v['value'] end)
     end
 
     # "Validate" a metric object.
     # There really is no way to do this in any way that carries much weight.
     # However, if a user gives you a metricId and you'd like to know if
-    # that actually IS a metricId, this might be useful. 
+    # that actually IS a metricId, this might be useful.
     #
     # @example
     #    someId = ... get a metric ID from someone ...
@@ -1180,7 +1301,7 @@ class NumerousMetric < NumerousClientInternals
     # Realize that even a valid metric can be deleted asynchronously
     # and thus become invalid after being validated by this method.
     #
-    # Reads the metric, catches the specific exceptions that occur for 
+    # Reads the metric, catches the specific exceptions that occur for
     # invalid metric IDs, and returns True/False. Other exceptions mean
     # something else went awry (server down, bad authentication, etc).
     # @return [Boolean] validity of the metric
@@ -1189,7 +1310,7 @@ class NumerousMetric < NumerousClientInternals
             ignored = read()
             return true
         rescue NumerousError => e
-            # bad request (400) is a completely bogus metric ID whereas 
+            # bad request (400) is a completely bogus metric ID whereas
             # not found (404) is a well-formed ID that simply does not exist
             if e.code == 400 or e.code == 404
                 return false
@@ -1230,7 +1351,7 @@ class NumerousMetric < NumerousClientInternals
         return self
     end
 
-    # Enumerate the interactions (like/comment/error) of a metric. 
+    # Enumerate the interactions (like/comment/error) of a metric.
     #
     # @yield [i] interactions
     # @yieldparam i [Hash] String-key representation of one interaction.
@@ -1276,7 +1397,7 @@ class NumerousMetric < NumerousClientInternals
     # Obtain your subscription parameters on a given metric
     #
     # Note that normal users cannot see other user's subscriptions.
-    # Thus the "userId" parameter is somewhat pointless; you can only 
+    # Thus the "userId" parameter is somewhat pointless; you can only
     # ever see your own.
     # @param [String] userId
     # @return [Hash] your subscription attributes
@@ -1285,7 +1406,7 @@ class NumerousMetric < NumerousClientInternals
         return @nr.simpleAPI(api)
     end
 
-    # Subscribe to a metric. 
+    # Subscribe to a metric.
     #
     # See the NumerousApp API docs for what should be
     # in the dict. This function will fetch the current parameters
@@ -1309,7 +1430,7 @@ class NumerousMetric < NumerousClientInternals
         end
 
         dict.each { |k, v| params[k] = v }
-
+        @cachedHash = nil     # bcs the subscriptions count changes
         api = getAPI(:subscription, :PUT, { userId: userId })
         return @nr.simpleAPI(api, jdict:params)
     end
@@ -1318,7 +1439,7 @@ class NumerousMetric < NumerousClientInternals
     #
     # @param [Fixnum|Float] newval Required. Value to be written.
     #
-    # @param [Boolean] onlyIf 
+    # @param [Boolean] onlyIf
     #   Optional (keyword arg). Only creates an event at the server
     #   if the newval is different from the current value. Raises
     #   NumerousMetricConflictError if there is no change in value.
@@ -1345,6 +1466,7 @@ class NumerousMetric < NumerousClientInternals
             j['action'] = 'ADD'
         end
 
+        @cachedHash = nil  # will need to refresh cache on next access
         api = getAPI(:events, :POST)
         begin
             v = @nr.simpleAPI(api, jdict:j)
@@ -1373,7 +1495,7 @@ class NumerousMetric < NumerousClientInternals
     #   with your updates before writing them back. If true your supplied
     #   dictionary will become the entirety of the metric's parameters, and
     #   any parameters you did not include in your dictionary will revert to
-    #   their default values. 
+    #   their default values.
     # @return [Hash] string-key Hash of the new metric parameters.
     #
     def update(dict, overwriteAll:false)
@@ -1381,7 +1503,8 @@ class NumerousMetric < NumerousClientInternals
         dict.each { |k, v| newParams[k] = v }
 
         api = getAPI(:metric, :PUT)
-        return @nr.simpleAPI(api, jdict:newParams)
+        @cachedHash = @nr.simpleAPI(api, jdict:newParams)
+        return @cachedHash.clone
     end
 
     # common code for writing interactions
@@ -1439,7 +1562,8 @@ class NumerousMetric < NumerousClientInternals
     def photo(imageDataOrReadable, mimeType:'image/jpeg')
         api = getAPI(:photo, :POST)
         mpart = { :f => imageDataOrReadable, :mimeType => mimeType }
-        return @nr.simpleAPI(api, multipart: mpart)
+        @cachedHash = @nr.simpleAPI(api, multipart: mpart)
+        return @cachedHash.clone()
     end
 
     # Delete the metric's photo
@@ -1447,6 +1571,7 @@ class NumerousMetric < NumerousClientInternals
     #   but the error code will be 200/OK.
     # @return [nil]
     def photoDelete
+        @cachedHash = nil   # I suppose we could have just deleted the photoURL
         api = getAPI(:photo, :DELETE)
         v = @nr.simpleAPI(api)
         return nil
@@ -1476,9 +1601,9 @@ class NumerousMetric < NumerousClientInternals
 
     # Obtain the underlying photoURL for a metric.
     #
-    # The photoURL is available in the metrics parameters so you could 
+    # The photoURL is available in the metrics parameters so you could
     # just read(dictionary:true) and obtain it that way. However this goes
-    # one step further ... the URL in the metric itself still requires 
+    # one step further ... the URL in the metric itself still requires
     # authentication to fetch (it then redirects to the "real" underlying
     # static photo URL). This function goes one level deeper and
     # returns you an actual, publicly-fetchable, photo URL.
@@ -1525,6 +1650,7 @@ class NumerousMetric < NumerousClientInternals
     #
     # @return [nil]
     def crushKillDestroy
+        @cachedHash = nil
         api = getAPI(:metric, :DELETE)
         v = @nr.simpleAPI(api)
         return nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: numerousapp
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Neil Webber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-25 00:00:00.000000000 Z
+date: 2015-02-15 00:00:00.000000000 Z
 dependencies: []
 description: Classes implementing the NumerousApp REST APIs for metrics. Requires
   Ruby 2.x