package Package

package Package

Roles in this namespace are meant to enable users to install packages using package managers such as Aptitude or Pip in Debian distributions.

aptitude Module

Roles in this namespace are meant to provision packages installed via the Aptitude package manager for Debian distributions.

class provy.more.debian.package.aptitude.AptitudeRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides package management operations with Aptitude within Debian distributions.

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.ensure_package_installed('nginx')
aptitude = 'aptitude'
ensure_aptitude_source(source_string)[source]

Ensures that the specified repository is in aptitude’s list of repositories.

Parameters:source_string (str) – Repository string.
Returns:Whether the repository had to be added or not.
Return type:bool

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.ensure_aptitude_source('deb http://www.las.ic.unicamp.br/pub/ubuntu/ natty main restricted')
ensure_gpg_key(url)[source]

Ensures that the specified gpg key is imported into aptitude.

Parameters:url (str) – URL of the gpg key file.

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.ensure_gpg_key('http://some.url.com/to/key.gpg')
ensure_package_installed(package_name, stdout=False, sudo=True)[source]

Ensures that the given package is installed via aptitude.

Parameters:
  • package_name (str) – Name of the package to install.
  • stdout (bool) – Indicates whether install progress should be shown to stdout. Defaults to False.
  • sudo (bool) – Indicates whether the package should be installed with the super user. Defaults to True.
Returns:

Whether the package had to be installed or not.
Return type:

bool
Raise:

provy.more.debian.PackageNotFound if the package is not found in the repositories.

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.ensure_package_installed('nginx')
ensure_up_to_date()[source]

Makes sure aptitude’s repository is updated if it hasn’t been updated in the last 30 minutes.

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.ensure_up_to_date()
force_update()[source]

Forces an update to aptitude’s repository.

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.force_update()
get_last_update_date()[source]

Returns the date in the update_date_file().

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            last_update = role.get_last_update_date()
has_source(source_string)[source]

Returns True if the specified repository is in aptitude’s list of repositories.

Parameters:source_string (str) – Repository string.
Returns:Whether the repository string is present or not.
Return type:bool

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            if role.has_source('deb http://www.las.ic.unicamp.br/pub/ubuntu/ natty main restricted'):
                pass
is_package_installed(package_name)[source]

Returns True if the given package is installed via aptitude, False otherwise.

Parameters:package_name (str) – Name of the package to verify.
Returns:Whether the package is installed or not.
Return type:bool

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            if role.is_package_installed('nginx'):
                pass
key = 'aptitude-up-to-date'
package_exists(package)[source]

Checks if the given package exists.

Parameters:package (str) – Name of the package to check.
Returns:Whether the package exists or not.
Return type:bool

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.package_exists('nginx') # True
provision()[source]

Installs Aptitude dependencies. This method should be called upon if overriden in base classes, or Aptitude won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(AptitudeRole) # does not need to be called if using with block.
store_update_date()[source]

Updates the date in the update_date_file().

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            role.store_update_date()
time_format = '%d-%m-%y %H:%M:%S'
update_date_file

Returns the path for the file that contains the last update date to aptitudes’s list of packages.

Returns:The path to the file.
Return type:str

Example:

from provy.core import Role
from provy.more.debian import AptitudeRole

class MySampleRole(Role):
    def provision(self):
        with self.using(AptitudeRole) as role:
            file_path = role.update_date_file
exception provy.more.debian.package.aptitude.PackageNotFound[source]

Bases: exceptions.Exception

Should be raised when a package doesn’t exist.

gem Module

Roles in this namespace are meant to provision packages installed via the gem package manager for Debian distributions.

class provy.more.debian.package.gem.GemRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides package management operations with gem within Debian distributions.

If you wish to use a different Ruby version other than the default in provy, remember to set version and priority in the RubyRole class.

Example:

from provy.core import Role
from provy.more.debian import GemRole

class MySampleRole(Role):
    def provision(self):
        with self.using(GemRole) as role:
            role.ensure_package_installed('activerecord', version='3.1.1')
ensure_package_installed(package_name, version=None)[source]

Makes sure the package is installed with the specified version (latest if None specified). This method does not verify and upgrade the package on subsequent provisions, though.

Parameters:
  • package_name (str) – Name of the package to install.
  • version (str) – If specified, installs this version of the package. Installs latest version otherwise.

Example::

from provy.core import Role
from provy.more.debian import GemRole

class MySampleRole(Role):
    def provision(self):
        with self.using(GemRole) as role:
            role.ensure_package_installed('activerecord', version='3.1.1')
is_package_installed(package_name, version=None)[source]

Returns True if the given package is installed via gem in the remote server, False otherwise.

Parameters:
  • package_name (str) – Name of the package to verify.
  • version (str) – Version to check for. Defaults to None, which makes it check for any version.
Returns:

Wheter the package is installed or not.
Return type:

bool

Example:

from provy.core import Role
from provy.more.debian import GemRole

class MySampleRole(Role):
    def provision(self):
        with self.using(GemRole) as role:
            if role.is_package_installed('activerecord', version='3.1.1'):
                pass
provision()[source]

Installs gem dependencies. This method should be called upon if overriden in base classes, or gem won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import PipRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(PipRole) # does not need to be called if using with block.
use_sudo = True

npm Module

Roles in this namespace are meant to provision packages installed via the NPM package manager for Debian distributions.

class provy.more.debian.package.npm.NPMRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides package management operations with NPM within Debian distributions.

Example:

from provy.core import Role
from provy.more.debian import NPMRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NPMRole) as role:
            role.ensure_package_installed('socket.io', '0.6.17')
ensure_package_installed(package_name, version=None, stdout=False, sudo=True)[source]

Ensures that the given package in the given version is installed via NPM.

Parameters:
  • package_name (str) – Name of the package to install.
  • version (str) – If specified, installs this version of the package. Installs latest version otherwise.
  • stdout (bool) – Indicates whether install progress should be shown to stdout. Defaults to False.
  • sudo (bool) – Indicates whether the package should be installed with the super user. Defaults to True.
Returns:

Whether the package had to be installed or not.
Return type:

bool

Example:

from provy.core import Role
from provy.more.debian import NPMRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NPMRole) as role:
            role.ensure_package_installed('socket.io', '0.6.17')
is_package_installed(package_name, version=None)[source]

Returns True if the given package is installed via NPM, False otherwise.

Parameters:
  • package_name (str) – Name of the package to verify
  • version (str) – Version to check for. Defaults to None, which makes it check for any version.
Returns:

Whether the package is installed or not.
Return type:

bool

Example:

from provy.core import Role
from provy.more.debian import NPMRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NPMRole) as role:
            if role.is_package_installed('socket.io', '0.6.17'):
                pass
key = 'npm-up-to-date'
provision()[source]

Installs NPM. This method should be called upon if overriden in base classes, or NPM won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import NPMRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(NPMRole) # no need to call this if using with block.
time_format = '%d-%m-%y %H:%M:%S'

pip Module

Roles in this namespace are meant to provision packages installed via the PIP package manager for Debian distributions.

class provy.more.debian.package.pip.PipRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides package management operations with PIP within Debian distributions.

By default, all commands executed with this role will be executed with sudo, unless you set a different user (refer to the set_user() method below).

You can also change the class parameters below in the class directly to have a global effect (use carefully!).

Variables:
  • use_sudo – If False, the packages will be installed as normal user. Defaults to True.
  • user – User through which the packages will be installed. Defaults to None, which means that, using together with the default use_sudo, will install packages globally.

Example:

from provy.core import Role
from provy.more.debian import PipRole

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            role.ensure_package_installed('django', version='1.1.1')
ensure_package_installed(package_name, version=None)[source]

Makes sure the package is installed with the specified version (latest if None specified). This method does not verify and upgrade the package on subsequent provisions, though. Use ensure_package_up_to_date() for this purpose instead.

Parameters:
  • package_name (str) – Name of the package to install.
  • version (str) – If specified, installs this version of the package. Installs latest version otherwise. You can use >= or <= before version number to ensure package version.
Returns:

Whether the package had to be installed or not.
Return type:

bool

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            role.ensure_package_installed('django', version='1.1.1')
ensure_package_up_to_date(package_name)[source]

Makes sure the package is installed and up-to-date with the latest version. This method verifies if there is a newer version for this package every time the server is provisioned. If a new version is found, it is installed.

Parameters:package_name (str) – Name of the package to install.

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            role.ensure_package_is_up_to_date('django')
ensure_requirements_installed(requirements_file_name)[source]

Makes sure the requirements file provided is installed.

Parameters:requirements_file_name (str) – Path to the requirements file (can be provided as absolute path or relative to the directory where provy is run from).

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            role.ensure_requirements_installed('/path/to/requirements.txt')
extract_package_data_from_input(input_line)[source]
get_package_latest_version(package_name)[source]

Returns the latest available version of the package at the Python Package Index. If package is not available, returns None.

Parameters:package_name (str) – Name of the package to verify
Returns:The package version.
Return type:str

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            version = role.get_package_remote_version('django')
            latest = role.get_package_latest_version('django')
            if version != latest:
                pass
                # this check is not needed if you use ensure_package_up_to_date.
get_package_remote_version(package_name)[source]

Returns the version of the package currently installed via PIP in the remote server. If package is not installed, returns None.

Parameters:package_name (str) – Name of the package to verify
Returns:The package version.
Return type:str

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            version = role.get_package_remote_version('django')
            if version and version == '1.1.1':
                pass
is_package_installed(package_name, version=None)[source]

Returns True if the given package is installed via pip in the remote server, False otherwise.

Parameters:
  • package_name (str) – Name of the package to verify
  • version (str) – Version to check for. Defaults to None, which makes it check for any version.
Returns:

Whether the package is installed or not.
Return type:

bool

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            if role.is_package_installed('django', version='1.1.1'):
                pass
package_can_be_updated(package_name)[source]

Returns True if there is an update for the given package in the Python Package Index, False otherwise.

Parameters:package_name (str) – Name of the package to verify
Returns:Whether the package can be updated.
Return type:bool

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            if role.package_can_be_updated('django'):
                pass
                # this check is not needed if you use ensure_package_up_to_date.
provision()[source]

Installs pip dependencies. This method should be called upon if overriden in base classes, or PIP won’t work properly in the remote server.

Example:

class MySampleRole(Role):
    def provision(self):
        self.provision_role(PipRole) # does not need to be called if using with block.
set_sudo()[source]

Prepares the pip role instance to run its commands with sudo; This is useful when you had previously set a user, and want it to run back as sudo.

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            role.ensure_package_installed('django') # runs as sudo
            role.set_user('johndoe')
            role.ensure_package_installed('django') # runs as "johndoe" user
            role.set_sudo()
            role.ensure_package_installed('django') # runs as sudo
set_user(user)[source]

Prepares the pip role instance to run its commands as a specific user.

Parameters:user (str) – The username with which the role should run its commands.

Example:

class MySampleRole(Role):
    def provision(self):
        with self.using(PipRole) as role:
            role.ensure_package_installed('django') # runs as sudo
            role.set_user('johndoe')
            role.ensure_package_installed('django') # runs as "johndoe" user
use_sudo = True
user = None

virtualenv Module

Roles in this namespace are meant to provide virtual environments and run commands inside a virtualenv, for Debian distributions.

class provy.more.debian.package.virtualenv.VirtualenvRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides virtualenv management. It also provides virtualenvwrapper provisioning, although it’s not internally used in this role.

When using the object as a context manager (that is, using a with block) it will make sure that the virtual environment is created and that the commands that run inside it run within this same virtual environment (which affects, for example, the python and pip commands).

If the virtual environment already exists, it just bypasses the creation procedure.

Parameters:
  • env_name (str) – Name of the virtual environment to be created and to keep activated when running commands inside the context manager.
  • system_site_packages (bool) – If True, will include system-wide site-packages in the virtual environment. Defaults to False.
Variables:
  • base_directory – (str) Directory where the virtual environment subdirectory will be put at. For example, if you set it as “/home/johndoe/my_envs”, and use venv(“some_env”), it will create a virtual environment at “/home/johndoe/my_envs/some_env”. Defaults to $HOME/.virtualenvs (or venv.user /.virtualenvs, if the user is explicitly set - see below -).
  • user – (str) The user with which the virtual environment should be created. Defaults to the context user.

Example:

from provy.core import Role
from provy.more.debian import VirtualenvRole

class MySampleRole(Role):
    def provision(self):

        # this example uses the defaults provided
        with self.using(PipRole) as pip, self.using(VirtualenvRole) as venv, venv('fancylib'):
            pip.ensure_package_installed('django')

        # this is when you want to set a different base virtualenv directory and user, and include the system-wide site-packages.
        with self.using(PipRole) as pip, self.using(VirtualenvRole) as venv:
            venv.base_directory = '/home/johndoe/Envs'
            venv.user = 'johndoe'
            with venv('fancylib2', system_site_packages=True):
                pip.ensure_package_installed('tornado')
create_env(env_name, system_site_packages=False)[source]

Creates a virtual environment.

Parameters:
  • env_name (str) – Name of the virtual environment to be created.
  • system_site_packages (bool) – If True, will include system-wide site-packages in the virtual environment. Defaults to False.

Examples:

from provy.core import Role
from provy.more.debian import VirtualenvRole

class MySampleRole(Role):
    def provision(self):
        with self.using(VirtualenvRole) as venv:
            env_dir = venv.create_env('fancylib') # will return the directory where the virtual environment was created
env_dir(env_name)[source]

Gets the virtual environment directory for a given environment name.

Please note that this doesn’t check if the env actually exists.

Parameters:env_name (str) – Name of the virtual environment to be used to build a directory string.
Returns:The directory to be used.
Return type:str

Example:

from provy.core import Role
from provy.more.debian import VirtualenvRole

class MySampleRole(Role):
    def provision(self):
        with self.using(VirtualenvRole) as venv, venv('fancylib'):
            venv.env_dir('fancylib')
env_exists(env_name)[source]

Checks if a virtual environment exists.

Parameters:env_name (str) – Name of the virtual environment to be checked.
Returns:Whether the virtual environment exists.
Return type:bool

Example:

from provy.core import Role
from provy.more.debian import VirtualenvRole

class MySampleRole(Role):
    def provision(self):
        with self.using(VirtualenvRole) as venv:
            venv.env_exists('fancylib') # True or False
get_base_directory()[source]

Gets the base directory that will be used to create the virtual environment.

By default, it returns a subdir under the current venv user home and ”.virtualenvs”. If you wish to change the directory where it gets created, just set role.base_directory

Example:

from provy.core import Role
from provy.more.debian import VirtualenvRole

class MySampleRole(Role):
    def provision(self):
        with self.using(VirtualenvRole) as venv:
            venv.user = 'johndoe'
            venv.get_base_directory() # "/home/johndoe/.virtualenvs"
            venv.base_directory = '/home/johndoe/Envs'
            venv.get_base_directory() # "/home/johndoe/Envs"
provision()[source]

Installs virtualenv and virtualenvwrapper, and their dependencies. This method should be called upon if overriden in base classes, or virtualenv won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import VirtualenvRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(VirtualenvRole) # does not need to be called if using with block.