From 79da3cabfd6f424ebf303095600d78e1fb1311f2 Mon Sep 17 00:00:00 2001 From: Tim Van Steenburgh Date: Wed, 18 May 2016 17:44:58 -0400 Subject: [PATCH] Filling in params, docstrings (wip) --- juju/cloud.py | 42 +++++++++++- juju/controller.py | 48 ++++++++++++-- juju/credential.py | 0 juju/juju.py | 21 +++++- juju/model.py | 160 ++++++++++++++++++++++++++++++++++++++------- juju/service.py | 41 ++++++++++-- juju/unit.py | 11 +++- 7 files changed, 277 insertions(+), 46 deletions(-) create mode 100644 juju/credential.py diff --git a/juju/cloud.py b/juju/cloud.py index 474d5a6..b1a1276 100644 --- a/juju/cloud.py +++ b/juju/cloud.py @@ -1,7 +1,14 @@ class Cloud(object): - def add_credential(self): + """Cloud + + :ivar name: Name of the cloud + + """ + def add_credential(self, credential): """Add or replaces credentials for this cloud. + :param `juju.Credential` credential: The Credential to add + """ pass @@ -17,9 +24,40 @@ class Cloud(object): """ pass - def bootstrap(self): + def bootstrap( + self, controller_name, region=None, agent_version=None, + auto_upgrade=False, bootstrap_constraints=None, + bootstrap_series=None, config=None, constraints=None, + credential=None, default_model=None, keep_broken=False, + metadata_source=None, no_gui=False, to=None, + upload_tools=False): + """Initialize a cloud environment. + :param str controller_name: Name of controller to create + :param str region: Cloud region in which to bootstrap + :param str agent_version: Version of tools to use for Juju agents + :param bool auto_upgrade: Upgrade to latest path release tools on first + bootstrap + :param :class:`juju.Constraints` bootstrap_constraints: Constraints + for the bootstrap machine + :param str bootstrap_series: Series of the bootstrap machine + :param dict config: Controller configuration + :param :class:`juju.Constraints` constraints: Default constraints for + all future workload machines + :param :class:`juju.Credential` credential: Credential to use when + bootstrapping + :param str default_model: Name to give the default model + :param bool keep_broken: Don't destroy model if bootstrap fails + :param str metadata_source: Local path to use as tools and/or metadata + source + :param bool no_gui: Don't install the Juju GUI in the controller when + bootstrapping + :param str to: Placement directive for bootstrap node (typically used + with MAAS) + :param bool upload_tools: Upload local version of tools before + bootstrapping + """ pass diff --git a/juju/controller.py b/juju/controller.py index 632b98e..d7911a5 100644 --- a/juju/controller.py +++ b/juju/controller.py @@ -1,31 +1,49 @@ class Controller(object): - def add_model(self): + def add_model(self, name, config=None, credential=None, owner=None): """Add a model to this controller. + :param str name: Name of the model + :param dict config: Model configuration + :param str credential: e.g. ':' + :param str owner: Owner username + """ pass - def add_user(self): + def add_user(self, username, display_name=None, acl=None, models=None): """Add a user to this controller. + :param str username: Username + :param str display_name: Display name + :param str acl: Access control, e.g. 'read' + :param list models: Models to which the user is granted access + """ pass - def change_user_password(self): + def change_user_password(self, username, password): """Change the password for a user in this controller. + :param str username: Username + :param str password: New password + """ pass - def destroy(self): + def destroy(self, destroy_all_models=False): """Destroy this controller. + :param bool destroy_all_models: Destroy all hosted models in the + controller. + """ pass - def disable_user(self): + def disable_user(self, username): """Disable a user. + :param str username: Username + """ pass @@ -42,15 +60,31 @@ class Controller(object): """ pass - def get_models(self): + def get_models(self, all_=False, username=None): """Return list of available models on this controller. + :param bool all_: List all models, regardless of user accessibilty + (admin use only) + :param str username: User for which to list models (admin use only) + """ pass - def get_payloads(self): + def get_payloads(self, *patterns): """Return list of known payloads. + :param str \*patterns: Patterns to match against + + Each pattern will be checked against the following info in Juju:: + + - unit name + - machine id + - payload type + - payload class + - payload id + - payload tag + - payload status + """ pass diff --git a/juju/credential.py b/juju/credential.py new file mode 100644 index 0000000..e69de29 diff --git a/juju/juju.py b/juju/juju.py index b1dcabd..45e5c9e 100644 --- a/juju/juju.py +++ b/juju/juju.py @@ -1,13 +1,26 @@ class Juju(object): - def add_cloud(self): + def add_cloud(self, name, definition, replace=False): """Add a user-defined cloud to Juju from among known cloud types. + :param str name: Name of cloud + :param dict definition: Cloud definition + + Example cloud definition, as yaml:: + + type: openstack + auth-types: [ userpass ] + regions: + london: + endpoint: https://london.mycloud.com:35574/v3.0/ + """ pass - def agree(self): + def agree(self, *terms): """Agree to the terms of a charm. + :param str \*terms: Terms to agree to + """ pass @@ -49,9 +62,11 @@ class Juju(object): """ pass - def get_plans(self, charm_name): + def get_plans(self, charm_url): """Return list of plans available for the specified charm. + :param str charm_url: Charm url + """ pass diff --git a/juju/model.py b/juju/model.py index 32295d5..e6fcda1 100644 --- a/juju/model.py +++ b/juju/model.py @@ -1,34 +1,69 @@ class Model(object): - def add_machine(self): + def add_machine( + self, spec=None, constraints=None, disks=None, series=None, + count=1): """Start a new, empty machine and optionally a container, or add a container to a machine. + :param str spec: Machine specification + Examples:: + (None) - starts a new machine + 'lxc' - starts a new machine with on lxc container + 'lxc:4' - starts a new lxc container on machine 4 + 'ssh:user@10.10.0.3' - manually provisions a machine with ssh + 'zone=us-east-1a' - starts a machine in zone us-east-1s on AWS + 'maas2.name' - acquire machine maas2.name on MAAS + :param :class:`juju.Constraints` constraints: Machine constraints + :param list disks: List of disk :class:`constraints ` + :param str series: Series + :param int count: Number of machines to deploy + + Supported container types are: lxc, lxd, kvm + + When deploying a container to an existing machine, constraints cannot + be used. + """ pass add_machines = add_machine - def add_relation(self): + def add_relation(self, relation1, relation2): """Add a relation between two services. + :param str relation1: '[:]' + :param str relation2: '[:]' + """ pass - def add_space(self): + def add_space(self, name, *cidrs): """Add a new network space. + Adds a new space with the given name and associates the given + (optional) list of existing subnet CIDRs with it. + + :param str name: Name of the space + :param \*cidrs: Optional list of existing subnet CIDRs + """ pass - def add_ssh_key(self): + def add_ssh_key(self, key): """Add a public SSH key to this model. + :param str key: The public ssh key + """ pass add_ssh_keys = add_ssh_key - def add_subnet(self): + def add_subnet(self, cidr_or_id, space, *zones): """Add an existing subnet to this model. + :param str cidr_or_id: CIDR or provider ID of the existing subnet + :param str space: Network space with which to associate + :param str \*zones: Zone(s) in which the subnet resides + """ pass @@ -38,9 +73,12 @@ class Model(object): """ pass - def block(self): + def block(self, *commands): """Add a new block to this model. + :param str \*commands: The commands to block. Valid values are + 'all-changes', 'destroy-model', 'remove-object' + """ pass @@ -50,33 +88,89 @@ class Model(object): """ pass - def get_cached_images(self): + def get_cached_images(self, arch=None, kind=None, series=None): """Return a list of cached OS images. + :param str arch: Filter by image architecture + :param str kind: Filter by image kind, e.g. 'lxd' + :param str series: Filter by image series, e.g. 'xenial' + """ pass - def create_backup(self): + def create_backup(self, note=None, no_download=False): """Create a backup of this model. + :param str note: A note to store with the backup + :param bool no_download: Do not download the backup archive + :return str: Path to downloaded archive + """ pass - def create_storage_pool(self): + def create_storage_pool(self, name, provider_type, **pool_config): """Create or define a storage pool. + :param str name: Name to give the storage pool + :param str provider_type: Pool provider type + :param \*\*pool_config: key/value pool configuration pairs + """ pass - def debug_log(self): + def debug_log( + self, no_tail=False, exclude_module=None, include_module=None, + include=None, level=None, limit=0, lines=10, replay=False, + exclude=None): """Get log messages for this model. - """ - pass - - def deploy(self): + :param bool no_tail: Stop after returning existing log messages + :param list exclude_module: Do not show log messages for these logging + modules + :param list include_module: Only show log messages for these logging + modules + :param list include: Only show log messages for these entities + :param str level: Log level to show, valid options are 'TRACE', + 'DEBUG', 'INFO', 'WARNING', 'ERROR, + :param int limit: Return this many of the most recent (possibly + filtered) lines are shown + :param int lines: Yield this many of the most recent lines, and keep + yielding + :param bool replay: Yield the entire log, and keep yielding + :param list exclude: Do not show log messages for these entities + + """ + pass + + def deploy( + self, entity_url, service_name=None, bind=None, budget=None, + channel=None, config=None, constraints=None, force=False, + num_units=1, plan=None, resource=None, series=None, storage=None, + to=None): """Deploy a new service or bundle. + :param str entity_url: Charm or bundle url + :param str service_name: Name to give the service + :param dict bind: : pairs + :param dict budget: : pairs + :param str channel: Charm store channel from which to retrieve + the charm or bundle, e.g. 'development' + :param dict config: Charm configuration dictionary + :param :class:`juju.Constraints` constraints: Service constraints + :param bool force: Allow charm to be deployed to a machine running + an unsupported series + :param int num_units: Number of units to deploy + :param str plan: Plan under which to deploy charm + :param dict resource: : pairs + :param str series: Series on which to deploy + :param dict storage: Storage constraints TODO how do these look? + :param str to: Placement directive, e.g.:: + '23' - machine 23 + 'lxc:7' - new lxc container on machine 7 + '24/lxc/3' - lxc container 3 or machine 24 + + If None, a new machine is provisioned. + """ pass @@ -86,15 +180,30 @@ class Model(object): """ pass - def get_backup(self): + def get_backup(self, archive_id): """Download a backup archive file. + :param str archive_id: The id of the archive to download + :return str: Path to the archive file + """ pass - def enable_ha(self): + def enable_ha( + self, num_controllers=0, constraints=None, series=None, to=None): """Ensure sufficient controllers exist to provide redundancy. + :param int num_controllers: Number of controllers to make available + :param :class:`juju.Constraints` constraints: Constraints to apply + to the controller machines + :param str series: Series of the controller machines + :param list to: Placement directives for controller machines, e.g.:: + '23' - machine 23 + 'lxc:7' - new lxc container on machine 7 + '24/lxc/3' - lxc container 3 or machine 24 + + If None, a new machine is provisioned. + """ pass @@ -110,28 +219,29 @@ class Model(object): """ pass - def grant(self): + def grant(self, username, acl='read'): """Grant a user access to this model. + :param str username: Username + :param str acl: Access control ('read' or 'write') + """ pass - def import_ssh_key(self): + def import_ssh_key(self, identity): """Add a public SSH key from a trusted indentity source to this model. - """ - pass - import_ssh_keys = import_ssh_key - - def get_machine(self, machine_id): - """Get a machine by id. + :param str identity: User identity in the form : """ pass + import_ssh_keys = import_ssh_key - def get_machines(self): + def get_machines(self, utc=False): """Return list of machines in this model. + :param bool utc: Display time as UTC in RFC3339 format + """ pass diff --git a/juju/service.py b/juju/service.py index 08324bd..007306a 100644 --- a/juju/service.py +++ b/juju/service.py @@ -1,26 +1,44 @@ class Service(object): - def add_relation(self): + def add_relation(self, local_relation, remote_relation): """Add a relation to another service. + :param str local_relation: Name of relation on this service + :param str remote_relation: Name of relation on the other service in + the form '[:]' + """ pass - def add_unit(self): + def add_unit(self, count=1, to=None): """Add one or more units to this service. + :param int count: Number of units to add + :param str to: Placement directive, e.g.:: + '23' - machine 23 + 'lxc:7' - new lxc container on machine 7 + '24/lxc/3' - lxc container 3 or machine 24 + + If None, a new machine is provisioned. + """ pass add_units = add_unit - def allocate(self): + def allocate(self, budget, value): """Allocate budget to this service. + :param str budget: Name of budget + :param int value: Budget limit + """ pass - def attach(self): + def attach(self, resource_name, file_path): """Upload a file as a resource for this service. + :param str resource: Name of the resource + :param str file_path: Path to the file to upload + """ pass @@ -30,9 +48,13 @@ class Service(object): """ pass - def destroy_relation(self): + def destroy_relation(self, local_relation, remote_relation): """Remove a relation to another service. + :param str local_relation: Name of relation on this service + :param str remote_relation: Name of relation on the other service in + the form '[:]' + """ pass remove_relation = destroy_relation @@ -62,15 +84,20 @@ class Service(object): """ pass - def get_actions(self): + def get_actions(self, schema=False): """Get actions defined for this service. + :param bool schema: Return the full action schema + """ pass - def get_resources(self): + def get_resources(self, details=False): """Return resources for this service. + :param bool details: Include detailed info about resources used by each + unit + """ pass diff --git a/juju/unit.py b/juju/unit.py index 1a26a55..6450691 100644 --- a/juju/unit.py +++ b/juju/unit.py @@ -1,7 +1,11 @@ class Unit(object): - def add_storage(self): + def add_storage(self, name, constraints=None): """Add unit storage dynamically. + :param str name: Storage name, as specified by the charm + :param str constraints: Comma-separated list of constraints in the + form 'POOL,COUNT,SIZE' + """ pass @@ -18,9 +22,12 @@ class Unit(object): pass remove = destroy - def get_resources(self): + def get_resources(self, details=False): """Return resources for this unit. + :param bool details: Include detailed info about resources used by each + unit + """ pass -- 2.25.1