ansible_play_batch (#17779)

* ansible_play_batch

* added version added

3 files changed, 10 insertions, 1 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2e1f478a6a..1386d7d73b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -249,6 +249,7 @@ Ansible Changes By Release
 * Only check if the default ssh client supports ControlPersist once instead of once for each host + task combination.
 * Fix a problem with the pip module updating the python pip package itself.
 * ansible_play_hosts is a new magic variable to provide a list of hosts in scope for the current play. Unlike play_hosts it is not subject to the 'serial' keyword.
+* ansible_play_batch is a new magic variable meant to substitute the current play_hosts.
 
 ###For custom front ends using the API:
 * ansible.parsing.vault:
@@ -481,6 +482,7 @@ Notice given that the following will be removed in Ansible 2.4:
 * Deprecated the use of "bare" variables in loops (ie. `with_items: foo`, where `foo` is a variable).
   The full jinja2 variable syntax of `{{foo}}` should always be used instead. This warning will be removed
   completely in 2.3, after which time it will be an error.
+* play_hosts magic variable, use ansible_play_batch or ansible_play_hosts instead.
 
 ## 2.0.2 "Over the Hills and Far Away"
 
diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst
index e5c310f2ce..cce72edd5e 100644
--- a/docsite/rst/playbooks_variables.rst
+++ b/docsite/rst/playbooks_variables.rst
@@ -673,8 +673,14 @@ be useful for when you don't want to rely on the discovered hostname ``ansible_h
 reasons.  If you have a long FQDN, ``inventory_hostname_short`` also contains the part up to the first
 period, without the rest of the domain.
 
+``play_hosts`` has been deprecated in 2.2, it was the same as the new ``ansible_play_batch`` variable.
+
+.. versionadded:: 2.2
 ``ansible_play_hosts`` is the full list of all hosts still active in the current play.
-``play_hosts`` is available as a list of hostnames that are in scope for the current 'batch' of the play. The batch size is defined by ``serial``, when not set it is equivalent to the whole play (making it the same as ``ansible_play_hosts``).
+.. versionadded:: 2.2
+``ansible_play_batch`` is available as a list of hostnames that are in scope for the current 'batch' of the play. The batch size is defined by ``serial``, when not set it is equivalent to the whole play (making it the same as ``ansible_play_hosts``).
+
+
 These vars may be useful for filling out templates with multiple hostnames or for injecting the list into the rules for a load balancer.
 
 Don't worry about any of this unless you think you need it.  You'll know when you do.
diff --git a/lib/ansible/vars/__init__.py b/lib/ansible/vars/__init__.py
index 1765037218..b50fb22712 100644
--- a/lib/ansible/vars/__init__.py
+++ b/lib/ansible/vars/__init__.py
@@ -414,6 +414,7 @@ class VariableManager:
                 #             however this would take work in the templating engine, so for now
                 #             we'll add both so we can give users something transitional to use
                 variables['play_hosts'] = [x.name for x in self._inventory.get_hosts()]
+                variables['ansible_play_batch'] = [x.name for x in self._inventory.get_hosts()]
                 variables['ansible_play_hosts'] = [x.name for x in self._inventory.get_hosts(pattern=play.hosts or 'all', ignore_restrictions=True)]
 
         # the 'omit' value alows params to be left out if the variable they are based on is undefined