antsibull-core

3.5.0 verified Thu Apr 16 auth: no python

antsibull-core is a foundational Python library providing core tools for building various components of the Ansible Distribution. It adheres to semantic versioning (1.0.0+), aiming for backward compatibility within major release cycles, though exceptions may occur for critical security fixes. The library is actively maintained, with the current development version being 3.x.y.

pip install antsibull-core

Common errors

error TypeError: 'LibContext' object is not iterable ↓

cause Attempting to iterate over a context object directly or treating it like a list/dictionary without accessing specific attributes or methods.

fix

Access specific attributes or call appropriate methods on LibContext or AppContext objects. For example, to get configuration, use app_ctx.config (if such an attribute exists based on API documentation).

error pydantic.v1.ValidationError: field required ↓

cause This error, specifically referencing `pydantic.v1`, occurs when antsibull-core (v3+) expects Pydantic v2, but a dependency or environment issue causes Pydantic v1 to be loaded or a Pydantic v1-style model to be used.

fix

Ensure that pydantic>=2.0 is correctly installed and that there are no conflicting Pydantic v1 installations in your environment. You might need to explicitly uninstall pydantic<2 or use a fresh virtual environment.

error ImportError: cannot import name 'LibContext' from 'antsibull_core' ↓

cause Incorrect import path for core components, as `LibContext` and `AppContext` are nested under `antsibull_core.context`.

fix

Change the import statement from from antsibull_core import LibContext to from antsibull_core.context import LibContext.

Warnings

breaking antsibull-core version 2.x.y dropped support for Python 3.6, 3.7, and 3.8. Version 3.x.y explicitly requires Python >= 3.9. ↓

fix Ensure your Python environment is 3.9 or newer for antsibull-core 3.x.y. For antsibull-core 2.x.y, use Python 3.9 or later. Upgrade your Python interpreter if necessary.

breaking antsibull-core version 3.x.y has dropped support for Pydantic v1 and now exclusively uses Pydantic v2. Code relying on Pydantic v1 APIs exposed by antsibull-core may break. ↓

fix If your project integrates deeply with antsibull-core's Pydantic models or depends on specific Pydantic v1 behaviors, you must migrate your code to be compatible with Pydantic v2. Review the Pydantic v2 migration guide.

gotcha While antsibull-core aims for no backward-incompatible changes within a major release, exceptions might be made for severe security fixes. Always review changelogs when updating to new minor or patch versions. ↓

fix Monitor release notes and changelogs, especially for critical updates, to be aware of any potentially unexpected changes. Pinning major versions in your dependency management (`antsibull-core~=3.0`) is recommended.

Imports

LibContext

from antsibull_core.context import LibContext

AppContext

from antsibull_core.context import AppContext

Quickstart

Initialize basic contexts provided by antsibull-core. These contexts are typically used by other antsibull projects to manage application state, configuration, and interactions with the underlying Ansible environment.

from antsibull_core.context import LibContext, AppContext

# Example of initializing a library context (often used internally by other antsibull tools)
lib_ctx = LibContext()
print(f"Initialized LibContext: {lib_ctx}")

# Example of initializing an application context (often used internally by other antsibull tools)
app_ctx = AppContext(lib_context=lib_ctx, cwd="/tmp")
print(f"Initialized AppContext: {app_ctx}")