1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

deps module_utils: add docs (#8417)

* add docs for the deps module utils

* wordsmithing

* fix reference and filename

* add entries to BOTMETA.yml

* Update docs/docsite/rst/moddev_guide_deps.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* adjust docs organisation

* adjust docs organisation II

* PR adjustments

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Alexei Znamensky 2024-06-02 10:16:53 +12:00 committed by GitHub
parent 58ce19d2c2
commit 5a5188a453
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 79 additions and 0 deletions

2
.github/BOTMETA.yml vendored
View file

@ -1456,6 +1456,8 @@ files:
maintainers: baldwinSPC nurfet-becirevic t0mk teebes
docs/docsite/rst/guide_scaleway.rst:
maintainers: $team_scaleway
docs/docsite/rst/guide_deps.rst:
maintainers: russoz
docs/docsite/rst/test_guide.rst:
maintainers: felixfontein
#########################

View file

@ -14,3 +14,6 @@ sections:
- guide_online
- guide_packet
- guide_scaleway
- title: Developer Guides
toctree:
- guide_deps

View file

@ -0,0 +1,74 @@
..
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later
.. _ansible_collections.community.general.docsite.guide_deps:
``deps`` Guide
==============
Using ``deps``
^^^^^^^^^^^^^^
The ``ansible_collections.community.general.plugins.module_utils.deps`` module util simplifies
the importing of code as described in :ref:`Importing and using shared code <shared_code>`.
Please notice that ``deps`` is meant to be used specifically with Ansible modules, and not other types of plugins.
The same example from the Developer Guide would become:
.. code-block:: python
from ansible_collections.community.general.plugins.module_utils import deps
with deps.declare("foo"):
import foo
Then in ``main()``, just after the argspec (or anywhere in the code, for that matter), do
.. code-block:: python
deps.validate(module) # assuming module is a valid AnsibleModule instance
By default, ``deps`` will rely on ``ansible.module_utils.basic.missing_required_lib`` to generate
a message about a failing import. That function accepts parameters ``reason`` and ``url``, and
and so does ``deps```:
.. code-block:: python
with deps.declare("foo", reason="foo is needed to properly bar", url="https://foo.bar.io"):
import foo
If you would rather write a custom message instead of using ``missing_required_lib`` then do:
.. code-block:: python
with deps.declare("foo", msg="Custom msg explaining why foo is needed"):
import foo
``deps`` allows for multiple dependencies to be declared:
.. code-block:: python
with deps.declare("foo"):
import foo
with deps.declare("bar"):
import bar
with deps.declare("doe"):
import doe
By default, ``deps.validate()`` will check on all the declared dependencies, but if so desired,
they can be validated selectively by doing:
.. code-block:: python
deps.validate(module, "foo") # only validates the "foo" dependency
deps.validate(module, "doe:bar") # only validates the "doe" and "bar" dependencies
deps.validate(module, "-doe:bar") # validates all dependencies except "doe" and "bar"
.. versionadded:: 6.1.0