[PR #7490/e0346d40 backport][stable-8] Add onepassword_doc lookup plugin (#7617)

Add onepassword_doc lookup plugin (#7490)

* Add onepassword_doc lookup plugin

* Switch to a doc fragment

* Add unit test

* Update docs

* Move parameter validation to the OnePass object

This makes it built in for other lookup plugins using this class.

* Use kwargs for OnePass instantiation

There are enough parameters now that using them positionally can result in
odd behavior.

* Update tests

Correct conftest file name so fixtures are discovered and loaded correctly
Move constant so it doesn’t need to be imported
Add a patch since the parameter validation moved to part of the class init

* Use a lookup docs fragment

* Correct plugin description

(cherry picked from commit e0346d400f)

Co-authored-by: Sam Doran <sdoran@redhat.com>

plugins/lookup/onepassword_raw.py

@@ -15,67 +15,23 @@ DOCUMENTATION = '''
       - Andrew Zenk (@azenk)
       - Sam Doran (@samdoran)
     requirements:
-      - C(op) 1Password command line utility. See U(https://support.1password.com/command-line/)
-    short_description: fetch an entire item from 1Password
+      - C(op) 1Password command line utility
+    short_description: Fetch an entire item from 1Password
     description:
       - P(community.general.onepassword_raw#lookup) wraps C(op) command line utility to fetch an entire item from 1Password.
     options:
       _terms:
-        description: identifier(s) (UUID, name, or domain; case-insensitive) of item(s) to retrieve.
+        description: Identifier(s) (case-insensitive UUID or name) of item(s) to retrieve.
         required: true
-      master_password:
-        description: The password used to unlock the specified vault.
-        aliases: ['vault_password']
-      section:
-        description: Item section containing the field to retrieve (case-insensitive). If absent will return first match from any section.
-      subdomain:
-        description: The 1Password subdomain to authenticate against.
-      domain:
-        description: Domain of 1Password.
-        version_added: 6.0.0
-        default: '1password.com'
-        type: str
       account_id:
-        description: The account ID to target.
-        type: str
         version_added: 7.5.0
-      username:
-        description: The username used to sign in.
-      secret_key:
-        description: The secret key used when performing an initial sign in.
+      domain:
+        version_added: 6.0.0
       service_account_token:
-        description:
-          - The access key for a service account.
-          - Only works with 1Password CLI version 2 or later.
-        type: string
         version_added: 7.1.0
-      connect_host:
-        description: The host for 1Password Connect. Must be used in combination with O(connect_token).
-        type: str
-        env:
-          - name: OP_CONNECT_HOST
-        version_added: 8.1.0
-      connect_token:
-        description: The token for 1Password Connect. Must be used in combination with O(connect_host).
-        type: str
-        env:
-          - name: OP_CONNECT_TOKEN
-        version_added: 8.1.0
-      vault:
-        description: Vault containing the item to retrieve (case-insensitive). If absent will search all vaults.
-    notes:
-      - This lookup will use an existing 1Password session if one exists. If not, and you have already
-        performed an initial sign in (meaning C(~/.op/config exists)), then only the O(master_password) is required.
-        You may optionally specify O(subdomain) in this scenario, otherwise the last used subdomain will be used by C(op).
-      - This lookup can perform an initial login by providing O(subdomain), O(username), O(secret_key), and O(master_password).
-      - Can target a specific account by providing the O(account_id).
-      - Due to the B(very) sensitive nature of these credentials, it is B(highly) recommended that you only pass in the minimal credentials
-        needed at any given time. Also, store these credentials in an Ansible Vault using a key that is equal to or greater in strength
-        to the 1Password master password.
-      - This lookup stores potentially sensitive data from 1Password as Ansible facts.
-        Facts are subject to caching if enabled, which means this data could be stored in clear text
-        on disk or in a database.
-      - Tested with C(op) version 2.7.0
+    extends_documentation_fragment:
+      - community.general.onepassword
+      - community.general.onepassword.lookup
 '''
 
 EXAMPLES = """
@@ -90,7 +46,7 @@ EXAMPLES = """
 
 RETURN = """
   _raw:
-    description: field data requested
+    description: Entire item requested.
     type: list
     elements: dict
 """
@@ -98,7 +54,6 @@ RETURN = """
 import json
 
 from ansible_collections.community.general.plugins.lookup.onepassword import OnePass
-from ansible.errors import AnsibleOptionsError
 from ansible.plugins.lookup import LookupBase
 
 
@@ -118,10 +73,17 @@ class LookupModule(LookupBase):
         connect_host = self.get_option("connect_host")
         connect_token = self.get_option("connect_token")
 
-        if (connect_host or connect_token) and None in (connect_host, connect_token):
-            raise AnsibleOptionsError("connect_host and connect_token are required together")
-
-        op = OnePass(subdomain, domain, username, secret_key, master_password, service_account_token, account_id, connect_host, connect_token)
+        op = OnePass(
+            subdomain=subdomain,
+            domain=domain,
+            username=username,
+            secret_key=secret_key,
+            master_password=master_password,
+            service_account_token=service_account_token,
+            account_id=account_id,
+            connect_host=connect_host,
+            connect_token=connect_token,
+        )
         op.assert_logged_in()
 
         values = []