appngizer package — appngizer 1.14.0 documentation

# appngizer package

## Submodules

## appngizer.client module

This module contains network clients which are used to communicate with an appNGizer instance.

Currently there is only an implementation of a `XMLClient`.

class `appngizer.client.` `Client`(url, sharedsecret)

  Bases: `object`

  Abstract class of an appNGizer client All further appNGizer clients will inherits from this class

  `REGEX_URL` = <_sre.SRE_Pattern object at 0x2f79d70>
  `request`(method, path, pdata=None)

    Sends request to appNGizer instance

    Parameters: | method (str) – HTTP method path (str) – url to appNGizer instance pdata (str) – data to send
    Returns: | `Client` object

  `validate_url`(url)

    Validates an url

    Parameters: | url (str) –
    Returns: | url as string if valide

class `appngizer.client.` `ClientNetwork`

  Bases: `object`

  appNGizer ClientNetwork class

  `request`(method, url, *args, **kwargs)

    Sends request to an appNGizer instance

    Parameters: | method (str) – HTTP method path (str) – url to appNGizer instance args (list) – additional args for `requests.Request` object kwargs (dict) – additional kwargs for `requests.Request`
    Returns: | `requests.Response` object

class `appngizer.client.` `Singleton`

  Bases: `type`

  Singleton class pattern to be used as metaclass for the `Client`.

class `appngizer.client.` `XMLClient`(url, sharedsecret)

  Bases: `appngizer.client.Client`

  appNGizer XML Client class

## appngizer.elements module

This module contains all appNG entities which currently can managed via an appNGizer instance:

- `Property`
- `Site`
- `Repository`
- `Application`
- `Package`
- `Subject`
- `Group`
- `Role`
- `Permission`
- `Database`
- `Platform` (only for reload)

To do this the `appngizer.elements.Element.xml` attribute helds the xml representation of the entity as an `lxml.etree.Element`.

CRUD methods on the entity are done via the `appngizer.client.XMLClient` where the `appngizer.elements.Element.xml` attribute is added to the data of the HTTP/S request if needed (usually in a PUT/POST request).

There also container elements where appNG entities of the same entity type are held. Currently they are only usable for read operations (f.e. read all available Sites) but can be the start point for further improvements like bulk operatios.

- `Properties`
- `Sites`
- `Repositories`
- `Applications`
- `Packages`
- `Subjects`
- `Groups`
- `Roles`
- `Permissions`
- `Databases`

To address an appNG entity we use their `appngizer.elements.Element.name` attribute, the entity type name `appngizer.elements.Element.TYPE` and their `appngizer.elements.Element.parents` attribute.

Examples:

- Site entity ‘an_appng_site’:

      Site('an_appng_site')

- Site application property ‘a_site_app_property’:

      Property('a_site_app_property', parents=[ Site('an_appng_site') , Application('an_app') ] )

class `appngizer.elements.` `Application`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage applications of an appNG instance

  `ALLOWED_FIELDS` = ['displayName', 'core', 'fileBased', 'hidden', 'version']
  `TYPE` = 'Application'
  `TYPE_C` = 'Applications'
  `assign`(site)

    Assigns application to a site

    Parameters: | site (elements.Site) – site object
    Returns: | xml of assigned application

  `assign_by_name`(site_name)

    Assigns application to a site via site_name

    Parameters: | site_name (elements.Site) – str
    Returns: | xml of assigned application

  `deassign`(site)

    Deassigns application from a site

    Parameters: | site (elements.Site) – site object
    Returns: | xml of deassigned application

  `deassign_by_name`(site_name)

    Deassigns application from a site via site_name

    Parameters: | site_name (elements.Site) – str
    Returns: | xml of deassigned application

  `deassign_from_all`()

    Deassigns application from all sites

    Returns: | bool (True if deassigned)

  `delete`()

    Deletes an application

    With additional check if application is assigned to any site before try to delete

    Returns: | bool (True if deleted)

  `is_assigned`(site=None)

    Checks if application is already assigned to a site

    Parameters: | site (elements.Site) – site object
    Returns: | bool (True if assigned, False if not assigned)

  `is_update_needed`(hidden=False, core=False, fileBased=False, displayName=None)

    Checks if update of application is needed

    Parameters: | hidden (bool) – hide application core (bool) – run as core application fileBased (bool) – store application filebased, otherwise databased displayName (str) – display name of application
    Returns: | bool (True if needed, False if not needed), xml of current application, xml of desired application

  `read`(site=None)

    Reads application from platform or if given from an assigned site

    Returns: | xml of application

  `update`(hidden=False, core=False, fileBased=False, displayName=None)

    Updates an application

    Parameters: | hidden (bool) – hide application core (bool) – run as core application fileBased (bool) – store application filebased, otherwise databased displayName (str) – display name of application
    Returns: | xml of updated application

class `appngizer.elements.` `Applications`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage application of an appNG instance

  `TYPE` = 'Application'
  `TYPE_C` = 'Applications'
  `read`(site=None)

    Reads applications global or if given from an assigned site

    Returns: | xml of the applications

class `appngizer.elements.` `Database`(name='', parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage databases of an appNG instance

  `ALLOWED_FIELDS` = ['user', 'password', 'driver', 'url']
  `TYPE` = 'Database'
  `TYPE_C` = 'Databases'
  `create`()

    Creates a database

    Raises: | errors.ElementError – create is not avaible for database

  `delete`()

    Delete a database

    Raises: | errors.ElementError – delete is not avaible for database

  `is_update_needed`(user, password, salt, driver, url)

    Checks if update of database is needed

    Parameters: | user (str) – database username password (str) – database password salt (str) – salt (appNGizer uses platform.sharedsecret) to generate bcrypt hash of password driver (str) – jdbc driver class url (str) – jdbc url of database
    Returns: | bool (True if needed, False if not needed), xml of current database, xml of desired database

  `update`(user, password, salt, driver, url)

    Updates a database

    Parameters: | user (str) – database username password (str) – database password salt (str) – salt (appNGizer uses platform.sharedsecret) to generate bcrypt hash of password driver (str) – jdbc driver class url (str) – jdbc url of database
    Returns: | xml of updated database

class `appngizer.elements.` `Databases`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage databases of an appNG instance

  `TYPE` = 'Database'
  `TYPE_C` = 'Databases'

class `appngizer.elements.` `Element`(name=None, parents=None, xml=None)

  Bases: `object`

  Abstract class of an appNGizer element All further appngizer elements will inherits from this class

  `ALLOWED_ATTRIBUTES` = []
  `ALLOWED_CDATA_FIELDS` = []
  `ALLOWED_CHILDS` = []
  `ALLOWED_FIELDS` = []
  `PRESERVED_FIELDS` = ['description', 'displayName']
  `TYPE` = 'Element'
  `TYPE_C` = 'Elements'
  `XPATH_DEFAULT_NAMESPACE` = {'a': 'http://www.appng.org/schema/appngizer'}
  `XSD_APPNGIZER_PATH` = '/var/lib/jenkins/workspace/python-appngizer_master-KL52RCXWYFCR4A2K5RTXRNXD3GQC7MMVVO5H26AOLOJOGUJOLX6Q/appngizer/appngizer.xsd'
  `delete`()

    Deletes entity

    Returns: | bool (True if successfully)

  `dump`(xml=None)

    Pretty print an etree as string

    Parameters: | xml (lxml.etree.Element) – xml to be pretty printed, if not given self.xml is used
    Returns: | string with pretty printed xml

  `exist`()

    Checks if entity already exist

    Returns: | bool (True if exist, False if not exist)

  `is_valide_xml`(xml=None)

    Validates a xml against the appNGizer xsd schema

    Parameters: | xml (lxml.etree.Element) – xml to be validated, if not given self.xml attribute is used
    Returns: | bool (True if validates)

  `read`()

    Reads entity

    Returns: | xml of the entity

class `appngizer.elements.` `Elements`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Element`

  Abstract class of an appNGizer container element All further appngizer container elements will inherits from this class

  Currently only reading is implemented.

  `delete`()

    Deletes an entity

    Raises: | error.ElementError – delete is not avaible for entity

  `exist`()

    Check if entity already exist

    Raises: | errors.ElementError – exist is not avaible for entity

  `is_update_needed`(**kwargs)

    Checks if update of entity is needed

    Raises: | error.ElementError – is_update_needed is not avaible for entity

class `appngizer.elements.` `Group`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage groups of an appNG instance.

  `ALLOWED_CHILDS` = ['roles']
  `ALLOWED_FIELDS` = ['description']
  `TYPE` = 'Group'
  `TYPE_C` = 'Groups'
  `create`(description=None, roles=[])

    Creates a new group

    Parameters: | description (str) – short description roles (list) – list of `Role` objects the group should be assigned to
    Returns: | xml of created group

  `is_update_needed`(description=None, roles=[])

    Checks if update of group is needed

    Parameters: | description (str) – short description roles (list) – list of `Role` objects the group should be assigned to
    Returns: | bool (True if needed, False if not needed), xml of current group, xml of desired group

  `update`(description=None, roles=[])

    Updates a group

    Parameters: | description (str) – short description roles (list) – list of `Role` objects the group should be assigned to
    Returns: | xml of updated group

class `appngizer.elements.` `Groups`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage groups of an appNG instance

  `TYPE` = 'Group'
  `TYPE_C` = 'Groups'

class `appngizer.elements.` `Package`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage packages of an appNG instance

  `ALLOWED_FIELDS` = ['displayName', 'version', 'timestamp', 'release', 'snapshot', 'installed', 'type']
  `TYPE` = 'Package'
  `TYPE_C` = 'Packages'
  `delete`()

    Deletes a package

    Raises: | appngizer.errors.ElementError – delete is not avaible for packages

  `exist`(version, timestamp=None)

    Checks if package exist

    Parameters: | version (str) – version of package timestamp (str) – timestamp of package
    Returns: | bool (True if exist, False if not exist)

  `install`(version, timestamp=None, type='APPLICATION')

    Installs a package

    Parameters: | version (str) – version of package timestamp (str) – timestamp of package type (str) – type of package (APPLICATION|TEMPLATE)
    Returns: | xml of installed package

  `is_installed`()

    Checks if a package is already installed

    Returns: | bool (True if installed, False if not installed)

  `is_update_needed`(version, timestamp=None)

    Checks if update of an installed package is needed

    Parameters: | version (str) – version of package timestamp (str) – timestamp of package
    Returns: | bool (True if needed, False if not needed), xml of current package, xml of desired package

  `read`(version, timestamp=None)

    Reads package

    Parameters: | version (str) – version of package timestamp (str) – timestamp of package
    Returns: | xml of package

  `read_installed`()

    Reads package which is already installed

    Returns: | xml of installed package

  `update`(version, timestamp=None, type='APPLICATION')

    Updates an installed package

    Parameters: | version (str) – version of package timestamp (str) – timestamp of package type (str) – type of package (APPLICATION|TEMPLATE)
    Returns: | xml of updated package

class `appngizer.elements.` `Packages`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage packages of an appNG instance

  `TYPE` = 'Package'
  `TYPE_C` = 'Packages'
  `read`()

    Reads packages from a repository

    Returns: | xml of the packages

class `appngizer.elements.` `Permission`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage roles of an appNG instance

  `ALLOWED_FIELDS` = ['description']
  `TYPE` = 'Permission'
  `TYPE_C` = 'Permissions'
  `create`(description=None)

    Creates a new permission

    Parameters: | description (str) – short description
    Returns: | xml of created permission

  `is_update_needed`(description=None)

    Checks if update of permission is needed

    Parameters: | description (str) – short description
    Returns: | xml of updated permission
    Returns: | bool (True if needed, False if not needed), xml of current permission, xml of desired permission

  `update`(description=None)

    Updates a permission

    Parameters: | description (str) – short description
    Returns: | xml of updated permission

class `appngizer.elements.` `Permissions`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage permissions of an appNG instance

  `TYPE` = 'Permission'
  `TYPE_C` = 'Permissions'

class `appngizer.elements.` `Platform`(name='', parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage the platform of an appNG instance.

  `ALLOWED_FIELDS` = []
  `TYPE` = 'Platform'
  `TYPE_C` = 'Platform'
  `delete`()

    Deletes a platform

    Raises: | errors.ElementError – delete is not avaible for platform

  `exist`()

    Checks if platform already exist

    Raises: | errors.ElementError – exist is not avaible for platform

  `read`()

    Reads a platform

    Raises: | errors.ElementError – read is not avaible for platform

  `reload`()

    Reloads a platform

    Returns: | bool (True if reloaded, False if not reloaded)

class `appngizer.elements.` `Properties`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage properties of an appNG instance

  `TYPE` = 'Property'
  `TYPE_C` = 'Properties'

class `appngizer.elements.` `Property`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage properties of an appNG instance

  `ALLOWED_ATTRIBUTES` = ['clob']
  `ALLOWED_FIELDS` = ['value', 'defaultValue', 'description']
  `PRESERVED_FIELDS` = ['description', 'defaultValue']
  `TYPE` = 'Property'
  `TYPE_C` = 'Properties'
  `create`(value, defaultValue=None, description=None, clob=False)

    Creates a new property

    Parameters: | value (str) – value of property defaultValue (str) – default value of property description (str) – short description clob (bool) – treat property value as clob
    Returns: | xml of created property

  `is_update_needed`(value, defaultValue=None, description=None, clob=None)

    Checks if update of property is needed

    Parameters: | value (str) – value of property defaultValue (str) – default value of property description (str) – short description clob (bool) – treat property value as clob
    Returns: | bool (True if needed, False if not needed), xml of current property, xml of desired property

  `update`(value, defaultValue=None, description=None, clob=False)

    Updates a new property

    Parameters: | value (str) – value of property defaultValue (str) – default value of property description (str) – short description clob (bool) – treat property value as clob
    Returns: | xml of updated property

class `appngizer.elements.` `Repositories`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage repositories of an appNG instance

  `TYPE` = 'Repository'
  `TYPE_C` = 'Repositories'

class `appngizer.elements.` `Repository`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage repositories of an appNG instance

  `ALLOWED_FIELDS` = ['description', 'remoteName', 'uri', 'enabled', 'strict', 'published', 'mode', 'type']
  `TYPE` = 'Repository'
  `TYPE_C` = 'Repositories'
  `create`(uri, type='LOCAL', remoteName=None, mode='ALL', enabled=True, strict=False, published=False, description=None)

    Creates a new repository

    Parameters: | uri (str) – uri to the packages (file:// or http|s://) type (str) – type of repository (LOCAL = local repository, REMOTE = remote repository) remoteName (str) – name of remote repository mode (str) – mode of repository (ALL = all packages, STABLE = only stable packages, SNAPSHOT = only snapshot packages) enabled (bool) – enable repository strict (bool) – use strict mode published (bool) – publish repository description (str) – short description
    Returns: | xml of created repository

  `is_update_needed`(uri, type='LOCAL', remoteName=None, mode='ALL', enabled=True, strict=False, published=False, description=None)

    Checks if update of repository is needed

    Parameters: | uri (str) – uri to the packages (file:// or http|s://) type (str) – type of repository (LOCAL = local repository, REMOTE = remote repository) remoteName (str) – name of remote repository mode (str) – mode of repository (ALL = all packages, STABLE = only stable packages, SNAPSHOT = only snapshot packages) enabled (bool) – enable repository strict (bool) – use strict mode published (bool) – publish repository description (str) – short description
    Returns: | bool (True if needed, False if not needed), xml of current repository, xml of desired repository

  `update`(uri, type='LOCAL', remoteName=None, mode='ALL', enabled=True, strict=False, published=False, description=None)

    Updates a repository

    Parameters: | uri (str) – uri to the packages (file:// or http|s://) type (str) – type of repository (LOCAL = local repository, REMOTE = remote repository) remoteName (str) – name of remote repository mode (str) – mode of repository (ALL = all packages, STABLE = only stable packages, SNAPSHOT = only snapshot packages) enabled (bool) – enable repository strict (bool) – use strict mode published (bool) – publish repository description (str) – short description
    Returns: | xml of updated repository

class `appngizer.elements.` `Role`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage roles of an appNG instance

  `ALLOWED_CHILDS` = ['permissions']
  `ALLOWED_FIELDS` = ['application', 'description']
  `TYPE` = 'Role'
  `TYPE_C` = 'Roles'
  `create`(description=None, permissions=[])

    Creates a new role

    Parameters: | description (str) – short description permissions (list) – list of `Permission` objects the role should be assigned to
    Returns: | xml of created role

  `is_update_needed`(description=None, permissions=[])

    Checks if update of role is needed

    Parameters: | description (str) – short description permissions (list) – list of `Permission` objects the role should be assigned to
    Returns: | bool (True if needed, False if not needed), xml of current role, xml of desired role

  `update`(description=None, permissions=[])

    Updates a role

    Parameters: | description (str) – short description permissions (list) – list of `Permission` objects the role should be assigned to
    Returns: | xml of updated role

class `appngizer.elements.` `Roles`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage roles of an appNG instance

  `TYPE` = 'Role'
  `TYPE_C` = 'Roles'

class `appngizer.elements.` `Site`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage a site of an appNG instance

  `ALLOWED_FIELDS` = ['host', 'domain', 'description', 'active', 'createRepositoryPath']
  `TYPE` = 'Site'
  `TYPE_C` = 'Sites'
  `create`(host, domain, description=None, active=True, createRepositoryPath=True)

    Creates a new site

    Parameters: | host (str) – host header domain (str) – primary domain with protocol description (str) – short description active (bool) – activate site createRepositoryPath (bool) – create site directory in repository
    Returns: | xml of created site

  `is_update_needed`(host, domain, description=None, active=True, createRepositoryPath=True)

    Checks if update of site is needed

    Parameters: | host (str) – host header domain (str) – primary domain with protocol description (str) – short description active (bool) – activate site createRepositoryPath (bool) – create site directory in repository
    Returns: | bool (True if needed, False if not needed), xml of current site, xml of desired site

  `reload`()

    Reloads a site

    Returns: | bool (True if reloaded, False if not reloaded)

  `update`(host, domain, description=None, active=True, createRepositoryPath=True)

    Updates an existing site

    Parameters: | host (str) – host header domain (str) – primary domain with protocol description (str) – short description active (bool) – activate site createRepositoryPath (bool) – create site directory in repository
    Returns: | xml of updated site

class `appngizer.elements.` `Sites`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage sites of an appNG instance

  `TYPE` = 'Site'
  `TYPE_C` = 'Sites'

class `appngizer.elements.` `Subject`(name=None, parents=None, xml=None)

  Bases: `appngizer.elements.Element`

  Class to manage subjects of an appNG instance

  `ALLOWED_CHILDS` = ['groups']
  `ALLOWED_FIELDS` = ['realName', 'email', 'description', 'digest', 'timeZone', 'language', 'type']
  `TYPE` = 'Subject'
  `TYPE_C` = 'Subjects'
  `create`(realName, digest, email, description=None, language='en', type='LOCAL_USER', timeZone='Europe/Berlin', groups=[])

    Creates a new subject

    Parameters: | realName (str) – real name digest (str) – digest of subject (can be plaintext or bcrypt hash ($2a$13$)) email (str) – e-mail address description (str) – short description language (str) – language setting type (str) – subject type (LOCAL_USER|GLOBAL_USER|GLOBAL_GROUP) timeZone (str) – timezone setting groups (list) – list of `Group` objects the subject should be assigned to
    Returns: | xml of created subject

  `digest_match_hash`(digest, hashed)

    Checks if digest match hash

    If digest does not start with ‘$2a$’ it will handled as plaintext otherwise digest is directly matched against hashed

    Parameters: | digest (str) – digest of subject hashed (str) – bcrypt hash of digest to match
    Returns: | bool (True if match, False if not match)

  `get_digest_hash`()

    Gets digest field value from subject

    Returns: | digest of subject as string

  `is_update_needed`(realName, digest, email, description=None, language='en', type='LOCAL_USER', timeZone='Europe/Berlin', groups=[])

    Checks if update of subject is needed

    Parameters: | realName (str) – real name digest (str) – digest of subject (can be plaintext or bcrypt hash ($2a$13$)) email (str) – e-mail address description (str) – short description language (str) – language setting type (str) – subject type (LOCAL_USER|GLOBAL_USER|GLOBAL_GROUP) timeZone (str) – timezone setting groups (list) – list of `Group` objects the subject should be assigned to
    Returns: | bool (True if needed, False if not needed), xml of current subject, xml of desired subject

  `update`(realName, digest, email, description=None, language='en', type='LOCAL_USER', timeZone='Europe/Berlin', groups=[])

    Updates a subject

    Parameters: | realName (str) – real name digest (str) – digest of subject (can be plaintext or bcrypt hash ($2a$13$)) email (str) – e-mail address description (str) – short description language (str) – language setting type (str) – subject type (LOCAL_USER|GLOBAL_USER|GLOBAL_GROUP) timeZone (str) – timezone setting groups (list) – list of `Group` objects the subject should be assigned to
    Returns: | xml of updated subject

class `appngizer.elements.` `Subjects`(name='', parents=[], xml=None)

  Bases: `appngizer.elements.Elements`

  Class to manage subjects of an appNG instance

  `TYPE` = 'Subject'
  `TYPE_C` = 'Subjects'

## appngizer.errors module

exception `appngizer.errors.` `CLIError`

  Bases: `exceptions.Exception`

exception `appngizer.errors.` `ClientError`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `ElementError`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `Error`

  Bases: `exceptions.Exception`

exception `appngizer.errors.` `HttpClientBadRequest`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `HttpElementConflict`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `HttpElementForbidden`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `HttpElementNotFound`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `HttpServerError`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `NotAllowedOp`

  Bases: `appngizer.errors.Error`

exception `appngizer.errors.` `XMLValidationError`

  Bases: `appngizer.errors.Error`

## Module contents