rackfish 1.0.0__tar.gz

rackfish-1.0.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+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).
+
+## [1.0.0] - 2025-10-15
+
+### Added
+
+- Initial release of rackfish
+- Dynamic Redfish client with lazy loading
+- Automatic OEM and Links property surfacing
+- Action method binding with ActionInfo validation
+- Collection iteration support
+- Session and basic authentication
+- Support for 150+ common Redfish operations
+- Comprehensive documentation and examples
+- Full test suite with 100% passing tests
+- Support for Huawei, Dell, HPE, Lenovo, Supermicro and all Redfish-compliant BMCs
+
+### Features
+
+- Zero external dependencies (except `requests`)
+- Lazy resource fetching for performance
+- Dynamic attribute mapping from JSON
+- Collision-safe OEM/Links surfacing
+- Type-safe action parameter validation
+- Pythonic API with natural dot notation
+- Thread-safe HTTP session management
+- Recursion guard for deeply nested structures
+
+### Documentation
+
+- Complete API documentation
+- 150+ usage examples
+- Use case index
+- Test suite documentation
+- Comprehensive README
+- GitHub/PyPI ready structure
+
+[1.0.0]: https://github.com/yourusername/rackfish/releases/tag/v1.0.0

rackfish-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing to rackfish
+
+Thank you for your interest in contributing to rackfish! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions with the project community.
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Check if the bug has already been reported in Issues
+- Include detailed steps to reproduce
+- Include Python version, OS, and BMC vendor/model
+- Provide relevant error messages and logs
+
+### Suggesting Features
+
+- Open an issue describing the feature
+- Explain the use case and benefits
+- Provide examples if possible
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`pytest tests/`)
+6. Update documentation as needed
+7. Commit your changes (`git commit -m 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/rackfish.git
+cd rackfish
+
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Run linting
+ruff check rackfish/
+black --check rackfish/
+mypy rackfish/
+```
+
+## Coding Standards
+
+### Style Guide
+
+- Follow PEP 8
+- Use Black for code formatting (line length: 100)
+- Use Ruff for linting
+- Use type hints where appropriate
+- Write docstrings for public functions and classes
+
+### Code Organization
+
+- Keep functions focused and small
+- Use meaningful variable names
+- Add comments for complex logic
+- Maintain backward compatibility when possible
+
+### Testing
+
+- Write tests for all new functionality
+- Maintain or improve test coverage
+- Use descriptive test names
+- Mock external dependencies (BMC connections)
+- Test edge cases and error conditions
+
+### Documentation
+
+- Update README.md for major changes
+- Add examples to `docs/EXAMPLES.md`
+- Update `docs/USE_CASES.md` for new operations
+- Add docstrings with examples
+- Update CHANGELOG.md
+
+## Architecture Guidelines
+
+See `.github/copilot-instructions.md` for detailed architecture documentation:
+
+- Lazy loading semantics
+- OEM/Links surfacing mechanism
+- Action binding and validation
+- Collection protocols
+- Recursion guard implementation
+
+## Review Process
+
+1. All PRs require review before merging
+2. Automated tests must pass
+3. Code coverage should not decrease
+4. Documentation must be updated
+5. CHANGELOG.md must be updated
+
+## Release Process
+
+1. Update version in `rackfish/__init__.py` and `pyproject.toml`
+2. Update CHANGELOG.md
+3. Create a git tag
+4. Build and publish to PyPI
+
+## Questions?
+
+Feel free to open an issue for questions or discussion.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

rackfish-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dmitrii Frolov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rackfish-1.0.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# Manifest file for source distributions
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+include requirements.txt
+
+recursive-include pyredfisher *.py
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+
+# Exclude development files
+exclude .gitignore
+exclude .python-version
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store

rackfish-1.0.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: rackfish
+Version: 1.0.0
+Summary: A lightweight, dynamic Python client for Redfish BMC APIs
+Author-email: Dmitrii Frolov <thefrolov@mts.ru>
+License: MIT
+Project-URL: Homepage, https://github.com/thefrolov/rackfish
+Project-URL: Documentation, https://github.com/thefrolov/rackfish/blob/main/docs/INDEX.md
+Project-URL: Repository, https://github.com/thefrolov/rackfish
+Project-URL: Issues, https://github.com/thefrolov/rackfish/issues
+Project-URL: Changelog, https://github.com/thefrolov/rackfish/blob/main/CHANGELOG.md
+Keywords: redfish,bmc,ipmi,server-management,hardware-management,datacenter,ilo,idrac,server
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# rackfish - Dynamic Redfish Client
+
+[![PyPI version](https://img.shields.io/pypi/v/rackfish.svg)](https://pypi.org/project/rackfish/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/rackfish.svg)](https://pypi.org/project/rackfish/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/yourusername/rackfish/workflows/CI/badge.svg)](https://github.com/yourusername/rackfish/actions)
+[![codecov](https://codecov.io/gh/yourusername/rackfish/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/rackfish)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+A lightweight, dynamic Python client for interacting with Redfish BMC (Baseboard Management Controller) APIs. Provides intuitive access to server hardware management through lazy-loaded object graphs, automatic OEM property surfacing, and validated action invocation.
+
+## 🎯 Why rackfish?
+
+- 🚀 **Zero Dependencies** (except `requests`) - Minimal footprint
+- ⚡ **Lazy Loading** - Resources fetched on-demand for performance
+- 🎨 **Pythonic Interface** - JSON properties become Python attributes
+- 🔧 **OEM Support** - Vendor extensions (Huawei, Dell, HPE) automatically accessible
+- 🔗 **Smart Navigation** - Related resources directly navigable via Links
+- ✅ **Action Validation** - Parameter validation using ActionInfo schemas
+- 📚 **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)
+
+```bash
+pip install rackfish
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourusername/rackfish.git
+cd rackfish
+pip install -e .
+```
+
+### Development installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from rackfish import RedfishClient
+
+# Connect to BMC
+client = RedfishClient("https://bmc.example.com", "admin", "password", 
+                       use_session=True, verify_ssl=False)
+root = client.connect()
+
+# Power control
+system = next(iter(client.Systems))
+system.Reset(ResetType="GracefulRestart")
+
+# Access OEM properties (auto-surfaced)
+if hasattr(system, "BootMode"):
+    print(f"Boot Mode: {system.BootMode}")
+
+# Navigate linked resources
+for chassis in system.Chassis:
+    print(f"Chassis: {chassis.Name}")
+
+# Logout
+client.logout()
+```
+
+## Documentation
+
+- **[docs/EXAMPLES.md](docs/EXAMPLES.md)** - Comprehensive usage examples for all common Redfish operations
+- **[docs/USE_CASES.md](docs/USE_CASES.md)** - Complete index of 150+ supported use cases
+- **[docs/OEM_LINKS_SURFACING.md](docs/OEM_LINKS_SURFACING.md)** - Details on automatic OEM and Links surfacing
+- **[docs/TESTS.md](docs/TESTS.md)** - Test suite documentation
+- **[docs/INDEX.md](docs/INDEX.md)** - Master navigation document
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
+
+## Common Use Cases
+
+### User Management
+```python
+accounts = client.AccountService.Accounts
+new_user = accounts.create({"UserName": "operator", "Password": "pass", "RoleId": "Operator"})
+new_user.RoleId = "Administrator"
+new_user.delete()
+```
+
+### Storage Management
+```python
+storage = next(iter(client.Systems)).Storage[0]
+volume = storage.Volumes.create({"Name": "DataVol", "CapacityBytes": 500*1024**3})
+```
+
+### Network Configuration
+```python
+port = client.Managers[0].EthernetInterfaces[0]
+port.patch({"IPv4Addresses": [{"Address": "192.168.1.100", "SubnetMask": "255.255.255.0"}]})
+```
+
+### Event Subscriptions
+```python
+subs = client.EventService.Subscriptions
+sub = subs.create({"Destination": "https://listener/events", "EventTypes": ["Alert"]})
+```
+
+### Firmware Updates
+```python
+client.UpdateService.SimpleUpdate(ImageURI="http://server/fw.bin", TransferProtocol="HTTP")
+```
+
+### System Health Monitoring
+```python
+for temp in chassis.Thermal.Temperatures:
+    print(f"{temp.Name}: {temp.ReadingCelsius}°C")
+```
+
+See [EXAMPLES.md](EXAMPLES.md) for 100+ more examples covering:
+- BIOS configuration
+- Certificate management
+- Virtual media (KVM)
+- LDAP authentication
+- Boot order configuration
+- 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
+
+```
+rackfish/
+├── rackfish/          # Main package
+│   ├── __init__.py       # Package initialization
+│   └── client.py         # Core library implementation
+├── tests/                # Test suite
+│   ├── __init__.py
+│   ├── test_common_usage.py
+│   ├── test_oem_links_surfacing.py
+│   └── test_recursion_fix.py
+├── examples/             # Usage examples
+│   ├── examples_comprehensive.py
+│   ├── demo_surfacing_comprehensive.py
+│   └── example_oem_links.py
+├── docs/                 # Documentation
+│   ├── INDEX.md
+│   ├── EXAMPLES.md
+│   ├── USE_CASES.md
+│   ├── TESTS.md
+│   ├── OEM_LINKS_SURFACING.md
+│   └── COMPLETION_SUMMARY.md
+├── .github/
+│   └── copilot-instructions.md
+├── README.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── pyproject.toml
+└── requirements.txt
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Architecture
+
+### Core Components
+
+- **`RedfishClient`** - HTTP session management, authentication, base URL handling
+- **`RedfishResource`** - Dynamic resource representation with lazy loading
+- **`_convert`** - Recursive JSON-to-object mapping with link stub creation
+- **`_hydrate`** - Property mapping, OEM/Links surfacing, action binding
+
+### Key Design Patterns
+
+1. **Lazy Loading** - Link stubs defer fetching until attribute access
+2. **OEM Surfacing** - Vendor properties promoted to main object (collision-safe)
+3. **Links Surfacing** - Related resources directly accessible (collision-safe)
+4. **Action Methods** - Redfish Actions bound as callable instance methods
+5. **ActionInfo Validation** - Parameter schemas fetched and enforced
+
+### Recursion Guard
+
+Deeply nested JSON structures are handled safely by deferring hydration (`fetched=False`) for all embedded resources, preventing stack overflow.
+
+## Supported Use Cases
+
+The library supports **150+ common Redfish operations** including:
+
+### System Management
+- Power control (Reset, ForceOff, GracefulRestart)
+- Boot order configuration
+- System health monitoring
+
+### Storage
+- Logical drive creation/deletion
+- Storage controller management
+- Drive inventory and status
+
+### Network
+- IP configuration (IPv4/IPv6)
+- VLAN management
+- DNS/NTP configuration
+- SNMP trap configuration
+
+### User & Security
+- User account CRUD
+- Role assignment
+- Password policies
+- LDAP integration
+
+### Certificates
+- CSR generation
+- SSL/TLS certificate import
+- SSH public key management
+- Two-factor authentication certs
+
+### Firmware & BIOS
+- Firmware updates
+- BIOS configuration
+- BMC reset/rollback
+
+### Monitoring & Logs
+- Temperature sensors
+- Fan speeds
+- Voltage readings
+- System event logs (SEL)
+
+### Virtual Media
+- ISO mounting (KVM)
+- VNC/KVM configuration
+- Virtual media operations
+
+See [EXAMPLES.md](EXAMPLES.md) for complete list and code samples.
+
+## OEM Vendor Support
+
+Works with any Redfish-compliant BMC including:
+
+- **Huawei** - TaiShan servers, FruControl, custom boot modes
+- **Dell** - iDRAC, DellAttributes
+- **HPE** - iLO, HPE-specific extensions
+- **Lenovo** - XClarity
+- **Supermicro** - IPMI/Redfish hybrid
+- And any other vendor implementing Redfish standard
+
+OEM extensions are automatically surfaced to the main object for easy access.
+
+## Advanced Features
+
+### Generic Request Helpers
+
+For operations not exposed as methods:
+
+```python
+response = client.get("/redfish/v1/custom/path")
+client.post("/redfish/v1/Actions/Custom", data={"param": "value"})
+client.patch("/redfish/v1/Systems/1", data={"AssetTag": "NEW"})
+client.delete("/redfish/v1/Collection/Item")
+```
+
+### Allowable Values
+
+Get valid parameter values:
+
+```python
+reset_types = system.get_allowable_values("ResetType")
+print(f"Valid reset types: {reset_types}")
+```
+
+### Raw JSON Access
+
+```python
+raw_data = resource.to_dict()
+```
+
+## Contributing
+
+See `.github/copilot-instructions.md` for development guidelines and architecture details.
+
+## License
+
+See LICENSE file.
+
+## Version
+
+Current version: 1.0.0
+
+## Requirements
+
+- Python 3.8+
+- requests library
+
+## Support
+
+For issues, questions, or contributions, please refer to the project repository.