From a129499cf48a859fefe5f289d107c6a8bfc535dd Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 17 Oct 2019 22:02:39 +0200 Subject: [PATCH] Improve module return values (#63541) * Remove lists from contains:, fix types, some more details. * Adjust types. * Add new type. * Re-add meraki_mx_l7_firewall docs at right indentation level. --- .../modules/cloud/alicloud/ali_instance.py | 22 +-- .../cloud/alicloud/ali_instance_info.py | 22 +-- .../modules/cloud/amazon/aws_codebuild.py | 4 +- .../modules/cloud/amazon/aws_codecommit.py | 4 +- .../modules/cloud/amazon/aws_secret.py | 2 +- .../modules/cloud/amazon/ec2_instance.py | 128 +++++++++--------- .../modules/cloud/amazon/ec2_instance_info.py | 128 +++++++++--------- .../modules/cloud/amazon/ec2_vpc_nacl_info.py | 4 +- .../modules/cloud/amazon/ec2_vpc_vpn_info.py | 7 +- .../modules/cloud/openstack/os_coe_cluster.py | 2 +- lib/ansible/modules/cloud/ovirt/ovirt_auth.py | 2 +- .../modules/cloud/vmware/vcenter_folder.py | 8 +- lib/ansible/modules/files/stat.py | 4 +- .../network/meraki/meraki_mx_l7_firewall.py | 20 +-- lib/ansible/modules/windows/win_updates.py | 2 +- 15 files changed, 184 insertions(+), 175 deletions(-) diff --git a/lib/ansible/modules/cloud/alicloud/ali_instance.py b/lib/ansible/modules/cloud/alicloud/ali_instance.py index d6a115b76c9..444d92da70c 100644 --- a/lib/ansible/modules/cloud/alicloud/ali_instance.py +++ b/lib/ansible/modules/cloud/alicloud/ali_instance.py @@ -468,18 +468,18 @@ instances: security_groups: description: One or more security groups for the instance. returned: always - type: complex + type: list of complex contains: - - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-0123456 - - group_name: - description: The name of the security group. - returned: always - type: str - sample: my-security-group + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-0123456 + group_name: + description: The name of the security group. + returned: always + type: str + sample: my-security-group status: description: The current status of the instance. returned: always diff --git a/lib/ansible/modules/cloud/alicloud/ali_instance_info.py b/lib/ansible/modules/cloud/alicloud/ali_instance_info.py index 886bf5e7155..bb96aada8e3 100644 --- a/lib/ansible/modules/cloud/alicloud/ali_instance_info.py +++ b/lib/ansible/modules/cloud/alicloud/ali_instance_info.py @@ -309,18 +309,18 @@ instances: security_groups: description: One or more security groups for the instance. returned: always - type: complex + type: list of complex contains: - - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-0123456 - - group_name: - description: The name of the security group. - returned: always - type: str - sample: my-security-group + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-0123456 + group_name: + description: The name of the security group. + returned: always + type: str + sample: my-security-group status: description: The current status of the instance. returned: always diff --git a/lib/ansible/modules/cloud/amazon/aws_codebuild.py b/lib/ansible/modules/cloud/amazon/aws_codebuild.py index e6e4a4e02b6..098343a9483 100644 --- a/lib/ansible/modules/cloud/amazon/aws_codebuild.py +++ b/lib/ansible/modules/cloud/amazon/aws_codebuild.py @@ -257,11 +257,11 @@ project: cache: description: Cache settings for the build project. returned: when configured - type: complex + type: dict environment: description: Environment settings for the build returned: always - type: complex + type: dict service_role: description: IAM role to be used during build to access other AWS services. returned: always diff --git a/lib/ansible/modules/cloud/amazon/aws_codecommit.py b/lib/ansible/modules/cloud/amazon/aws_codecommit.py index ca674e4d5a9..24ebffa6971 100644 --- a/lib/ansible/modules/cloud/amazon/aws_codecommit.py +++ b/lib/ansible/modules/cloud/amazon/aws_codecommit.py @@ -73,7 +73,7 @@ repository_metadata: creation_date: description: "The date and time the repository was created, in timestamp format." returned: when state is present - type: datetime + type: str sample: "2018-10-16T13:21:41.261000+09:00" last_modified_date: description: "The date and time the repository was last modified, in timestamp format." @@ -104,7 +104,7 @@ response_metadata: http_headers: description: "http headers of http response" returned: always - type: complex + type: dict http_status_code: description: "http status code of http response" returned: always diff --git a/lib/ansible/modules/cloud/amazon/aws_secret.py b/lib/ansible/modules/cloud/amazon/aws_secret.py index 96da5c56828..41fda7db710 100644 --- a/lib/ansible/modules/cloud/amazon/aws_secret.py +++ b/lib/ansible/modules/cloud/amazon/aws_secret.py @@ -119,7 +119,7 @@ secret: version_ids_to_stages: description: Provide the secret version ids and the associated secret stage. returned: always - type: complex + type: dict sample: { "dc1ed59b-6d8e-4450-8b41-536dfe4600a9": [ "AWSCURRENT" ] } ''' diff --git a/lib/ansible/modules/cloud/amazon/ec2_instance.py b/lib/ansible/modules/cloud/amazon/ec2_instance.py index 57532ecc7bd..591c13e9e7b 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_instance.py +++ b/lib/ansible/modules/cloud/amazon/ec2_instance.py @@ -477,18 +477,18 @@ instances: groups: description: One or more security groups. returned: always - type: complex + type: list of complex contains: - - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-abcdef12 - group_name: - description: The name of the security group. - returned: always - type: str - sample: mygroup + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-abcdef12 + group_name: + description: The name of the security group. + returned: always + type: str + sample: mygroup ipv6_addresses: description: One or more IPv6 addresses associated with the network interface. returned: always @@ -522,38 +522,38 @@ instances: private_ip_addresses: description: The private IPv4 addresses associated with the network interface. returned: always - type: complex + type: list of complex contains: - - association: - description: The association information for an Elastic IP address (IPv4) associated with the network interface. - returned: always - type: complex - contains: - ip_owner_id: - description: The ID of the owner of the Elastic IP address. - returned: always - type: str - sample: amazon - public_dns_name: - description: The public DNS name. - returned: always - type: str - sample: "" - public_ip: - description: The public IP address or Elastic IP address bound to the network interface. - returned: always - type: str - sample: 1.2.3.4 - primary: - description: Indicates whether this IPv4 address is the primary private IP address of the network interface. - returned: always - type: bool - sample: true - private_ip_address: - description: The private IPv4 address of the network interface. - returned: always - type: str - sample: 10.0.0.1 + association: + description: The association information for an Elastic IP address (IPv4) associated with the network interface. + returned: always + type: complex + contains: + ip_owner_id: + description: The ID of the owner of the Elastic IP address. + returned: always + type: str + sample: amazon + public_dns_name: + description: The public DNS name. + returned: always + type: str + sample: "" + public_ip: + description: The public IP address or Elastic IP address bound to the network interface. + returned: always + type: str + sample: 1.2.3.4 + primary: + description: Indicates whether this IPv4 address is the primary private IP address of the network interface. + returned: always + type: bool + sample: true + private_ip_address: + description: The private IPv4 address of the network interface. + returned: always + type: str + sample: 10.0.0.1 source_dest_check: description: Indicates whether source/destination checking is enabled. returned: always @@ -607,18 +607,18 @@ instances: product_codes: description: One or more product codes. returned: always - type: complex + type: list of complex contains: - - product_code_id: - description: The product code. - returned: always - type: str - sample: aw0evgkw8ef3n2498gndfgasdfsd5cce - product_code_type: - description: The type of product code. - returned: always - type: str - sample: marketplace + product_code_id: + description: The product code. + returned: always + type: str + sample: aw0evgkw8ef3n2498gndfgasdfsd5cce + product_code_type: + description: The type of product code. + returned: always + type: str + sample: marketplace public_dns_name: description: The public DNS name assigned to the instance. returned: always @@ -642,18 +642,18 @@ instances: security_groups: description: One or more security groups for the instance. returned: always - type: complex + type: list of complex contains: - - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-0123456 - - group_name: - description: The name of the security group. - returned: always - type: str - sample: my-security-group + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-0123456 + group_name: + description: The name of the security group. + returned: always + type: str + sample: my-security-group network.source_dest_check: description: Indicates whether source/destination checking is enabled. returned: always diff --git a/lib/ansible/modules/cloud/amazon/ec2_instance_info.py b/lib/ansible/modules/cloud/amazon/ec2_instance_info.py index 46bcb4767ff..0a41183e9da 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_instance_info.py +++ b/lib/ansible/modules/cloud/amazon/ec2_instance_info.py @@ -263,18 +263,18 @@ instances: groups: description: One or more security groups. returned: always - type: complex + type: list of complex contains: - - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-abcdef12 - group_name: - description: The name of the security group. - returned: always - type: str - sample: mygroup + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-abcdef12 + group_name: + description: The name of the security group. + returned: always + type: str + sample: mygroup ipv6_addresses: description: One or more IPv6 addresses associated with the network interface. returned: always @@ -308,38 +308,38 @@ instances: private_ip_addresses: description: The private IPv4 addresses associated with the network interface. returned: always - type: complex + type: list of complex contains: - - association: - description: The association information for an Elastic IP address (IPv4) associated with the network interface. - returned: always - type: complex - contains: - ip_owner_id: - description: The ID of the owner of the Elastic IP address. - returned: always - type: str - sample: amazon - public_dns_name: - description: The public DNS name. - returned: always - type: str - sample: "" - public_ip: - description: The public IP address or Elastic IP address bound to the network interface. - returned: always - type: str - sample: 1.2.3.4 - primary: - description: Indicates whether this IPv4 address is the primary private IP address of the network interface. - returned: always - type: bool - sample: true - private_ip_address: - description: The private IPv4 address of the network interface. - returned: always - type: str - sample: 10.0.0.1 + association: + description: The association information for an Elastic IP address (IPv4) associated with the network interface. + returned: always + type: complex + contains: + ip_owner_id: + description: The ID of the owner of the Elastic IP address. + returned: always + type: str + sample: amazon + public_dns_name: + description: The public DNS name. + returned: always + type: str + sample: "" + public_ip: + description: The public IP address or Elastic IP address bound to the network interface. + returned: always + type: str + sample: 1.2.3.4 + primary: + description: Indicates whether this IPv4 address is the primary private IP address of the network interface. + returned: always + type: bool + sample: true + private_ip_address: + description: The private IPv4 address of the network interface. + returned: always + type: str + sample: 10.0.0.1 source_dest_check: description: Indicates whether source/destination checking is enabled. returned: always @@ -393,18 +393,18 @@ instances: product_codes: description: One or more product codes. returned: always - type: complex + type: list of complex contains: - - product_code_id: - description: The product code. - returned: always - type: str - sample: aw0evgkw8ef3n2498gndfgasdfsd5cce - product_code_type: - description: The type of product code. - returned: always - type: str - sample: marketplace + product_code_id: + description: The product code. + returned: always + type: str + sample: aw0evgkw8ef3n2498gndfgasdfsd5cce + product_code_type: + description: The type of product code. + returned: always + type: str + sample: marketplace public_dns_name: description: The public DNS name assigned to the instance. returned: always @@ -428,18 +428,18 @@ instances: security_groups: description: One or more security groups for the instance. returned: always - type: complex + type: list of complex contains: - - group_id: - description: The ID of the security group. - returned: always - type: str - sample: sg-0123456 - - group_name: - description: The name of the security group. - returned: always - type: str - sample: my-security-group + group_id: + description: The ID of the security group. + returned: always + type: str + sample: sg-0123456 + group_name: + description: The name of the security group. + returned: always + type: str + sample: my-security-group source_dest_check: description: Indicates whether source/destination checking is enabled. returned: always diff --git a/lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_info.py b/lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_info.py index 51cdbc99a44..e6aeb86af04 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_info.py +++ b/lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_info.py @@ -91,14 +91,14 @@ nacls: ingress: description: - A list of NACL ingress rules with the following format. - - [rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to] + - "C([rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to])" returned: always type: list of list sample: [[100, 'tcp', 'allow', '0.0.0.0/0', null, null, 22, 22]] egress: description: - A list of NACL egress rules with the following format. - - [rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to] + - "C([rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to])" returned: always type: list of list sample: [[100, 'all', 'allow', '0.0.0.0/0', null, null, null, null]] diff --git a/lib/ansible/modules/cloud/amazon/ec2_vpc_vpn_info.py b/lib/ansible/modules/cloud/amazon/ec2_vpc_vpn_info.py index 9974ec342ad..1a61eb10e6b 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_vpc_vpn_info.py +++ b/lib/ansible/modules/cloud/amazon/ec2_vpc_vpn_info.py @@ -123,7 +123,7 @@ vpn_connections: last_status_change: description: The date and time of the last change in status. returned: always - type: datetime + type: str sample: "2018-02-09T14:35:27+00:00" outside_ip_address: description: The Internet-routable IP address of the virtual private gateway's outside interface. @@ -140,6 +140,11 @@ vpn_connections: returned: always type: str sample: IPSEC IS DOWN + certificate_arn: + description: The Amazon Resource Name of the virtual private gateway tunnel endpoint certificate. + returned: when a private certificate is used for authentication + type: str + sample: "arn:aws:acm:us-east-1:123456789101:certificate/c544d8ce-20b8-4fff-98b0-example" vpn_connection_id: description: The ID of the VPN connection. returned: always diff --git a/lib/ansible/modules/cloud/openstack/os_coe_cluster.py b/lib/ansible/modules/cloud/openstack/os_coe_cluster.py index ad53bb5aada..26e3a18aeb7 100644 --- a/lib/ansible/modules/cloud/openstack/os_coe_cluster.py +++ b/lib/ansible/modules/cloud/openstack/os_coe_cluster.py @@ -105,7 +105,7 @@ cluster: created_at: description: - The time in UTC at which the cluster is created - type: datetime + type: str sample: "2018-08-16T10:29:45+00:00" create_timeout: description: diff --git a/lib/ansible/modules/cloud/ovirt/ovirt_auth.py b/lib/ansible/modules/cloud/ovirt/ovirt_auth.py index ad4b3356bea..c8f7407b24b 100644 --- a/lib/ansible/modules/cloud/ovirt/ovirt_auth.py +++ b/lib/ansible/modules/cloud/ovirt/ovirt_auth.py @@ -169,7 +169,7 @@ ovirt_auth: ca_file: description: CA file, which is used to verify SSL/TLS connection. returned: success - type: path + type: str sample: "ca.pem" insecure: description: Flag indicating if insecure connection is used. diff --git a/lib/ansible/modules/cloud/vmware/vcenter_folder.py b/lib/ansible/modules/cloud/vmware/vcenter_folder.py index 004fd39af7d..d6fc2e42342 100644 --- a/lib/ansible/modules/cloud/vmware/vcenter_folder.py +++ b/lib/ansible/modules/cloud/vmware/vcenter_folder.py @@ -132,8 +132,12 @@ result: returned: On success type: complex contains: - path: the full path of the new folder - msg: string stating about result + path: + description: the full path of the new folder + type: str + msg: + description: string stating about result + type: str ''' try: diff --git a/lib/ansible/modules/files/stat.py b/lib/ansible/modules/files/stat.py index a8557eb8164..31bd132699f 100644 --- a/lib/ansible/modules/files/stat.py +++ b/lib/ansible/modules/files/stat.py @@ -143,9 +143,9 @@ stat: type: str sample: '/path/to/file' mode: - description: Unix permissions of the file in octal + description: Unix permissions of the file in octal representation as a string returned: success, path exists and user can read stats - type: octal + type: str sample: 1755 isdir: description: Tells you if the path is a directory diff --git a/lib/ansible/modules/network/meraki/meraki_mx_l7_firewall.py b/lib/ansible/modules/network/meraki/meraki_mx_l7_firewall.py index 8ba9be97ff5..48dfce4e9df 100644 --- a/lib/ansible/modules/network/meraki/meraki_mx_l7_firewall.py +++ b/lib/ansible/modules/network/meraki/meraki_mx_l7_firewall.py @@ -247,16 +247,16 @@ data: returned: success type: str sample: meraki:layer7/application/4 - id: - description: URI of application category. - returned: success - type: string - sample: Email - name: - description: Descriptive name of application category. - returned: success - type: string - sample: layer7/category/1 + id: + description: URI of application category. + returned: success + type: string + sample: Email + name: + description: Descriptive name of application category. + returned: success + type: string + sample: layer7/category/1 ''' import copy diff --git a/lib/ansible/modules/windows/win_updates.py b/lib/ansible/modules/windows/win_updates.py index 511c2e2e490..d2f2419f3a9 100644 --- a/lib/ansible/modules/windows/win_updates.py +++ b/lib/ansible/modules/windows/win_updates.py @@ -221,7 +221,7 @@ updates: id: description: Internal Windows Update GUID. returned: always - type: str (guid) + type: str sample: "fb95c1c8-de23-4089-ae29-fd3351d55421" installed: description: Was the update successfully installed.