I guess this is left over from testing

The apt module check if a packag eis valid by loking in the cache, checking only for
full name, while it should also check that the name is not just provided.
Fix https://github.com/ansible/ansible/issues/5177

Revert "No longer need to reference 'version_added' in docs for these, as this was quite a while ago."

This reverts commit ff0a41d4.

This will allow specifying dpkg options as a string passed over to apt
command. dpkg_options expects a comma-separated string of options to be
passed as dpkg options which will be further expanded. For example
dpkg_options='force-confdef,force-confold' will end up as
-o \"Dpkg::Options::=--force-confold\" when passed to apt
Example usage would be:
-m apt -u ubuntu -s \
 -a "upgrade=dist update_cache=yes dpkg_options='force-confold'"
or
apt: upgrade=dist update_cache=yes dpkg_options='force-confold'

For values that are booleans in the module doc, the value in the doc section should be a boolean or truthiness
is engaged in the documentation formatting.  This fixes the update_cache default in the docs to the proper
value of "no"

If one pins a package and does a 'apt-get dist-upgrade' then the
output looks like:

    # apt-get dist-upgrade
    Reading package lists... Done
    Building dependency tree
    Reading state information... Done
    Calculating upgrade... Done
    The following packages have been kept back:
      cassandra
    0 upgraded, 0 newly installed, 0 to remove and 1 not upgraded.

The check for any changes made should only be on the 'upgraded' and
'newly installed' values and not include the 'to remove' and 'not
upgraded' values.

Without this, this fails:

    - name: apt-get dist-upgrade
      action: apt upgrade=dist
      register: apt_get_contents

    - name: apt-get clean
      action: command apt-get clean
      when: apt_get_contents.stdout.find("0 upgraded") == -1

TASK: [apt-get clean] *********************************************************

fatal: [192.168.2.2] => error while evaluating conditional: {% if apt_get_contents.stdout.find("0 upgraded") == -1 %} True {% else %} False {% endif %}

FATAL: all hosts have already failed -- aborting

Packages which are half-installed are not adequately represented by
the .is_installed field of the apt.package.Package object. By using the
lower-level apt_pkg.Package object (which provides the .current_state
field), we can check for a partially-installed state more accurately.

Fixes #3421

Related to PR #3823

You can write a apt action like "- apt: pkg=apt*" with this package.

I'm seeing ansible hang when trying to remove a package, and the hung
process is `whiptail` like in #2763. It looks like we only use
`APT_ENVVARS` and `DPKG_OPTIONS` for the `apt` commands in install()
and upgrade(). This change uses them in remove() as well, which fixes
the hang.

Fix prev feature commit, Do not require aptitude to use apt commands in the apt module, only needed when upgrading.

A small error in the reuse of a variable caused packages to never get
purged. This commit fixes that.

Signed-off-by: martin f. krafft <madduck@madduck.net>

This reverts commit 4942a06b.

Conflicts:

	lib/ansible/runner/__init__.py

Older python-apt modules don't export Package.installed_files and there
seems to be no other way to figure out if a package is
removed-but-not-purged, so we just always assume it's purged.

Signed-off-by: martin f. krafft <madduck@madduck.net>

A package may be removed but not purged with APT. The only way to
identify this state is by looking at the list of installed files of
a package. Even if the package has no files installed, this list will be
non-empty until the package is removed:

  # python -c "import apt; c=apt.Cache(); c.update(); c.open(); p=c['ruby1.8']; print p, p.installed, p.installed_files"
  <Package: name:'ruby1.8' id:1425> None [u'']

  # dpkg --purge ruby1.8
  (Reading database ... 27904 files and directories currently installed.)
  Removing ruby1.8 ...
  Purging configuration files for ruby1.8 ...

  # python -c "import apt; c=apt.Cache(); c.update(); c.open(); p=c['ruby1.8']; print p, p.installed, p.installed_files"
  <Package: name:'ruby1.8' id:1425> None []

See http://bugs.debian.org/712749 too.

If a package is not marked installed but it still 'has_files', then it
should be processed if the request is to purge it.

Signed-off-by: martin f. krafft <madduck@madduck.net>

A small error in the reuse of a variable caused packages to never get
purged. This commit fixes that.

Signed-off-by: martin f. krafft <madduck@madduck.net>

You can use apt module with update_cache and without specifying a
package. Update the docs to reflect this.

hardcoded lists in ansible code, just add WITH_ITEMS_USES_LIST in a
comment anywhere, and of course, support recieving params as list.

Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

I have something like:

  apt: pkg={{ item }} state=present
  with_items:
    - python-pysqlite2=2.6.3-*
    - python-paramiko=1.7.7.1-*

But due to the use of *'s in the version specifications, the apt ansible
module always reports changed: true. This patch fixes that.

tweak position & look of Requirements in rst
tweak APT's notes as per anhj's wish