rackfish 1.0.1__tar.gz → 1.0.3__tar.gz

{rackfish-1.0.1 → rackfish-1.0.3}/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.0.3] - 2025-10-15
+
+### Added
+
+- Singular collection access: Access single-member collections directly (e.g., `client.System` instead of `next(iter(client.Systems))`)
+- Works at all resource hierarchy levels (client and nested resources)
+- Automatic fallback to traditional methods when collection doesn't have exactly one member
+- Comprehensive test suite for singular access (`test_singular_collection_access.py`)
+- Documentation for singular collection access feature
+- New test suite for ETag functionality (`test_etag_support.py`)
+
+### Fixed
+
+- Added ETag support for PATCH requests via If-Match header to prevent HTTP 412 errors
+- PATCH operations now automatically include ETags when available in resource metadata
+- Resources without ETags continue to work normally (backward compatible)
+- Suppressed urllib3 InsecureRequestWarning when `verify_ssl=False` is used
+
 ## [1.0.1] - 2025-10-15
 
 ### Fixed

{rackfish-1.0.1 → rackfish-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rackfish
-Version: 1.0.1
+Version: 1.0.3
 Summary: A lightweight, dynamic Python client for Redfish BMC APIs
 Author-email: Dmitrii Frolov <thefrolov@mts.ru>
 License: MIT
@@ -58,17 +58,6 @@ A lightweight, dynamic Python client for interacting with Redfish BMC (Baseboard
 - 📚 **Collection Support** - Iterate Redfish collections naturally
 - 🔐 **Flexible Auth** - Session tokens or Basic authentication
 
-## Features
-
-- **Zero Dependencies** (except `requests`) - Minimal footprint
-- **Lazy Loading** - Resources fetched on-demand for performance
-- **Dynamic Attributes** - JSON properties become Python attributes
-- **OEM Surfacing** - Vendor extensions automatically accessible
-- **Links Surfacing** - Related resources directly navigable
-- **Action Validation** - Parameter validation using ActionInfo schemas
-- **Collection Support** - Iterate Redfish collections naturally
-- **Session & Basic Auth** - Flexible authentication options
-
 ## Installation
 
 ### From PyPI (recommended)
@@ -101,8 +90,11 @@ client = RedfishClient("https://bmc.example.com", "admin", "password",
                        use_session=True, verify_ssl=False)
 root = client.connect()
 
-# Power control
-system = next(iter(client.Systems))
+# Power control - multiple ways to access systems
+system = next(iter(client.Systems))  # Traditional iteration
+system = client.Systems.Members[0]    # Direct member access
+system = client.System                # Singular form (if only one member!)
+
 system.Reset(ResetType="GracefulRestart")
 
 # Access OEM properties (auto-surfaced)
@@ -166,7 +158,8 @@ for temp in chassis.Thermal.Temperatures:
     print(f"{temp.Name}: {temp.ReadingCelsius}°C")
 ```
 
-See [EXAMPLES.md](EXAMPLES.md) for 100+ more examples covering:
+See [docs/EXAMPLES.md](docs/EXAMPLES.md) for 100+ more examples covering:
+
 - BIOS configuration
 - Certificate management
 - Virtual media (KVM)
@@ -175,24 +168,6 @@ See [EXAMPLES.md](EXAMPLES.md) for 100+ more examples covering:
 - SEL/log collection
 - And much more...
 
-## Testing
-
-Run the test suite:
-
-```bash
-# Install with dev dependencies
-pip install -e ".[dev]"
-
-# Run all tests
-pytest tests/
-
-# Run with coverage
-pytest --cov=rackfish tests/
-
-# Run specific test file
-pytest tests/test_common_usage.py
-```
-
 ## Project Structure
 
 ```
@@ -356,7 +331,7 @@ See LICENSE file.
 
 ## Version
 
-Current version: 1.0.0
+Current version: 1.0.3
 
 ## Requirements
 

{rackfish-1.0.1 → rackfish-1.0.3}/README.md

@@ -20,17 +20,6 @@ A lightweight, dynamic Python client for interacting with Redfish BMC (Baseboard
 - 📚 **Collection Support** - Iterate Redfish collections naturally
 - 🔐 **Flexible Auth** - Session tokens or Basic authentication
 
-## Features
-
-- **Zero Dependencies** (except `requests`) - Minimal footprint
-- **Lazy Loading** - Resources fetched on-demand for performance
-- **Dynamic Attributes** - JSON properties become Python attributes
-- **OEM Surfacing** - Vendor extensions automatically accessible
-- **Links Surfacing** - Related resources directly navigable
-- **Action Validation** - Parameter validation using ActionInfo schemas
-- **Collection Support** - Iterate Redfish collections naturally
-- **Session & Basic Auth** - Flexible authentication options
-
 ## Installation
 
 ### From PyPI (recommended)
@@ -63,8 +52,11 @@ client = RedfishClient("https://bmc.example.com", "admin", "password",
                        use_session=True, verify_ssl=False)
 root = client.connect()
 
-# Power control
-system = next(iter(client.Systems))
+# Power control - multiple ways to access systems
+system = next(iter(client.Systems))  # Traditional iteration
+system = client.Systems.Members[0]    # Direct member access
+system = client.System                # Singular form (if only one member!)
+
 system.Reset(ResetType="GracefulRestart")
 
 # Access OEM properties (auto-surfaced)
@@ -128,7 +120,8 @@ for temp in chassis.Thermal.Temperatures:
     print(f"{temp.Name}: {temp.ReadingCelsius}°C")
 ```
 
-See [EXAMPLES.md](EXAMPLES.md) for 100+ more examples covering:
+See [docs/EXAMPLES.md](docs/EXAMPLES.md) for 100+ more examples covering:
+
 - BIOS configuration
 - Certificate management
 - Virtual media (KVM)
@@ -137,24 +130,6 @@ See [EXAMPLES.md](EXAMPLES.md) for 100+ more examples covering:
 - SEL/log collection
 - And much more...
 
-## Testing
-
-Run the test suite:
-
-```bash
-# Install with dev dependencies
-pip install -e ".[dev]"
-
-# Run all tests
-pytest tests/
-
-# Run with coverage
-pytest --cov=rackfish tests/
-
-# Run specific test file
-pytest tests/test_common_usage.py
-```
-
 ## Project Structure
 
 ```
@@ -318,7 +293,7 @@ See LICENSE file.
 
 ## Version
 
-Current version: 1.0.0
+Current version: 1.0.3
 
 ## Requirements
 

rackfish-1.0.3/docs/ETAG_SUPPORT.md

@@ -0,0 +1,241 @@
+# ETag Support in rackfish
+
+## Overview
+
+As of version 1.0.2 (unreleased), rackfish automatically includes ETag support for PATCH requests to prevent HTTP 412 (Precondition Failed) errors from Redfish BMCs that require concurrency control.
+
+## Background
+
+Many Redfish BMC implementations require the `If-Match` header with an ETag value when performing PATCH operations. This is a standard HTTP precondition mechanism to prevent lost updates in concurrent environments.
+
+### The Problem
+
+When a PATCH request is sent without the `If-Match` header:
+- BMCs may respond with **HTTP 428 Precondition Required**
+- BMCs may respond with **HTTP 412 Precondition Failed**
+- The update operation fails even though the data is valid
+
+### The Solution
+
+rackfish now automatically:
+1. Extracts the `@odata.etag` value from resources when they are fetched
+2. Includes the ETag in the `If-Match` header for all PATCH requests
+3. Falls back gracefully when no ETag is present (backward compatible)
+
+## Usage
+
+No changes are needed to your existing code! ETag support works automatically.
+
+### Example: Attribute Assignment
+
+```python
+from rackfish import RedfishClient
+
+client = RedfishClient("https://bmc.example.com", "admin", "password")
+client.connect()
+
+# Get a system resource (ETag is automatically extracted if present)
+system = client.Systems[0]
+
+# Modify an attribute - ETag is automatically included in PATCH
+system.AssetTag = "MyNewServer"
+# Behind the scenes: PATCH with If-Match header containing the ETag
+```
+
+### Example: Using .patch() Method
+
+```python
+# Complex updates using .patch()
+system.patch({
+    "AssetTag": "UpdatedTag",
+    "IndicatorLED": "Lit"
+})
+# ETag is automatically included in the PATCH request
+```
+
+### Example: Resources Without ETags
+
+```python
+# Works seamlessly with BMCs that don't provide ETags
+system.PowerState = "On"
+# PATCH is sent without If-Match header (no error)
+```
+
+## How It Works
+
+### 1. ETag Extraction
+
+When a resource is fetched, rackfish looks for the `@odata.etag` field in the JSON response:
+
+```json
+{
+  "@odata.id": "/redfish/v1/Systems/1",
+  "@odata.type": "#ComputerSystem.v1_0_0.ComputerSystem",
+  "@odata.etag": "W/\"12345678\"",
+  "Id": "1",
+  "AssetTag": "MyServer"
+}
+```
+
+The ETag value `W/"12345678"` is stored internally in the resource object.
+
+### 2. ETag Inclusion in PATCH
+
+When a PATCH operation is triggered (via attribute assignment or `.patch()` method), rackfish:
+
+1. Checks if the resource has an `@odata.etag` value
+2. If present, includes it in the `If-Match` header
+3. If absent, sends the PATCH without the header
+
+HTTP request example with ETag:
+```http
+PATCH /redfish/v1/Systems/1 HTTP/1.1
+Host: bmc.example.com
+Content-Type: application/json
+If-Match: W/"12345678"
+
+{"AssetTag": "NewValue"}
+```
+
+### 3. Backward Compatibility
+
+Resources without ETags continue to work normally:
+- Old BMCs that don't provide ETags work as before
+- No breaking changes to existing code
+- Optional feature that activates only when ETags are present
+
+## Implementation Details
+
+### Modified Methods
+
+#### `RedfishClient.patch(path, data, etag=None)`
+
+The `patch` method now accepts an optional `etag` parameter:
+
+```python
+def patch(self, path: str, data: dict[str, Any], etag: str | None = None) -> None:
+    url = _safe_join(self.base_url, path) if not path.startswith("http") else path
+    headers = {}
+    if etag:
+        headers["If-Match"] = etag
+    resp = self._http.patch(url, json=data, headers=headers, timeout=self.timeout)
+    if resp.status_code not in (200, 204):
+        raise RedfishError(f"PATCH {url} -> {resp.status_code} {resp.text}")
+```
+
+#### `RedfishResource.patch(updates)`
+
+The resource `patch` method extracts and passes the ETag:
+
+```python
+def patch(self, updates: dict[str, Any]) -> None:
+    if not self._path:
+        raise RedfishError("PATCH requires a resource path")
+    self._ensure_fetched()
+    etag = self._raw.get("@odata.etag")
+    self._client.patch(self._path, updates, etag=etag)
+    self.refresh()
+```
+
+#### `RedfishResource.__setattr__(name, value)`
+
+Attribute assignment also passes the ETag:
+
+```python
+if name in self._raw and not isinstance(self._raw[name], (dict, list)):
+    etag = self._raw.get("@odata.etag")
+    self._client.patch(self._path, {name: value}, etag=etag)
+    self._raw[name] = value
+    object.__setattr__(self, name, value)
+```
+
+## Testing
+
+A comprehensive test suite verifies ETag functionality:
+
+```bash
+pytest tests/test_etag_support.py -v
+```
+
+Tests cover:
+1. ✅ ETag included in PATCH via attribute assignment
+2. ✅ ETag included in PATCH via `.patch()` method  
+3. ✅ PATCH works without ETag present (backward compatibility)
+
+## Benefits
+
+### 1. Prevents Lost Updates
+
+ETags ensure that updates are based on the current state of the resource:
+- Detects when another client has modified the resource
+- Prevents overwriting changes made by concurrent operations
+- Provides optimistic concurrency control
+
+### 2. BMC Compatibility
+
+Works with BMCs that require precondition headers:
+- ✅ HPE iLO (when ETag enforcement is enabled)
+- ✅ Dell iDRAC (some configurations)
+- ✅ Huawei iBMC
+- ✅ Lenovo XClarity Controller
+- ✅ Supermicro BMCs
+- ✅ Generic Redfish implementations
+
+### 3. Zero Breaking Changes
+
+- Existing code works without modification
+- Optional feature that activates automatically
+- Graceful fallback for BMCs without ETag support
+
+## Troubleshooting
+
+### HTTP 412 Precondition Failed
+
+If you still get 412 errors after this fix:
+
+1. **Stale ETag**: The resource was modified by another client
+   ```python
+   # Solution: Refresh the resource before updating
+   system.refresh()
+   system.AssetTag = "NewValue"
+   ```
+
+2. **Wrong ETag format**: Some BMCs are picky about ETag format
+   - Check BMC logs for details
+   - Verify the ETag value in the response
+
+3. **ETag not updated after refresh**: May be a BMC bug
+   ```python
+   # Workaround: Fetch a fresh instance
+   system = client.Systems[0]  # Get fresh data
+   system.AssetTag = "NewValue"
+   ```
+
+### HTTP 428 Precondition Required
+
+If you get 428 errors, it means:
+- The BMC requires an ETag but the resource doesn't have one
+- The resource hasn't been fetched yet (link stub)
+
+```python
+# Solution: Ensure resource is fetched
+system._ensure_fetched()  # Force fetch if needed
+system.patch({"AssetTag": "NewValue"})
+```
+
+## References
+
+- [RFC 7232: HTTP Conditional Requests](https://tools.ietf.org/html/rfc7232)
+- [Redfish Specification: ETags](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.15.1.pdf)
+- [HTTP 412 Precondition Failed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412)
+- [HTTP 428 Precondition Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428)
+
+## Version History
+
+- **v1.0.2** (unreleased): ETag support added
+- **v1.0.1**: Initial release without ETag support
+- **v1.0.0**: Initial release
+
+---
+
+For more information, see the [main documentation](INDEX.md) or [examples](EXAMPLES.md).

{rackfish-1.0.1 → rackfish-1.0.3}/docs/EXAMPLES.md

@@ -18,6 +18,22 @@ for system in client.Systems:
     print(f"System: {system.Id} - {system.Name} - Power: {system.PowerState}")
 ```
 
+### Alternative: Singular Access for Single-Member Collections
+
+If you know there's only one system (common in 1U servers), use singular form:
+
+```python
+# Only works if Systems collection has exactly 1 member
+system = client.System
+print(f"System: {system.Id} - {system.Name} - Power: {system.PowerState}")
+
+# Traditional methods also work:
+# system = next(iter(client.Systems))
+# system = client.Systems.Members[0]
+```
+
+See [SINGULAR_COLLECTION_ACCESS.md](SINGULAR_COLLECTION_ACCESS.md) for details.
+
 ## 3. Access OEM and Links Properties (Surfaced)
 
 ```python
@@ -792,5 +808,5 @@ client.delete("/redfish/v1/SomeCollection/Item")
 **See also:**
 
 - [OEM_LINKS_SURFACING.md](OEM_LINKS_SURFACING.md) for advanced surfacing details
-- [test_common_usage.py](test_common_usage.py) for test examples
+- [../tests/test_common_usage.py](../tests/test_common_usage.py) for test examples
 

{rackfish-1.0.1 → rackfish-1.0.3}/docs/INDEX.md

@@ -5,13 +5,15 @@ Complete documentation for the rackfish dynamic Redfish client library.
 ## 📚 Documentation Files
 
 ### Getting Started
-- **[README.md](README.md)** - Main documentation, installation, quick start, and overview
+
+- **[../README.md](../README.md)** - Main documentation, installation, quick start, and overview
   - Features and benefits
   - Quick start examples
   - Architecture overview
   - Supported vendors
 
 ### Usage Examples
+
 - **[EXAMPLES.md](EXAMPLES.md)** - Comprehensive code examples for 150+ Redfish operations
   - User management (create, delete, update)
   - Storage and logical drives
@@ -31,13 +33,32 @@ Complete documentation for the rackfish dynamic Redfish client library.
   - Maps original function names to rackfish patterns
 
 ### Advanced Topics
+
 - **[OEM_LINKS_SURFACING.md](OEM_LINKS_SURFACING.md)** - Details on automatic OEM and Links surfacing
   - How vendor extensions are surfaced
   - Collision avoidance mechanism
   - Before/after code comparisons
   - Benefits and backward compatibility
 
+- **[SINGULAR_COLLECTION_ACCESS.md](SINGULAR_COLLECTION_ACCESS.md)** - Singular access to single-member collections
+  - Convenient `client.System` instead of `next(iter(client.Systems))`
+  - Works for any collection with exactly one member
+  - Best practices and error handling
+  - Usage examples and limitations
+
+- **[ETAG_SUPPORT.md](ETAG_SUPPORT.md)** - ETag support for PATCH requests
+  - Automatic If-Match header inclusion
+  - Prevents HTTP 412 errors
+  - Usage examples and troubleshooting
+
+- **[SSL_CONFIGURATION.md](SSL_CONFIGURATION.md)** - SSL/TLS configuration guide
+  - Secure vs insecure connections
+  - Self-signed certificate handling
+  - Custom CA bundles
+  - Best practices and troubleshooting
+
 ### Testing
+
 - **[TESTS.md](TESTS.md)** - Test suite documentation
   - How to run tests
   - Test coverage overview
@@ -45,26 +66,42 @@ Complete documentation for the rackfish dynamic Redfish client library.
 
 ## 🧪 Test Files
 
-- **[test_common_usage.py](test_common_usage.py)** - Tests for common Redfish operations
+Located in `../tests/`:
+
+- **test_common_usage.py** - Tests for common Redfish operations
   - Resource traversal and collection iteration
   - OEM/Links surfacing
   - Action invocation
   - PATCH updates
   - Create/delete operations
 
-- **[test_oem_links_surfacing.py](test_oem_links_surfacing.py)** - Tests for OEM and Links surfacing
+- **test_oem_links_surfacing.py** - Tests for OEM and Links surfacing
   - OEM property surfacing (Huawei, Dell vendors)
   - Links resource surfacing (Chassis, ManagedBy)
   - Collision avoidance
   - OEM action binding
 
-- **[test_recursion_fix.py](test_recursion_fix.py)** - Tests for recursion guard
+- **test_recursion_fix.py** - Tests for recursion guard
   - 50-level deep nested structure handling
   - Lazy loading verification
 
+- **test_etag_support.py** - Tests for ETag functionality
+  - ETag extraction and usage
+  - PATCH with If-Match header
+  - Backward compatibility
+
+- **test_singular_collection_access.py** - Tests for singular collection access
+  - Single member access (success cases)
+  - Multiple members (error handling)
+  - Empty collections (error handling)
+  - Nested collections support
+  - Client-level and resource-level access
+
 ## 💻 Example Files
 
-- **[examples_comprehensive.py](examples_comprehensive.py)** - Full working examples
+Located in `../examples/`:
+
+- **examples_comprehensive.py** - Full working examples
   - Real-world usage patterns
   - User management
   - Power control
@@ -77,18 +114,20 @@ Complete documentation for the rackfish dynamic Redfish client library.
   - LDAP configuration
   - (Most write operations commented out for safety)
 
-- **[demo_surfacing_comprehensive.py](demo_surfacing_comprehensive.py)** - OEM/Links surfacing demonstration
+- **demo_surfacing_comprehensive.py** - OEM/Links surfacing demonstration
   - Mock Huawei BMC simulation
   - Before/after comparison
   - Backward compatibility verification
 
-- **[example_oem_links.py](example_oem_links.py)** - OEM/Links usage examples
+- **example_oem_links.py** - OEM/Links usage examples
   - Benefits demonstration
   - Navigation pattern improvements
 
 ## 🔧 Source Files
 
-- **[rackfish.py](rackfish.py)** - Main library implementation
+Located in `../rackfish/`:
+
+- **client.py** - Main library implementation
   - `RedfishClient` class - HTTP client and session management
   - `RedfishResource` class - Dynamic resource object graph
   - Lazy loading mechanism
@@ -97,11 +136,12 @@ Complete documentation for the rackfish dynamic Redfish client library.
 
 ## 📋 Configuration Files
 
-- **[requirements.txt](requirements.txt)** - Python dependencies (only `requests`)
+- `../requirements.txt` - Python dependencies (only `requests`)
+- `../pyproject.toml` - Project configuration and metadata
 
 ## 🤖 AI Agent Instructions
 
-- **[.github/copilot-instructions.md](.github/copilot-instructions.md)** - Guidelines for AI coding agents
+- **[../.github/copilot-instructions.md](../.github/copilot-instructions.md)** - Guidelines for AI coding agents
   - Architecture details
   - Design patterns
   - Extension guidelines
@@ -109,28 +149,47 @@ Complete documentation for the rackfish dynamic Redfish client library.
 
 ## 🚀 Quick Navigation by Task
 
-### I want to...
+### Common Tasks
 
 #### Learn the basics
-→ Start with [README.md](README.md)
+
+→ Start with [../README.md](../README.md)
 
 #### See code examples
+
 → Go to [EXAMPLES.md](EXAMPLES.md)
 
 #### Find a specific use case
+
 → Check [USE_CASES.md](USE_CASES.md) index
 
 #### Understand OEM surfacing
+
 → Read [OEM_LINKS_SURFACING.md](OEM_LINKS_SURFACING.md)
 
+#### Configure SSL/TLS
+
+→ See [SSL_CONFIGURATION.md](SSL_CONFIGURATION.md)
+
+#### Understand ETag support
+
+→ Read [ETAG_SUPPORT.md](ETAG_SUPPORT.md)
+
+#### Use singular collection access
+
+→ Read [SINGULAR_COLLECTION_ACCESS.md](SINGULAR_COLLECTION_ACCESS.md)
+
 #### Run tests
+
 → See [TESTS.md](TESTS.md)
 
 #### Write real code
-→ Look at [examples_comprehensive.py](examples_comprehensive.py)
+
+→ Look at `../examples/examples_comprehensive.py`
 
 #### Understand architecture
-→ Read [.github/copilot-instructions.md](.github/copilot-instructions.md)
+
+→ Read [../.github/copilot-instructions.md](../.github/copilot-instructions.md)
 
 ## 📊 Coverage Summary
 
@@ -163,7 +222,8 @@ Complete documentation for the rackfish dynamic Redfish client library.
 
 ## 📝 Contributing
 
-See [.github/copilot-instructions.md](.github/copilot-instructions.md) for:
+See [../.github/copilot-instructions.md](../.github/copilot-instructions.md) for:
+
 - Code architecture
 - Extension guidelines
 - Design patterns
@@ -171,15 +231,16 @@ See [.github/copilot-instructions.md](.github/copilot-instructions.md) for:
 
 ## 🔗 Related Files
 
-- `import_certificate.py` - Existing certificate import utility
+- `../CHANGELOG.md` - Version history and changes
+- `../CONTRIBUTING.md` - Contribution guidelines
+- `../LICENSE` - MIT License
 - `.python-version` - Python version specification
-- `.github/` - GitHub-specific files
 
 ---
 
 **Last Updated:** October 15, 2025
 
-**Version:** 1.0.0
+**Version:** 1.0.3
 
 **Supported Python:** 3.8+