Feature 20251012

.github/workflows/feature-test.yml

@@ -48,11 +48,76 @@ jobs:
       env:
         PYTHONPATH: ${{ github.workspace }}/src
 
+  # 📦 Validate optional dependencies installation
+  validate-extras:
+    name: 📦 Validate Optional Dependencies
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        extra: ["cli", "async", "config", "dotenv", "dev"]
+
+    steps:
+    - name: 📥 Checkout code
+      uses: actions/checkout@v4
+
+    - name: 🐍 Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: 📦 Install base package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+
+    - name: 📦 Install optional extra [${{ matrix.extra }}]
+      run: |
+        pip install -e ".[${{ matrix.extra }}]"
+
+    - name: ✅ Verify installation
+      run: |
+        echo "=== Installed packages ==="
+        pip list | grep -E "(nocodb|click|rich|aiohttp|aiofiles|pyyaml|tomli|python-dotenv)" || true
+
+        echo "=== Testing imports ==="
+        python -c "from nocodb_simple_client import NocoDBClient; print('✓ Base client imports')"
+
+        # Test extra-specific imports
+        case "${{ matrix.extra }}" in
+          cli)
+            python -c "import click; import rich; print('✓ CLI dependencies available')"
+            python -c "from nocodb_simple_client.cli import main; print('✓ CLI module imports')"
+            ;;
+          async)
+            python -c "import aiohttp; import aiofiles; print('✓ Async dependencies available')"
+            python -c "from nocodb_simple_client.async_client import AsyncNocoDBClient; print('✓ Async client imports')"
+            ;;
+          config)
+            python -c "import yaml; print('✓ PyYAML available')"
+            if [ "${{ matrix.python-version }}" != "3.11" ] && [ "${{ matrix.python-version }}" != "3.12" ] && [ "${{ matrix.python-version }}" != "3.13" ]; then
+              python -c "import tomli; print('✓ tomli available')"
+            else
+              python -c "import tomllib; print('✓ tomllib available (stdlib)')"
+            fi
+            python -c "from nocodb_simple_client.config import NocoDBConfig; from pathlib import Path; print('✓ Config module imports')"
+            ;;
+          dotenv)
+            python -c "import dotenv; print('✓ python-dotenv available')"
+            ;;
+          dev)
+            python -c "import pytest; import ruff; import mypy; print('✓ Dev dependencies available')"
+            ;;
+        esac
+
+        echo "✅ Extra '${{ matrix.extra }}' validated successfully!"
+
   # 🔗 Integration tests with Python-managed NocoDB instance
   integration-test:
     name: 🔗 Integration Tests (Python-Managed)
     runs-on: ubuntu-latest
-    needs: unit-tests
+    needs: validate-extras
 
     steps:
     - name: 📥 Checkout code

docs/ADVANCED-USEAGE.MD

@@ -44,13 +44,23 @@ Optional environment variables:
 
 ### File-based Configuration
 
+**Required Dependencies:**
+
+```bash
+# Install with configuration file support (YAML/TOML)
+pip install "nocodb-simple-client[config]"
+
+# For .env file support
+pip install "nocodb-simple-client[dotenv]"
+```
+
 Load configuration from JSON, YAML, or TOML files:
 
 ```python
 from pathlib import Path
 from nocodb_simple_client.config import load_config
 
-# Load from file
+# Load from file (supports .json, .yaml, .yml, .toml)
 config = load_config(config_path=Path("config.yaml"))
 ```
 
@@ -93,6 +103,13 @@ config.setup_logging()
 
 ## Async Support
 
+**Required Dependencies:**
+
+```bash
+# Install with async dependencies
+pip install "nocodb-simple-client[async]"
+```
+
 For high-performance applications, use the async client:
 
 ```python

docs/README.template.MD

@@ -46,6 +46,8 @@ A simple and powerful Python client for interacting with [NocoDB](https://nocodb
 
 ### Installation
 
+#### Basic Installation
+
 Install from PyPI using pip:
 
 ```bash
@@ -65,6 +67,39 @@ pip install git+{{REPO_URL}}.git@v{{VERSION}}
 pip install git+{{REPO_URL}}.git@main
 ```
 
+#### Optional Features
+
+Install with optional features based on your needs:
+
+```bash
+# Command-line interface support
+pip install "nocodb-simple-client[cli]"
+
+# Async client support
+pip install "nocodb-simple-client[async]"
+
+# Configuration file support (YAML/TOML)
+pip install "nocodb-simple-client[config]"
+
+# .env file support
+pip install "nocodb-simple-client[dotenv]"
+
+# Multiple features
+pip install "nocodb-simple-client[cli,async,config]"
+
+# All features for development
+pip install "nocodb-simple-client[dev]"
+```
+
+**Available extras:**
+
+- `cli` - Command-line interface with rich output (requires `click`, `rich`)
+- `async` - Async client support (requires `aiohttp`, `aiofiles`)
+- `config` - YAML/TOML configuration file support (requires `PyYAML`, `tomli` for Python <3.11)
+- `dotenv` - .env file support for configuration (requires `python-dotenv`)
+- `dev` - All development dependencies (testing, linting, etc.)
+- `docs` - Documentation generation dependencies
+
 ### Basic Usage
 
 ```python
@@ -1003,7 +1038,9 @@ except Exception as e:
 
 ## 🧪 Examples
 
-Check out the [`examples/`](examples/) directory for comprehensive examples:
+Check out the [`examples/`](examples/) directory for comprehensive examples. See the [Examples README](examples/README.md) for detailed documentation.
+
+### Core Examples
 
 - **[Basic Usage](examples/basic_usage.py)**: CRUD operations and fundamentals
 - **[API Version Support](examples/api_version_example.py)**: Using v2 and v3 APIs with automatic conversion
@@ -1017,6 +1054,14 @@ Check out the [`examples/`](examples/) directory for comprehensive examples:
 - **[Link Management](examples/link_examples.py)**: Managing relationships between tables
 - **[Configuration](examples/config_examples.py)**: Different configuration methods
 
+### Optional Dependencies Examples
+
+These examples demonstrate the optional dependency groups:
+
+- **[Async Client](examples/async_example.py)**: High-performance concurrent operations (`[async]`)
+- **[Config Files](examples/config_file_example.py)**: YAML/TOML configuration loading (`[config]`)
+- **[Environment Files](examples/dotenv_example.py)**: Secure .env file management (`[dotenv]`)
+
 ## 📋 Requirements
 
 - Python 3.8 or higher

examples/README.md

@@ -61,6 +61,81 @@ This directory contains comprehensive examples demonstrating how to use the Noco
 
 **Best for**: Production applications requiring robust error handling
 
+---
+
+## Optional Dependencies Examples
+
+These examples demonstrate how to use the optional dependency groups. Each group provides additional functionality that can be installed separately based on your needs.
+
+### 5. Async Client (`async_example.py`)
+
+**Installation**: `pip install "nocodb-simple-client[async]"`
+
+**Purpose**: High-performance concurrent operations using async/await
+
+**What you'll learn**:
+
+- Setting up and using `AsyncNocoDBClient`
+- Basic async CRUD operations with context managers
+- Parallel bulk operations with automatic concurrency limiting
+- Custom semaphore-based concurrency control
+- Async error handling patterns
+- Running multiple queries in parallel with `asyncio.gather()`
+
+**Best for**: High-throughput applications, batch processing, real-time data pipelines
+
+**Dependencies installed**: `aiohttp`, `aiofiles`
+
+### 6. Configuration Files (`config_file_example.py`)
+
+**Installation**: `pip install "nocodb-simple-client[config]"`
+
+**Purpose**: Load configuration from YAML and TOML files
+
+**What you'll learn**:
+
+- Loading configuration from YAML files
+- Loading configuration from TOML files
+- JSON configuration (no extra dependencies required)
+- Managing environment-specific configurations (dev/staging/prod)
+- Graceful fallback patterns when dependencies are missing
+- Python 3.11+ `tomllib` vs `tomli` for older versions
+
+**Best for**: Applications with complex configuration needs, multi-environment deployments
+
+**Dependencies installed**: `PyYAML`, `tomli` (Python < 3.11 only)
+
+### 7. Environment Files (`dotenv_example.py`)
+
+**Installation**: `pip install "nocodb-simple-client[dotenv]"`
+
+**Purpose**: Secure secrets management with .env files
+
+**What you'll learn**:
+
+- Basic `.env` file loading with `load_dotenv()`
+- Managing multiple environment files (`.env.development`, `.env.production`)
+- Secrets management best practices and gitignore patterns
+- Reading `.env` without modifying `os.environ` using `dotenv_values()`
+- Combining `.env` files (secrets) with config files (settings)
+- Docker and cloud platform compatibility
+
+**Best for**: 12-factor apps, Docker deployments, secure credential management
+
+**Dependencies installed**: `python-dotenv`
+
+### Quick Reference: Optional Extras
+
+| Extra      | Command                                                     | Use Case                    |
+| ---------- | ----------------------------------------------------------- | --------------------------- |
+| `[async]`  | `pip install "nocodb-simple-client[async]"`                 | Async/concurrent operations |
+| `[config]` | `pip install "nocodb-simple-client[config]"`                | YAML/TOML config files      |
+| `[dotenv]` | `pip install "nocodb-simple-client[dotenv]"`                | .env file support           |
+| `[cli]`    | `pip install "nocodb-simple-client[cli]"`                   | Command-line interface      |
+| Combined   | `pip install "nocodb-simple-client[async,config,dotenv]"`   | Multiple features           |
+
+---
+
 ## Configuration
 
 Before running the examples, you'll need to configure: