kaggle 0.0.2 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dd4c5fcd2e2e0f7841b00ba3b27d9dc75e898dc77bbc25b9ddbf10aad9f7561
-  data.tar.gz: e44814e2269cf74aafc044e60653c36523fa0868b4c1548da1083ece0866bf90
+  metadata.gz: '009830e3354d63a31d7f75ca303651389d53d99eb190d89dbd6f3a81765842ed'
+  data.tar.gz: 4de17ec0780676292396440832dbfd6c474ba2687b52d36e6c4e150fd9a6c989
 SHA512:
-  metadata.gz: 9f81008f7591da868c6eea42414b36159aa6d6c4e3be1ffd18f89f85a0e6e2c120310e4c56f71d32bd406d2eaced158d96972ccd653c3da215f6cfb256eac7d2
-  data.tar.gz: f3215a4798e90fa5e3496f2364f5da4e5bad5adf982e470c54118c8a5afea3c9ebdca99251e3ba4bf76a9c8f64dbe90664f91d7bff1d6ecec600708cf12c34ec
+  metadata.gz: 85b83dd390d80fe152b1214b729b757c6a118d06c89016f259927e998b65d7e9cd31bf8464fc986729c3fc48b2a5f90469e8c78324ded6e753222892f781a7d1
+  data.tar.gz: 7cdf4a9655d9b98d93a7081ddaad14ff19979646101e4f9bb45af4aa34bd955f2ea6dafe5fb4cc5b1d68e622c5e0e41851eac33b87a18560a296b2d53ff9e521

data/CLAUDE.md

@@ -6,6 +6,15 @@ This file documents how Claude helped develop this Ruby gem and provides guidanc
 
 This Kaggle Ruby gem was created with assistance from Claude (Sonnet 4) on 2025-08-23. The development process followed established Ruby gem conventions and best practices.
 
+### Version 0.0.3 Updates (2025-08-26)
+- **Added cache-only mode**: New `cache_only: true` initialization option
+- **Enhanced error handling**: Added `CacheNotFoundError` for cache-only scenarios
+- **Flexible cache behavior**: Support for graceful degradation vs strict cache requirements
+- **Comprehensive testing**: Added 6 new test cases for cache-only functionality
+- **Updated documentation**: README and CLAUDE.md updated with new features
+
+This update enables offline usage and integration with systems where credentials aren't available but cached data exists.
+
 ## Architecture Decisions
 
 ### 1. Gem Structure
@@ -31,14 +40,18 @@ This Kaggle Ruby gem was created with assistance from Claude (Sonnet 4) on 2025-
 ## Key Implementation Notes
 
 ### Authentication
-The gem supports two authentication methods:
-1. Environment variables (`KAGGLE_USERNAME`, `KAGGLE_KEY`)
-2. Explicit parameters during client initialization
+The gem supports multiple authentication methods:
+1. JSON credentials file (`kaggle.json`) - automatic detection or custom path
+2. Environment variables (`KAGGLE_USERNAME`, `KAGGLE_KEY`)
+3. Explicit parameters during client initialization
+4. **Cache-only mode** - no credentials required, access cached data only
 
 ### Caching Strategy
 - Simple file-based caching for parsed CSV data
 - Cache keys generated from dataset paths
 - Optional cache usage controlled by method parameters
+- **Cache-only mode** allows accessing datasets without valid credentials
+- Support for both graceful degradation (return nil) and strict mode (raise error)
 
 ### CSV Parsing
 - Uses Ruby's built-in CSV library for reliability

data/README.md

@@ -8,6 +8,7 @@ This is an unofficial project and still a work in progress (WIP) ... more to com
 - 📊 Download Kaggle datasets programmatically
 - 📄 Parse CSV datasets to JSON format
 - 💾 Configurable caching to avoid re-downloading
+- 🔐 Cache-only mode for accessing datasets without credentials
 - 🔧 Flexible download and cache paths
 - ⚡ Built-in error handling and validation
 - 🛠️ Command-line interface for quick operations
@@ -46,6 +47,9 @@ export KAGGLE_KEY="your_api_key"
 ### Option 3: Direct Credentials
 Pass credentials directly when initializing the client.
 
+### Option 4: Cache-Only Mode
+Access only cached datasets without providing credentials (useful for offline access or when credentials are unavailable).
+
 ### Kaggle JSON File Format
 The `kaggle.json` file downloaded from Kaggle should have this format:
 ```json
@@ -76,6 +80,40 @@ client = Kaggle::Client.new(
   username: 'your_username',
   api_key: 'your_api_key'
 )
+
+# Option 4: Cache-only mode (no credentials needed)
+client = Kaggle::Client.new(cache_only: true)
+```
+
+### Cache-Only Mode
+
+Cache-only mode allows you to access previously downloaded and cached datasets without requiring valid Kaggle credentials. This is useful for:
+
+- Offline development environments
+- CI/CD pipelines where credentials aren't available
+- Production systems that should only use pre-cached data
+
+```ruby
+# Initialize in cache-only mode
+client = Kaggle::Client.new(
+  cache_only: true,
+  cache_path: '/path/to/cache'
+)
+
+# This will return cached data if available, nil if not cached
+data = client.download_dataset('zillow', 'zecon', 
+                              parse_csv: true, 
+                              use_cache: true)
+
+# Force cache mode - raises CacheNotFoundError if not cached
+begin
+  data = client.download_dataset('zillow', 'zecon', 
+                                parse_csv: true, 
+                                use_cache: true,
+                                force_cache: true)
+rescue Kaggle::CacheNotFoundError
+  puts "Dataset not found in cache"
+end
 ```
 
 ### Download Datasets
@@ -145,8 +183,10 @@ kaggle --version
 | `download_path` | `./downloads` | Where to save downloaded files |
 | `cache_path` | `./cache` | Where to cache parsed data |
 | `timeout` | `30` | HTTP request timeout in seconds |
+| `cache_only` | `false` | Enable cache-only mode (no credentials required) |
 | `use_cache` | `false` | Use cached parsed data when available |
 | `parse_csv` | `false` | Automatically parse CSV files to JSON |
+| `force_cache` | `false` | Raise error if cached data not found (cache-only mode) |
 
 ## Error Handling
 
@@ -163,6 +203,8 @@ rescue Kaggle::DownloadError
   puts "Download failed"
 rescue Kaggle::ParseError
   puts "Failed to parse data"
+rescue Kaggle::CacheNotFoundError
+  puts "Dataset not found in cache (cache-only mode)"
 end
 ```
 

data/lib/kaggle/client.rb

@@ -4,22 +4,23 @@ module Kaggle
 
     base_uri Constants::BASE_URL
 
-    attr_reader :username, :api_key, :download_path, :cache_path, :timeout
+    attr_reader :username, :api_key, :download_path, :cache_path, :timeout, :cache_only
 
     def initialize(username: nil, api_key: nil, credentials_file: nil, download_path: nil, cache_path: nil,
-                   timeout: nil)
+                   timeout: nil, cache_only: false)
       load_credentials(username, api_key, credentials_file)
       @download_path = download_path || Constants::DEFAULT_DOWNLOAD_PATH
       @cache_path = cache_path || Constants::DEFAULT_CACHE_PATH
       @timeout = timeout || Constants::DEFAULT_TIMEOUT
+      @cache_only = cache_only
 
-      unless valid_credential?(@username) && valid_credential?(@api_key)
+      unless cache_only || (valid_credential?(@username) && valid_credential?(@api_key))
         raise AuthenticationError,
-              'Username and API key are required'
+              'Username and API key are required (or set cache_only: true for cache-only access)'
       end
 
       ensure_directories_exist
-      setup_httparty_options
+      setup_httparty_options unless cache_only
     end
 
     def download_dataset(dataset_owner, dataset_name, options = {})
@@ -37,6 +38,15 @@ module Kaggle
         return handle_existing_dataset(extracted_dir, options)
       end
 
+      # If cache_only mode and no cached data found, return nil or raise based on force_cache option
+      if @cache_only
+        if options[:force_cache]
+          raise CacheNotFoundError, "Dataset '#{dataset_path}' not found in cache and force_cache is enabled"
+        else
+          return nil # Gracefully return nil when cache_only but not forced
+        end
+      end
+
       # Download the zip file
       response = authenticated_request(:get, "#{Constants::DATASET_ENDPOINTS[:download]}/#{dataset_path}")
 

data/lib/kaggle/version.rb

@@ -1,3 +1,3 @@
 module Kaggle
-  VERSION = '0.0.2'
+  VERSION = '0.0.5'
 end

data/lib/kaggle.rb

@@ -16,4 +16,5 @@ module Kaggle
   class DatasetNotFoundError < Error; end
   class DownloadError < Error; end
   class ParseError < Error; end
+  class CacheNotFoundError < Error; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kaggle
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.5
 platform: ruby
 authors:
 - Your Name