AWXKit

Common errors

• TypeError: HelpfulArgumentParser._parse_known_args() takes 3 positional arguments but 4 were given

  cause Incompatibility with Python 3.13's `argparse` module, which changed the signature of `_parse_known_args`.
  fix Use a Python virtual environment with Python 3.11 or 3.12.

• AttributeError: 'CLI' object has no attribute 'verbose'

  cause Similar to the `TypeError` above, this is another symptom of `awxkit`'s incompatibility with Python 3.13's `argparse` changes.
  fix Revert to Python 3.11 or 3.12 until `awxkit` is updated for Python 3.13.

• ModuleNotFoundError: No module named 'pkg_resources'

  cause This error can occur if `setuptools` (which provides `pkg_resources`) is not correctly installed or if the Python environment is corrupted, especially in minimal container environments.
  fix Ensure `setuptools` is installed: `pip install setuptools`.

• AttributeError: 'Api' object has no attribute 'available_versions'

  cause This usually indicates an issue where `awxkit` cannot properly fetch or interpret the API version information from the AWX/Controller host, possibly due to an outdated AWX/Controller version or an incorrect `base_url`.
  fix Verify that your `AWX_HOST` is correct and pointing to a valid AWX or Automation Controller instance. Ensure your AWX/Controller version is compatible with your `awxkit` version.

• Error: argument resource: conflicting subparser: config.

  cause This specific error was reported when using `awxkit` CLI arguments with `--conf.*` in Python 3.11, suggesting an issue with how the `argparse` library handles conflicting subparsers in that Python version.
  fix Downgrade your Python environment to Python 3.10 if this issue persists. Alternatively, use environment variables (`CONTROLLER_HOST`, `CONTROLLER_USERNAME`, etc.) instead of `--conf.*` flags if possible.

Warnings

• breaking Starting with AWXKit 24.0.0, JSON Web Tokens (JWT) became the default authentication method. This might require updates to existing authentication logic that relied on older defaults.
  Fix: Review authentication code for JWT compatibility. If using username/password, explicitly configure `config.credentials` as shown in the quickstart or use OAuth2 tokens.
• breaking AWXKit 24.1.0 updated the required Python version from 3.9 to 3.11. Running on older Python versions (e.g., 3.9 or 3.10) may lead to unexpected errors or incompatibility issues.
  Fix: Ensure your environment uses Python 3.11 or newer. Upgrade your Python interpreter if necessary.
• gotcha AWXKit version 24.3.0 was explicitly marked as 'DO NOT USE/UPGRADE' in its release notes due to critical issues.
  Fix: Avoid installing or upgrading to version 24.3.0. Use 24.3.1 or a later stable release.
• gotcha Using awxkit with Python 3.13 can lead to `TypeError: HelpfulArgumentParser._parse_known_args()` or `AttributeError: 'CLI' object has no attribute 'verbose'` errors due to changes in Python's `argparse` module.
  Fix: As a temporary workaround, use Python 3.11 or 3.12. Monitor GitHub issues for a permanent fix compatible with Python 3.13.
• deprecated The `awxkit` library currently relies on the `pkg_resources` module, which is deprecated in modern Python versions and might lead to future compatibility issues or warnings.
  Fix: No direct fix for users; this requires an upstream update to use `importlib.metadata` instead.
• breaking After version 24.6.1, AWX is undergoing significant architectural refactoring to a pluggable service-oriented design. This shift may introduce substantial breaking changes and impact stability, as semantic versioning is being replaced by CalVer.
  Fix: If using AWXKit in a production environment, consider moving to Red Hat Ansible Automation Platform for greater stability. For development or lab environments, be prepared for potential breaking changes and monitor AWX project updates closely.

Install

• pip install awxkit Install latest stable version

Imports

• api, config, utils, cli

  from awxkit import api, config, utils, cli

  Common top-level imports for both API interaction and CLI utilities.
• ApiV2

  from awxkit.api import ApiV2

  For direct interaction with the AWX API v2.
• resources

  from awxkit.api.resources import resources

  To access AWX API resources programmatically.
• run

  from awxkit.cli import run

  Used for running AWX CLI commands programmatically.

Quickstart

This quickstart demonstrates how to connect to an AWX instance using username/password authentication and list organizations. It uses environment variables for secure credential handling.

import os
from awxkit.api import ApiV2, config
from awxkit.api.resources import resources
from awxkit.utils import PseudoNamespace

# Configure AWX host and credentials
config.base_url = os.environ.get('AWX_HOST', 'https://localhost:8043')
config.credentials = PseudoNamespace({
    'default': {
        'username': os.environ.get('AWX_USERNAME', 'admin'),
        'password': os.environ.get('AWX_PASSWORD', 'password'),
        'insecure': os.environ.get('AWX_INSECURE_SSL', 'False').lower() == 'true'
    }
})

try:
    # Load a session and get available API resources
    session_connection = ApiV2().load_session().get()
    api_resources = session_connection.get(resources)

    print(f"Successfully connected to AWX at: {config.base_url}")
    print(f"Available API resources: {list(api_resources.keys())}")

    # Example: List all organizations
    organizations = api_resources.organizations.get().results
    print(f"Found {len(organizations)} organizations:")
    for org in organizations:
        print(f" - {org.name} (ID: {org.id})")

except Exception as e:
    print(f"Error connecting to AWX: {e}")
    print("Please ensure AWX_HOST, AWX_USERNAME, AWX_PASSWORD, and AWX_INSECURE_SSL (optional) environment variables are set correctly.")