Skip to content

Commit 999221b

Browse files
karlspacekarlspace
authored
Merge pull request #10 from bauer-group/feature-20251012
Feature 20251012
2 parents b142cbb + 43608fa commit 999221b

9 files changed

Lines changed: 1330 additions & 9 deletions

File tree

‎.github/workflows/feature-test.yml‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,76 @@ jobs:
4848
env:
4949
PYTHONPATH: ${{ github.workspace }}/src
5050

51+
# 📦 Validate optional dependencies installation
52+
validate-extras:
53+
name: 📦 Validate Optional Dependencies
54+
runs-on: ubuntu-latest
55+
needs: unit-tests
56+
strategy:
57+
matrix:
58+
python-version: ["3.11", "3.12", "3.13"]
59+
extra: ["cli", "async", "config", "dotenv", "dev"]
60+
61+
steps:
62+
- name: 📥 Checkout code
63+
uses: actions/checkout@v4
64+
65+
- name: 🐍 Set up Python ${{ matrix.python-version }}
66+
uses: actions/setup-python@v4
67+
with:
68+
python-version: ${{ matrix.python-version }}
69+
70+
- name: 📦 Install base package
71+
run: |
72+
python -m pip install --upgrade pip
73+
pip install -e .
74+
75+
- name: 📦 Install optional extra [${{ matrix.extra }}]
76+
run: |
77+
pip install -e ".[${{ matrix.extra }}]"
78+
79+
- name: ✅ Verify installation
80+
run: |
81+
echo "=== Installed packages ==="
82+
pip list | grep -E "(nocodb|click|rich|aiohttp|aiofiles|pyyaml|tomli|python-dotenv)" || true
83+
84+
echo "=== Testing imports ==="
85+
python -c "from nocodb_simple_client import NocoDBClient; print('✓ Base client imports')"
86+
87+
# Test extra-specific imports
88+
case "${{ matrix.extra }}" in
89+
cli)
90+
python -c "import click; import rich; print('✓ CLI dependencies available')"
91+
python -c "from nocodb_simple_client.cli import main; print('✓ CLI module imports')"
92+
;;
93+
async)
94+
python -c "import aiohttp; import aiofiles; print('✓ Async dependencies available')"
95+
python -c "from nocodb_simple_client.async_client import AsyncNocoDBClient; print('✓ Async client imports')"
96+
;;
97+
config)
98+
python -c "import yaml; print('✓ PyYAML available')"
99+
if [ "${{ matrix.python-version }}" != "3.11" ] && [ "${{ matrix.python-version }}" != "3.12" ] && [ "${{ matrix.python-version }}" != "3.13" ]; then
100+
python -c "import tomli; print('✓ tomli available')"
101+
else
102+
python -c "import tomllib; print('✓ tomllib available (stdlib)')"
103+
fi
104+
python -c "from nocodb_simple_client.config import NocoDBConfig; from pathlib import Path; print('✓ Config module imports')"
105+
;;
106+
dotenv)
107+
python -c "import dotenv; print('✓ python-dotenv available')"
108+
;;
109+
dev)
110+
python -c "import pytest; import ruff; import mypy; print('✓ Dev dependencies available')"
111+
;;
112+
esac
113+
114+
echo "✅ Extra '${{ matrix.extra }}' validated successfully!"
115+
51116
# 🔗 Integration tests with Python-managed NocoDB instance
52117
integration-test:
53118
name: 🔗 Integration Tests (Python-Managed)
54119
runs-on: ubuntu-latest
55-
needs: unit-tests
120+
needs: validate-extras
56121

57122
steps:
58123
- name: 📥 Checkout code

‎docs/ADVANCED-USEAGE.MD‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,13 +44,23 @@ Optional environment variables:
4444

4545
### File-based Configuration
4646

47+
**Required Dependencies:**
48+
49+
```bash
50+
# Install with configuration file support (YAML/TOML)
51+
pip install "nocodb-simple-client[config]"
52+
53+
# For .env file support
54+
pip install "nocodb-simple-client[dotenv]"
55+
```
56+
4757
Load configuration from JSON, YAML, or TOML files:
4858

4959
```python
5060
from pathlib import Path
5161
from nocodb_simple_client.config import load_config
5262

53-
# Load from file
63+
# Load from file (supports .json, .yaml, .yml, .toml)
5464
config = load_config(config_path=Path("config.yaml"))
5565
```
5666

@@ -93,6 +103,13 @@ config.setup_logging()
93103

94104
## Async Support
95105

106+
**Required Dependencies:**
107+
108+
```bash
109+
# Install with async dependencies
110+
pip install "nocodb-simple-client[async]"
111+
```
112+
96113
For high-performance applications, use the async client:
97114

98115
```python

‎docs/README.template.MD‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ A simple and powerful Python client for interacting with [NocoDB](https://nocodb
4646

4747
### Installation
4848

49+
#### Basic Installation
50+
4951
Install from PyPI using pip:
5052

5153
```bash
@@ -65,6 +67,39 @@ pip install git+{{REPO_URL}}.git@v{{VERSION}}
6567
pip install git+{{REPO_URL}}.git@main
6668
```
6769

70+
#### Optional Features
71+
72+
Install with optional features based on your needs:
73+
74+
```bash
75+
# Command-line interface support
76+
pip install "nocodb-simple-client[cli]"
77+
78+
# Async client support
79+
pip install "nocodb-simple-client[async]"
80+
81+
# Configuration file support (YAML/TOML)
82+
pip install "nocodb-simple-client[config]"
83+
84+
# .env file support
85+
pip install "nocodb-simple-client[dotenv]"
86+
87+
# Multiple features
88+
pip install "nocodb-simple-client[cli,async,config]"
89+
90+
# All features for development
91+
pip install "nocodb-simple-client[dev]"
92+
```
93+
94+
**Available extras:**
95+
96+
- `cli` - Command-line interface with rich output (requires `click`, `rich`)
97+
- `async` - Async client support (requires `aiohttp`, `aiofiles`)
98+
- `config` - YAML/TOML configuration file support (requires `PyYAML`, `tomli` for Python <3.11)
99+
- `dotenv` - .env file support for configuration (requires `python-dotenv`)
100+
- `dev` - All development dependencies (testing, linting, etc.)
101+
- `docs` - Documentation generation dependencies
102+
68103
### Basic Usage
69104

70105
```python
@@ -1003,7 +1038,9 @@ except Exception as e:
10031038

10041039
## 🧪 Examples
10051040

1006-
Check out the [`examples/`](examples/) directory for comprehensive examples:
1041+
Check out the [`examples/`](examples/) directory for comprehensive examples. See the [Examples README](examples/README.md) for detailed documentation.
1042+
1043+
### Core Examples
10071044

10081045
- **[Basic Usage](examples/basic_usage.py)**: CRUD operations and fundamentals
10091046
- **[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:
10171054
- **[Link Management](examples/link_examples.py)**: Managing relationships between tables
10181055
- **[Configuration](examples/config_examples.py)**: Different configuration methods
10191056

1057+
### Optional Dependencies Examples
1058+
1059+
These examples demonstrate the optional dependency groups:
1060+
1061+
- **[Async Client](examples/async_example.py)**: High-performance concurrent operations (`[async]`)
1062+
- **[Config Files](examples/config_file_example.py)**: YAML/TOML configuration loading (`[config]`)
1063+
- **[Environment Files](examples/dotenv_example.py)**: Secure .env file management (`[dotenv]`)
1064+
10201065
## 📋 Requirements
10211066

10221067
- Python 3.8 or higher

‎examples/README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,81 @@ This directory contains comprehensive examples demonstrating how to use the Noco
6161

6262
**Best for**: Production applications requiring robust error handling
6363

64+
---
65+
66+
## Optional Dependencies Examples
67+
68+
These examples demonstrate how to use the optional dependency groups. Each group provides additional functionality that can be installed separately based on your needs.
69+
70+
### 5. Async Client (`async_example.py`)
71+
72+
**Installation**: `pip install "nocodb-simple-client[async]"`
73+
74+
**Purpose**: High-performance concurrent operations using async/await
75+
76+
**What you'll learn**:
77+
78+
- Setting up and using `AsyncNocoDBClient`
79+
- Basic async CRUD operations with context managers
80+
- Parallel bulk operations with automatic concurrency limiting
81+
- Custom semaphore-based concurrency control
82+
- Async error handling patterns
83+
- Running multiple queries in parallel with `asyncio.gather()`
84+
85+
**Best for**: High-throughput applications, batch processing, real-time data pipelines
86+
87+
**Dependencies installed**: `aiohttp`, `aiofiles`
88+
89+
### 6. Configuration Files (`config_file_example.py`)
90+
91+
**Installation**: `pip install "nocodb-simple-client[config]"`
92+
93+
**Purpose**: Load configuration from YAML and TOML files
94+
95+
**What you'll learn**:
96+
97+
- Loading configuration from YAML files
98+
- Loading configuration from TOML files
99+
- JSON configuration (no extra dependencies required)
100+
- Managing environment-specific configurations (dev/staging/prod)
101+
- Graceful fallback patterns when dependencies are missing
102+
- Python 3.11+ `tomllib` vs `tomli` for older versions
103+
104+
**Best for**: Applications with complex configuration needs, multi-environment deployments
105+
106+
**Dependencies installed**: `PyYAML`, `tomli` (Python < 3.11 only)
107+
108+
### 7. Environment Files (`dotenv_example.py`)
109+
110+
**Installation**: `pip install "nocodb-simple-client[dotenv]"`
111+
112+
**Purpose**: Secure secrets management with .env files
113+
114+
**What you'll learn**:
115+
116+
- Basic `.env` file loading with `load_dotenv()`
117+
- Managing multiple environment files (`.env.development`, `.env.production`)
118+
- Secrets management best practices and gitignore patterns
119+
- Reading `.env` without modifying `os.environ` using `dotenv_values()`
120+
- Combining `.env` files (secrets) with config files (settings)
121+
- Docker and cloud platform compatibility
122+
123+
**Best for**: 12-factor apps, Docker deployments, secure credential management
124+
125+
**Dependencies installed**: `python-dotenv`
126+
127+
### Quick Reference: Optional Extras
128+
129+
| Extra | Command | Use Case |
130+
| ---------- | ----------------------------------------------------------- | --------------------------- |
131+
| `[async]` | `pip install "nocodb-simple-client[async]"` | Async/concurrent operations |
132+
| `[config]` | `pip install "nocodb-simple-client[config]"` | YAML/TOML config files |
133+
| `[dotenv]` | `pip install "nocodb-simple-client[dotenv]"` | .env file support |
134+
| `[cli]` | `pip install "nocodb-simple-client[cli]"` | Command-line interface |
135+
| Combined | `pip install "nocodb-simple-client[async,config,dotenv]"` | Multiple features |
136+
137+
---
138+
64139
## Configuration
65140

66141
Before running the examples, you'll need to configure:

0 commit comments

Comments
 (0)