diff --git a/README.md b/README.md index 390c332..8bece76 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ [![Python Versions](https://img.shields.io/pypi/pyversions/ipsdk.svg)](https://pypi.org/project/ipsdk/) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Tests](https://github.com/itential/ipsdk/workflows/Run%20pre%20merge%20pipeline/badge.svg)](https://github.com/itential/ipsdk/actions) -[![Coverage](https://img.shields.io/badge/coverage-95%25-green)](https://github.com/itential/ipsdk) +[![Coverage](https://img.shields.io/badge/coverage-100%25-green)](https://github.com/itential/ipsdk) The Itential Python SDK provides a robust client implementation in Python for writing scripts and applications that can make API calls to Itential Platform or Itential Automation Gateway 4.x. -**Status**: Beta - Active development with comprehensive test coverage (95%+) +**Status**: Beta - Active development with comprehensive test coverage (100%) ## Features @@ -19,11 +19,10 @@ Automation Gateway 4.x. - OAuth (client credentials) for Itential Platform - Basic authentication (username/password) for both Platform and Gateway - **Sync and Async Support**: Both synchronous and asynchronous HTTP clients via `want_async` parameter -- **Comprehensive Logging**: Custom logging system with multiple levels (including FATAL), file and console handlers, and httpx integration control -- **Flexible Configuration**: Customizable connection settings including TLS, certificate verification, timeouts, and proxy support -- **Type Safety**: Full type hints with mypy support for enhanced development experience +- **Comprehensive Logging**: Custom logging system with multiple levels (including TRACE and FATAL) and httpx integration control +- **Flexible Configuration**: Customizable connection settings including TLS, certificate verification, and timeouts +- **Type Safety**: Full type hints for enhanced development experience - **HTTP Methods**: Support for GET, POST, PUT, DELETE, and PATCH operations with automatic JSON handling -- **Request/Response Wrappers**: Enhanced request and response objects with additional utilities beyond raw httpx ## Getting started @@ -192,12 +191,6 @@ import ipsdk # Configure logging level ipsdk.logging.set_level(ipsdk.logging.DEBUG) -# Enable file logging -ipsdk.logging.configure_file_logging( - "/path/to/logfile.log", - level=ipsdk.logging.INFO -) - # Use convenience functions ipsdk.logging.info("Connected to platform") ipsdk.logging.debug("Request details: %s", request_data) @@ -205,12 +198,11 @@ ipsdk.logging.error("API call failed") ``` **Logging Features**: -- **Multiple Log Levels**: DEBUG, INFO, WARNING, ERROR, CRITICAL, and custom FATAL (90) level +- **Multiple Log Levels**: TRACE (5), DEBUG, INFO, WARNING, ERROR, CRITICAL, FATAL (90), and NONE (100) - **Convenience Functions**: `debug()`, `info()`, `warning()`, `error()`, `critical()`, `fatal()`, `exception()` -- **File Logging**: Automatic directory creation and custom formatting support -- **Console Control**: Switch between stdout/stderr output +- **Function Tracing**: `@trace` decorator for automatic entry/exit logging with timing +- **Sensitive Data Filtering**: Automatic redaction of PII, API keys, passwords, and tokens - **httpx Integration**: Optional control of httpx/httpcore logging via `propagate` parameter -- **Handler Management**: Add/remove file handlers and customize console output For detailed logging documentation, see the logging module docstrings. diff --git a/docs/development.md b/docs/development.md index 8f9b723..8703c23 100644 --- a/docs/development.md +++ b/docs/development.md @@ -25,9 +25,6 @@ $ uv run pytest tests/test_.py # Run tests with coverage $ uv run pytest --cov=src/ipsdk --cov-report=term --cov-report=html tests/ $ make coverage - -# Run tests with coverage check (enforces 95% minimum coverage) -$ make coverage-check ``` ### Multi-Version Testing with Tox @@ -86,35 +83,14 @@ $ uv run bandit -r src/ipsdk --configfile pyproject.toml $ make security ``` -### Pre-commit Hooks - -The project uses pre-commit hooks for automatic code quality checks: - -```bash -# Install git hooks -$ uv run pre-commit install - -# Run on all files -$ uv run pre-commit run --all-files -``` - -Pre-commit hooks include: -- Basic file checks (trailing whitespace, EOF fixer, YAML/TOML validation) -- Ruff linting and formatting -- MyPy type checking - ## Build and Maintenance ```bash # Clean build artifacts $ make clean -# Run premerge checks (clean, lint, security, and test with coverage check) +# Run premerge checks (clean, lint, security, license check, and test) $ make premerge - -# Generate changelog (uses git-cliff with conventional commits) -$ make changelog # Generate full CHANGELOG.md -$ make changelog-unreleased # Show unreleased changes only ``` ### Version Management @@ -128,14 +104,13 @@ The project uses **dynamic versioning** from git tags: ## Development Workflow 1. **Setup**: Run `uv sync` to install dependencies and create a virtual environment -2. **Install hooks**: Run `uv run pre-commit install` to set up git hooks (optional but recommended) -3. **Development**: Make your changes to the codebase -4. **Format**: Run `make format` to auto-format code -5. **Testing**: Run tests with `make test` or `uv run pytest tests` -6. **Quality Checks**: Run `make lint` and `make security` to check code quality -7. **Coverage**: Ensure test coverage meets 95% threshold with `make coverage-check` -8. **Pre-merge**: Run `make premerge` before submitting changes (runs all checks) -9. **Multi-version**: Optionally test across Python versions with `make tox` +2. **Development**: Make your changes to the codebase +3. **Format**: Run `make format` to auto-format code +4. **Testing**: Run tests with `make test` or `uv run pytest tests` +5. **Quality Checks**: Run `make lint` and `make security` to check code quality +6. **Coverage**: Run `make coverage` to generate coverage report +7. **Pre-merge**: Run `make premerge` before submitting changes (runs all checks) +8. **Multi-version**: Optionally test across Python versions with `make tox` ## Additional Tools @@ -149,8 +124,6 @@ The project uses the following development tools: - **bandit**: Security vulnerability scanner - **tox**: Multi-version Python testing (3.10, 3.11, 3.12, 3.13) - **tox-uv**: Tox integration with uv for fast environments -- **pre-commit**: Git hooks for automated quality checks -- **git-cliff**: Changelog generator using conventional commits - **q**: Debugging utility All tools are configured in `pyproject.toml` and can be run through `uv` or the provided Makefile targets. @@ -168,14 +141,13 @@ The project uses comprehensive Ruff configuration with 30+ rule sets: ### Coverage Requirements The SDK enforces strict test coverage: -- **Minimum coverage**: 95% -- Coverage check runs in `make premerge` and CI/CD pipeline -- Pipeline fails if coverage drops below threshold +- **Current coverage**: 100% +- Coverage report runs in `make premerge` and CI/CD pipeline - Generate HTML reports with `make coverage` ## Python Version Support -The SDK officially supports Python >=3.8 and is tested on: +The SDK officially supports Python >=3.10 and is tested on: - Python 3.10 - Python 3.11 - Python 3.12 @@ -201,11 +173,9 @@ The SDK provides logging level constants that you can use instead of importing t The SDK includes a comprehensive logging system: - **Function tracing decorator** (`@trace`) with automatic timing and entry/exit logging - **Custom logging levels**: TRACE (5), FATAL (90), and NONE (100) in addition to standard levels -- **Convenience functions**: `debug()`, `info()`, `warning()`, `error()`, `critical()`, `fatal()`, `exception()`, `trace()` -- **File logging** with automatic directory creation and custom formatting -- **Console output control** (stdout/stderr switching) +- **Convenience functions**: `debug()`, `info()`, `warning()`, `error()`, `critical()`, `fatal()`, `exception()` - **httpx/httpcore logging control** via `propagate` parameter -- **Centralized configuration** via `set_level()` and `configure_file_logging()` +- **Centralized configuration** via `set_level()` - **Sensitive data filtering** to automatically redact PII, API keys, passwords, and tokens ### Available Logging Levels @@ -222,56 +192,6 @@ The SDK provides the following logging level constants: - `ipsdk.logging.FATAL` - Fatal error messages (90) - `ipsdk.logging.NONE` - Disable all logging (100) -### File Logging - -The SDK supports optional file logging in addition to console logging. You can configure file logging using several approaches: - -#### Quick Setup with `configure_file_logging` - -The easiest way to enable both console and file logging: - -```python ->>> import ipsdk - -# Enable both console and file logging ->>> ipsdk.logging.configure_file_logging("/path/to/app.log", level=ipsdk.logging.DEBUG) -``` - -#### Manual File Handler Management - -For more control, you can add and remove file handlers manually: - -```python ->>> import ipsdk - -# First set the console logging level ->>> ipsdk.logging.set_level(ipsdk.logging.INFO) - -# Add a file handler ->>> ipsdk.logging.add_file_handler("/path/to/app.log") - -# Add multiple file handlers with different levels ->>> ipsdk.logging.add_file_handler("/path/to/debug.log", level=ipsdk.logging.DEBUG) ->>> ipsdk.logging.add_file_handler("/path/to/errors.log", level=ipsdk.logging.ERROR) - -# Remove all file handlers when done ->>> ipsdk.logging.remove_file_handlers() -``` - -#### Custom Log Formatting - -You can specify custom format strings for file handlers: - -```python ->>> custom_format = "%(asctime)s [%(levelname)s] %(message)s" ->>> ipsdk.logging.add_file_handler("/path/to/app.log", format_string=custom_format) - -# Or with configure_file_logging ->>> ipsdk.logging.configure_file_logging("/path/to/app.log", format_string=custom_format) -``` - -**Note:** File logging automatically creates parent directories if they don't exist. - ### Function Tracing with @trace Decorator The SDK provides a powerful `@trace` decorator for debugging and performance monitoring. When applied to functions or methods, it automatically logs entry/exit points with execution timing.