kaggle 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56c5fd9c27bd8cdc20423167b912f171ee07d37e0413cfbbbcba2ea38140b7c6
-  data.tar.gz: 3f37e295dc32362f7606803790225af6a707021ba78b239d4f2a29567102fee6
+  metadata.gz: '009830e3354d63a31d7f75ca303651389d53d99eb190d89dbd6f3a81765842ed'
+  data.tar.gz: 4de17ec0780676292396440832dbfd6c474ba2687b52d36e6c4e150fd9a6c989
 SHA512:
-  metadata.gz: 41b60fa4d87d5a78778247acdbf620bbbcb2a23add74b07c76ff25fa2a02ed5675e8fd3aa27dce6352c2c49c0dfcfb90f54d55cbd1219cb81b04c6a2b371d086
-  data.tar.gz: c3b887147a1e0aeb38fdf1440b63f3c722e8375feaab45bbc0a5e4e434b0a8f7cb06ea71437fe08d888704c732d60629c7e3f18443c40e339abb72c88a56e667
+  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/version.rb

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

metadata

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