Skip to content

docs: Update documentation to reflect current state #107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
privateip merged 1 commit into from
Feb 25, 2026
Merged

docs: Update documentation to reflect current state #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 8 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -192,25 +191,18 @@ 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)
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.

Expand Down
106 changes: 13 additions & 93 deletions docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,6 @@ $ uv run pytest tests/test_<module>.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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down