{"id":8828,"library":"antsibull-core","title":"antsibull-core","description":"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.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/antsibull-core","tags":["ansible","build-tools","library","documentation-tools"],"install":[{"cmd":"pip install antsibull-core","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false},{"reason":"Core functionality depends on antsibull-fileutils for file-related utilities.","package":"antsibull-fileutils","optional":false},{"reason":"Version 3.x.y specifically requires Pydantic v2. Earlier versions might use Pydantic v1.","package":"pydantic","optional":false}],"imports":[{"symbol":"LibContext","correct":"from antsibull_core.context import LibContext"},{"symbol":"AppContext","correct":"from antsibull_core.context import AppContext"}],"quickstart":{"code":"from antsibull_core.context import LibContext, AppContext\n\n# Example of initializing a library context (often used internally by other antsibull tools)\nlib_ctx = LibContext()\nprint(f\"Initialized LibContext: {lib_ctx}\")\n\n# Example of initializing an application context (often used internally by other antsibull tools)\napp_ctx = AppContext(lib_context=lib_ctx, cwd=\"/tmp\")\nprint(f\"Initialized AppContext: {app_ctx}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0, 3.0.0+"},{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.0.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","cause":"Attempting to iterate over a context object directly or treating it like a list/dictionary without accessing specific attributes or methods.","error":"TypeError: 'LibContext' object is not iterable"},{"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.","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.","error":"pydantic.v1.ValidationError: field required"},{"fix":"Change the import statement from `from antsibull_core import LibContext` to `from antsibull_core.context import LibContext`.","cause":"Incorrect import path for core components, as `LibContext` and `AppContext` are nested under `antsibull_core.context`.","error":"ImportError: cannot import name 'LibContext' from 'antsibull_core'"}]}