[Python-modules-commits] [python-shade] 01/04: Import python-shade_1.3.0.orig.tar.gz
Clint Byrum
spamaps at moszumanska.debian.org
Sat Dec 26 16:05:31 UTC 2015
This is an automated email from the git hooks/post-receive script.
spamaps pushed a commit to tag debian-1.3.0-1
in repository python-shade.
commit 5a22215a91f4ddf43831ce76629a461e0d918f7b
Author: Clint Byrum <clint at fewbar.com>
Date: Sat Dec 26 07:56:51 2015 -0800
Import python-shade_1.3.0.orig.tar.gz
---
.coveragerc | 2 +-
.mailmap | 3 +-
AUTHORS | 12 +-
ChangeLog | 387 ++
PKG-INFO | 46 +-
README.rst | 46 +-
doc/source/coding.rst | 89 +
doc/source/future.rst | 176 +
doc/source/index.rst | 4 +-
doc/source/installation.rst | 2 +-
doc/source/usage.rst | 5 +-
extras/delete-network.sh | 14 +
extras/run-ansible-tests.sh | 75 +
requirements.txt | 24 +-
setup.cfg | 8 +-
shade.egg-info/PKG-INFO | 46 +-
shade.egg-info/SOURCES.txt | 75 +-
shade.egg-info/entry_points.txt | 3 +
shade.egg-info/pbr.json | 2 +-
shade.egg-info/requires.txt | 24 +-
shade/__init__.py | 2768 +------------
shade/_log.py | 28 +
shade/_tasks.py | 406 +-
shade/_utils.py | 453 ++
shade/cmd/__init__.py | 0
shade/cmd/inventory.py | 68 +
shade/exc.py | 39 +-
shade/inventory.py | 60 +
shade/meta.py | 269 +-
shade/openstackcloud.py | 4318 ++++++++++++++++++++
shade/operatorcloud.py | 1474 +++++++
shade/task_manager.py | 41 +-
shade/tests/ansible/README.txt | 26 +
.../hooks/post_test_hook.sh | 9 +-
shade/tests/ansible/roles/auth/tasks/main.yml | 6 +
.../ansible/roles/client_config/tasks/main.yml | 7 +
shade/tests/ansible/roles/image/tasks/main.yml | 54 +
shade/tests/ansible/roles/image/vars/main.yml | 1 +
shade/tests/ansible/roles/keypair/tasks/main.yml | 54 +
shade/tests/ansible/roles/keypair/vars/main.yml | 1 +
shade/tests/ansible/roles/network/tasks/main.yml | 14 +
shade/tests/ansible/roles/network/vars/main.yml | 3 +
.../tests/ansible/roles/nova_flavor/tasks/main.yml | 53 +
shade/tests/ansible/roles/object/tasks/main.yml | 37 +
shade/tests/ansible/roles/port/tasks/main.yml | 79 +
shade/tests/ansible/roles/port/vars/main.yml | 4 +
shade/tests/ansible/roles/router/tasks/main.yml | 70 +
shade/tests/ansible/roles/router/vars/main.yml | 2 +
.../ansible/roles/security_group/tasks/main.yml | 123 +
.../ansible/roles/security_group/vars/main.yml | 1 +
shade/tests/ansible/roles/subnet/tasks/main.yml | 43 +
shade/tests/ansible/roles/subnet/vars/main.yml | 1 +
shade/tests/ansible/roles/user/tasks/main.yml | 30 +
.../tests/ansible/roles/user_group/tasks/main.yml | 31 +
shade/tests/ansible/roles/volume/tasks/main.yml | 17 +
shade/tests/ansible/run.yml | 20 +
shade/tests/fakes.py | 142 +-
shade/tests/functional/hooks/post_test_hook.sh | 16 +-
shade/tests/functional/test_compute.py | 162 +-
shade/tests/functional/test_domain.py | 65 +
shade/tests/functional/test_endpoints.py | 166 +
shade/tests/functional/test_flavor.py | 127 +
shade/tests/functional/test_floating_ip.py | 246 ++
shade/tests/functional/test_floating_ip_pool.py | 52 +
shade/tests/functional/test_groups.py | 105 +
shade/tests/functional/test_identity.py | 81 +
shade/tests/functional/test_image.py | 12 +-
shade/tests/functional/test_inventory.py | 74 +
shade/tests/functional/test_network.py | 74 +
shade/tests/functional/test_object.py | 74 +
shade/tests/functional/test_port.py | 135 +
shade/tests/functional/test_router.py | 307 ++
shade/tests/functional/test_services.py | 108 +
shade/tests/functional/test_users.py | 134 +
shade/tests/functional/test_volume.py | 66 +
shade/tests/functional/util.py | 10 +
shade/tests/unit/test__utils.py | 114 +
shade/tests/unit/test_caching.py | 250 +-
shade/tests/unit/test_create_server.py | 89 +-
shade/tests/unit/test_create_volume_snapshot.py | 119 +
shade/tests/unit/test_delete_server.py | 64 +-
shade/tests/unit/test_delete_volume_snapshot.py | 94 +
shade/tests/unit/test_domain_params.py | 78 +
shade/tests/unit/test_domains.py | 48 +
shade/tests/unit/test_endpoints.py | 131 +
shade/tests/unit/test_flavors.py | 98 +
shade/tests/unit/test_floating_ip_common.py | 112 +
shade/tests/unit/test_floating_ip_neutron.py | 386 ++
shade/tests/unit/test_floating_ip_nova.py | 250 ++
shade/tests/unit/test_floating_ip_pool.py | 63 +
shade/tests/unit/test_groups.py | 64 +
shade/tests/unit/test_identity_roles.py | 65 +
shade/tests/unit/test_keypair.py | 72 +
shade/tests/unit/test_meta.py | 322 +-
shade/tests/unit/test_network.py | 50 +
shade/tests/unit/test_object.py | 96 +
shade/tests/unit/test_operator_noauth.py | 20 +-
shade/tests/unit/test_port.py | 271 ++
shade/tests/unit/test_project.py | 120 +
shade/tests/unit/test_rebuild_server.py | 33 +-
shade/tests/unit/test_security_groups.py | 335 ++
shade/tests/unit/test_services.py | 136 +
shade/tests/unit/test_shade.py | 729 +---
shade/tests/unit/test_shade_operator.py | 1070 +++++
shade/tests/unit/test_task_manager.py | 56 +
shade/tests/unit/test_users.py | 134 +
test-requirements.txt | 2 +-
tox.ini | 9 +-
108 files changed, 15699 insertions(+), 3590 deletions(-)
diff --git a/.coveragerc b/.coveragerc
index 078cf72..ca361e5 100644
--- a/.coveragerc
+++ b/.coveragerc
@@ -4,4 +4,4 @@ source = shade
omit = shade/tests/*
[report]
-ignore-errors = True
+ignore_errors = True
diff --git a/.mailmap b/.mailmap
index cc92f17..4d8361e 100644
--- a/.mailmap
+++ b/.mailmap
@@ -1,3 +1,4 @@
# Format is:
# <preferred e-mail> <other e-mail 1>
-# <preferred e-mail> <other e-mail 2>
\ No newline at end of file
+# <preferred e-mail> <other e-mail 2>
+<jeblair at linux.vnet.ibm.com> <jeblair at hp.com>
diff --git a/AUTHORS b/AUTHORS
index 6d01fc9..3c354e6 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,14 +1,24 @@
Adam Gandelman <adamg at ubuntu.com>
+Alberto Gireud <agireud at us.ibm.com>
+Atsushi SAKAI <sakaia at jp.fujitsu.com>
+Caleb Boylan <calebboylan at gmail.com>
+Clark Boylan <clark.boylan at gmail.com>
Clint Byrum <clint at fewbar.com>
David Shrewsbury <shrewsbury.dave at gmail.com>
Davide Guerri <davide.guerri at gmail.com>
Devananda van der Veen <devananda.vdv at gmail.com>
Ghe Rivero <ghe.rivero at hp.com>
Gregory Haynes <greg at greghaynes.net>
-James E. Blair <jeblair at hp.com>
+Haikel Guemar <hguemar at fedoraproject.org>
+James E. Blair <jeblair at linux.vnet.ibm.com>
+Jeremy Stanley <fungi at yuggoth.org>
Joshua Harlow <harlowja at yahoo-inc.com>
Julia Kreger <juliaashleykreger at gmail.com>
+Lars Kellogg-Stedman <lars at redhat.com>
Monty Taylor <mordred at inaugust.com>
Ricardo Carrillo Cruz <ricardo.carrillo.cruz at gmail.com>
+Rosario Di Somma <rosario.disomma at dreamhost.com>
+Steve Leon <kokhang at gmail.com>
Timothy Chavez <timothy.chavez at hp.com>
Yolanda Robla <yolanda.robla-mota at hp.com>
+matthew wagoner <zxkuqyb at gmail.com>
diff --git a/ChangeLog b/ChangeLog
index 1ea0fb1..2129f65 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,393 @@
CHANGES
=======
+1.3.0
+-----
+
+* Improve test coverage: project API
+* Improve test coverage: user API
+* Provide a better comment for the object short-circuit
+* Remove cinderclient version pin
+* Add functional tests for boot from volume
+* Enable running tests against RAX and IBM
+* Don't double-print exception subjects
+* Accept objects in name_or_id parameter
+* Normalize volume objects
+* Fix argument sequences for boot from volume
+* Make delete_server() return True/False
+* Adjust conditions when enable_snat is specified
+* Only log errors in exceptions on demand
+* Fix resource leak in test_compute
+* Clean up compute functional tests
+* Stop using nova client in test_compute
+* Retry API calls if they get a Retryable failure
+* Fix call to shade_exceptions in update_project
+* Add test for os_volume Ansible module
+
+1.2.0
+-----
+
+* Fix for min_disk/min_ram in create_image API
+* Add test for os_image Ansible module
+* Fix warnings.filterwarnings call
+* boot-from-volume and network params for server create
+* Do not send 'router:external' unless it is set
+* Add test for os_port Ansible module
+* Allow specifying cloud name to ansible tests
+* Fix a 60 second unit test
+* Make sure timeouts are floats
+* Remove default values from innner method
+* Bump os-client-config requirement
+* Add test for os_user_group Ansible module
+* Add user group assignment API
+* Add test for os_user Ansible module
+* Add test for os_nova_flavor Ansible module
+* Stop using uuid in functional tests
+* Make functional object tests actually run
+* Add Ansible object role
+* Fix for create_object
+* Four minor fixes that make debugging better
+* Add new context manager for shade exceptions, final
+* Add ability to selectively run ansible tests
+* Add Ansible testing infrastructure
+* Add new context manager for shade exceptions, cont. again
+* Pull server list cache setting via API
+* Plumb fixed_address through add_ips_to_server
+* Let os-client-config handle session creation
+* Remove designate support
+* Remove test reference to api_versions
+* Update dated project methods
+* Fix incorrect variable name
+* Add CRUD methods for keystone groups
+* Bump ironicclient depend
+* Make sure cache expiration time is an int
+* Add new context manager for shade exceptions, cont
+* Use the requestsexceptions library
+* Don't warn on configured insecure certs
+* Normalize domain data
+* Normalization methods should return Munch
+* Fix keystone domain searching
+* Add new context manager for shade exceptions
+* teach shade how to list_hypervisors
+* Update ansible router playbook
+* Stop calling obj_to_dict everwhere
+* Always return a munch from Tasks
+* Make raw-requests calls behave like client calls
+* Minor logging improvements
+* Remove another extraneous get for create_server
+* Don't wrap wrapped exception in create_server
+* Skip an extra unneeded server get
+* Don't wrap wrapped exceptions in operatorcloud.py
+* Add docs for create_server
+* Update README to not reference client passthrough
+* Move ironic client attribute to correct class
+* Move _neutron_exceptions context manager to _utils
+* Fix misspelling of ironic state name
+* Timeout too aggressive for inspection tests
+* Split out OpenStackCloud and OperatorCloud classes
+* Adds volume snapshot functionality to shade
+* Fix the return values of create and delete volume
+* Remove removal of jenkins clouds.yaml
+* Consume /etc/openstack/clouds.yaml
+* Add logic to support baremetal inspection
+
+1.0.0
+-----
+
+* node_set_provision_state wait/timeout support
+* Add warning suppression for keystoneauth loggers
+* Suppress Rackspace SAN warnings again
+* return additional detail about servers
+* expand security groups in get_hostvars_from_server
+* add list_server_security_groups method
+* Add swift object and container list functionality
+* Translate task name in log message always
+* Add debug logging to iterate timeout
+* Change the fallback on server wait to 2 seconds
+* Add entry for James Blair to .mailmap
+* handle routers without an external gateway in list_router_interfaces
+* Fix projects list/search/get interface
+* Remove unused parameter from create_stack
+* Move valid_kwargs decorator to _utils
+* Add heat support
+* Abstract out the name of the name key
+* Add heatclient support
+* Use OCC to create clouds in inventory
+* novaclient 2.32.0 does not work against rackspace
+* Support private address override in inventory
+* Normalize user information
+* Set cache information from clouds.yaml
+* Make designate record methods private for now
+* Rely on devstack for clouds.yaml
+* Rename identity_domain to domain
+* Rename designate domains to zones
+* Replace Bunch with compatible fork Munch
+* Make a few IP methods private
+
+0.16.0
+------
+
+* Push filtering down into neutron
+* Make floating IP func tests less racey
+* Make router func tests less racey
+* Create neutron floating ips with server info
+* Undecorate cache decorated methods on null cache
+* Tweak create_server to use list_servers cache
+* Add API method to list router interfaces
+* Handle list_servers caching more directly
+* Split the nova server active check out
+* Pass wait to add_ips_to_server
+* Fix floating ip removal on delete server
+* Document filters for get methods
+* Add some more docstrings
+* Remove shared=False from get_internal_network
+* Make attach_instance return updated volume object
+* Tell git to ignore .eggs directory
+* Align users with list/search/get interface
+* Add script to document deleting private networks
+* Add create/delete for keystone roles
+* Accept and emit union of keystone v2/v3 service
+* Use keystone v3 service type argument
+* Add get/list/search methods for identity roles
+* Add methods to update internal router interfaces
+* Add get_server_by_id optmization
+* Add option to floating ip creation to not reuse
+* Provide option to delete floating IP with server
+* Update python-troveclient requirement
+* Add a private method for nodepool server vars
+* Update required ironicclient version
+* Split get_hostvars_from_server into two
+* Invalidate image cache everytime we make a change
+* Use the ipaddress library for ip calculations
+* Optimize network finding
+* Fix create_image_snapshot
+
+0.15.0
+------
+
+* Return IPv6 address for interface_ip on request
+* Plumb wait and timout down to add_auto_ip
+* Pass parameters correctly for image snapshots
+* Fix mis-named has_service entry
+* Provide shortcut around has_service
+* Provide short-circuit for finding server networks
+* Update fake to match latest OCC
+* Dont throw exception on missing service
+* Add functional test for private_v4
+* Attempt to use glanceclient strip_version
+* Fix baremetal port deletion
+
+0.14.0
+------
+
+* Add router ansible test and update network role
+* Trap exceptions in helper functions
+* Add more info to some exceptions
+* Allow more complex router updates
+* Allow more complex router creation
+* Allow creating externally accessible networks
+* Handle glance v1 and v2 difference with is_public
+* Get defaults for image type from occ
+* Use the get_auth function from occ
+* Add a NullHandler to all of our loggers
+* Remove many redundant debug logs
+* Make inner_exception a private member
+* Just do the error logging in the base exception
+* Store the inner exception when creating an OSCException
+* Start using keystoneauth for keystone sessions
+* Move keystone to common identity client interface
+* Bump the default API version for python-ironicclient
+* Avoid 2.27.0 of novaclient
+* unregister_machine blocking logic
+* Fix exception lists in functional tests
+* Migrate neutron to the common client interface
+* Remove last vestige of glanceclient being different
+* Pass timeout to session, not constructors
+* Delete floating ip by ID instead of name
+
+0.13.0
+------
+
+* Move glanceclient to new common interface
+* Addition of shade unregister_machine timeout
+* Initial support for ironic enroll state
+* Add flavor access API
+* Make client constructor calls consistent
+* Change functional testing to use clouds.yaml
+* Add a developer coding standards doc
+
+0.12.0
+------
+
+* Add flavor functional tests
+* Bug fix for obj_to_dict()
+* Add log message for when IP addresses fail
+* Add methods to set and unset flavor extra specs
+* Listing flavors should pull all flavors
+* Be consistent with accessing server dict
+* Throw an exception on a server without an IP
+* Be smarter finding private IP
+* Clarify future changes in docs
+* Remove meta.get_server_public_ip() function
+* Document create_object
+* Remove unused server functions
+* Fix two typos and one readablity on shade documentation
+* Pass socket timeout to swiftclient
+* Process config options via os-client-config
+* Update ansible subnet test
+* Fix test_object.py test class name
+* Fix for swift servers older than 1.11.0
+* Use disable_vendor_agent flags in create_image
+* Use os-client-config SSL arg processing
+* Correctly pass the server ID to add_ip_from_pool
+* Add initial designate read-only operations
+* Always use a fixed address when attaching a floating IP to a server
+* Catch leaky exceptions from create_image()
+
+0.11.0
+------
+
+* Add flavor admin support
+* Fix debug logging lines
+* Account for Error 396 on Rackspace
+* Fix small error in README.rst
+* Allow use of admin tokens in keystone
+* Fix identity domain methods
+* Update ansible module playbooks
+* Rework how we get domains
+* Fix "Bad floatingip request" when multiple fixed IPs are present
+* Add Ansible module test for subnet
+* Add Ansible module test for networks
+* Add a testing framework for the Ansible modules
+* Support project/tenant and domain vs. None
+* Add CRUD methods for Keystone domains
+
+0.10.0
+------
+
+* Raise exception for nova egress secgroup rule
+* Modify secgroup rule processing
+* Make sure we are returning floating IPs in current domain
+* Correctly name the functional TestImage class
+
+0.9.0
+-----
+
+* Locking ironic API microversion
+* Add Neutron/Nova Floating IP tests
+* Adding SSL arguments to glance client
+* Remove list_keypair_dicts method
+* Do not use environment for Swift unit tests
+* Add Neutron/Nova Floating IP attach/detach
+* Fix available_floating_ip when using Nova network
+* Skip Swift functional tests if needed
+* Fix AttributeError in keystone functional tests
+* Update keypair APIs to latest standards
+* Add Neutron/Nova Floating IP delete (i.e. deallocate from project)
+* Add Neutron/Nova Floating IP create (i.e. allocate to project)
+* Convert ironicclient node.update() call to Task
+* Convert ironicclient node.get() call to Task
+* Move TestShadeOperator in a separate file
+* Fix intermittent error in unit tests
+* Pin cinderclient
+* Add comment explaining why finding an IP is hard
+* Add IPv6 to the server information too
+* Use accessIPv4 and accessIPv6 if they're there
+* Add Neutron/Nova Floating IP list/search/get
+
+0.8.2
+-----
+
+* Catch all exceptions around port for ip finding
+* Centralize exception management for Neutron
+
+0.8.1
+-----
+
+* Fix MD5 headers regression
+* Ensure that service values are strings
+* Pass token and endpoint to swift os_options
+* Convert ironicclient node.validate() call to Task
+* Convert ironicclient node.list() call to Task
+* Return True/False for delete methods
+
+0.8.0
+-----
+
+* Add delete method for security group rules
+* Add get_server_external_ipv6() to meta
+* Refactor find_nova_addresses()
+* Replace get_server_public_ip() with get_server_external_ipv4()
+* Add get_server_external_ipv4() to meta
+* Add more parameters to update_port()
+* Improve documentation for create_port()
+* Correct get_machine_by_mac and add test
+* Add create method for secgroup rule
+* Coalesce port values in secgroup rules
+* Move _utils unit testing to separate file
+
+0.7.0
+-----
+
+* Add secgroup update API
+* Add very initial support for passing in occ object
+* Don't emit volume tracebacks in inventory debug
+* Return new secgroup object
+* Port ironic client port.get_by_address() to a Task
+* Port ironic client port.get() to a Task
+* Add inventory command to shade
+* Extract logging config into a helper function
+* Add create method for security groups
+* Add delete method for security groups
+* Switch to SwiftService for segmented uploads
+* Add support to get a SwiftService object
+* Add port resource methods
+* Split security group list operations
+* Add keystone endpoint resource methods
+* Add Keystone service resource methods
+* Rely on defaults being present
+* Consume os_client_config defaults as base defaults
+* Remove hacking select line
+* Add design for an object interface
+* Port ironic client node.list_ports() to a Task
+* Port ironic client port.list() to a Task
+* Split list filtering into _utils
+
+0.6.5
+-----
+
+* Cast nova server object to dict after refetch
+* Split iterate_timeout into _utils
+* Cleanup OperatorCloud doc errors/warnings
+* Update pbr version pins
+
+0.6.4
+-----
+
+* Set metadata headers on object create
+
+0.6.3
+-----
+
+* Always refresh glanceclient for tokens validity
+* Don't cache keystone tokens as KSC does it for us
+* Make sure glance image list actually runs in Tasks
+
+0.6.2
+-----
+
+* Make caching work when cloud name is None
+* Handle novaclient exception in delete_server wait
+* Support PUT in Image v2 API
+* Make ironic use the API version system
+* Catch client exceptions during list ops
+* Replace ci.o.o links with docs.o.o/infra
+* Pass OS_ variables through to functional tests
+* Improve error message on auth_plugin failure
+* Handle novaclient exceptions during delete_server
+* Add floating IP pool resource methods
+* Don't error on missing certs
+
0.6.1
-----
diff --git a/PKG-INFO b/PKG-INFO
index d7bb31c..0b53537 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,13 +1,13 @@
Metadata-Version: 1.1
Name: shade
-Version: 0.6.1
+Version: 1.3.0
Summary: Client library for operating OpenStack clouds
-Home-page: http://ci.openstack.org/
+Home-page: http://docs.openstack.org/infra/shade/
Author: OpenStack Infrastructure Team
Author-email: openstack-infra at lists.openstack.org
License: UNKNOWN
-Description: shade
- =====
+Description: Introduction
+ ============
shade is a simple client library for operating OpenStack clouds. The
key word here is *simple*. Clouds can do many many many things - but there are
@@ -25,36 +25,32 @@ Description: shade
developed to run client applications at scale, it turned out that we'd written
nine-tenths of what we'd need to have a standalone library.
- example
- -------
+ Example
+ =======
Sometimes an example is nice.
::
- from shade import *
- import time
+ import shade
+
+ # Initialize and turn on debug loggin
+ shade.simple_logging(debug=True)
# Initialize cloud
# Cloud configs are read with os-client-config
- cloud = openstack_cloud('mordred')
+ cloud = shade.openstack_cloud(cloud='mordred')
+
+ # Upload an image to the cloud
+ image = cloud.create_image(
+ 'ubuntu-trusty', filename='ubuntu-trusty.qcow2', wait=True)
- # OpenStackCloud object has an interface exposing OpenStack services methods
- print cloud.list_servers()
- s = cloud.list_servers()[0]
+ # Find a flavor with at least 512M of RAM
+ flavor = cloud.get_flavor_by_ram(512)
- # But you can also access the underlying python-*client objects
- cinder = cloud.cinder_client
- volumes = cinder.volumes.list()
- volume_id = [v for v in volumes if v['status'] == 'available'][0]['id']
- nova = cloud.nova_client
- print nova.volumes.create_server_volume(s['id'], volume_id, None)
- attachments = []
- print volume_id
- while not attachments:
- print "Waiting for attach to finish"
- time.sleep(1)
- attachments = cinder.volumes.get(volume_id).attachments
- print attachments
+ # Boot a server, wait for it to boot, and then do whatever is needed
+ # to get a public ip for it.
+ cloud.create_server(
+ 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
Platform: UNKNOWN
diff --git a/README.rst b/README.rst
index dcda824..33eda5c 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
-shade
-=====
+Introduction
+============
shade is a simple client library for operating OpenStack clouds. The
key word here is *simple*. Clouds can do many many many things - but there are
@@ -17,33 +17,29 @@ library, and adding logic and features that the OpenStack Infra team had
developed to run client applications at scale, it turned out that we'd written
nine-tenths of what we'd need to have a standalone library.
-example
--------
+Example
+=======
Sometimes an example is nice.
::
- from shade import *
- import time
+ import shade
+
+ # Initialize and turn on debug loggin
+ shade.simple_logging(debug=True)
# Initialize cloud
# Cloud configs are read with os-client-config
- cloud = openstack_cloud('mordred')
-
- # OpenStackCloud object has an interface exposing OpenStack services methods
- print cloud.list_servers()
- s = cloud.list_servers()[0]
-
- # But you can also access the underlying python-*client objects
- cinder = cloud.cinder_client
- volumes = cinder.volumes.list()
- volume_id = [v for v in volumes if v['status'] == 'available'][0]['id']
- nova = cloud.nova_client
- print nova.volumes.create_server_volume(s['id'], volume_id, None)
- attachments = []
- print volume_id
- while not attachments:
- print "Waiting for attach to finish"
- time.sleep(1)
- attachments = cinder.volumes.get(volume_id).attachments
- print attachments
+ cloud = shade.openstack_cloud(cloud='mordred')
+
+ # Upload an image to the cloud
+ image = cloud.create_image(
+ 'ubuntu-trusty', filename='ubuntu-trusty.qcow2', wait=True)
+
+ # Find a flavor with at least 512M of RAM
+ flavor = cloud.get_flavor_by_ram(512)
+
+ # Boot a server, wait for it to boot, and then do whatever is needed
+ # to get a public ip for it.
+ cloud.create_server(
+ 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
diff --git a/doc/source/coding.rst b/doc/source/coding.rst
new file mode 100644
index 0000000..40a49e7
--- /dev/null
+++ b/doc/source/coding.rst
@@ -0,0 +1,89 @@
+********************************
+Shade Developer Coding Standards
+********************************
+
+In the beginning, there were no guidelines. And it was good. But that
+didn't last long. As more and more people added more and more code,
+we realized that we needed a set of coding standards to make sure that
+the shade API at least *attempted* to display some form of consistency.
+
+Thus, these coding standards/guidelines were developed. Note that not
+all of shade adheres to these standards just yet. Some older code has
+not been updated because we need to maintain backward compatibility.
+Some of it just hasn't been changed yet. But be clear, all new code
+*must* adhere to these guidelines.
+
+Below are the patterns that we expect Shade developers to follow.
+
+API Methods
+===========
+
+- When an API call acts on a resource that has both a unique ID and a
+ name, that API call should accept either identifier with a name_or_id
+ parameter.
+
+- All resources should adhere to the get/list/search interface that
+ control retrieval of those resources. E.g., `get_image()`, `list_images()`,
+ `search_images()`.
+
+- Resources should have `create_RESOURCE()`, `delete_RESOURCE()`,
+ `update_RESOURCE()` API methods (as it makes sense).
+
+- For those methods that should behave differently for omitted or None-valued
+ parameters, use the `_utils.valid_kwargs` decorator. Notably: all Neutron
+ `update_*` functions.
+
+- Deleting a resource should return True if the delete succeeded, or False
+ if the resource was not found.
+
+Exceptions
+==========
+
+All underlying client exceptions must be captured and converted to an
+`OpenStackCloudException` or one of its derivatives.
+
+Client Calls
+============
+
+All underlying client calls (novaclient, swiftclient, etc.) must be
+wrapped by a Task object.
+
+Returned Resources
+==================
+
+Complex objects returned to the caller must be a dict type. The
+methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this.
+
+As of this writing, those two methods are returning Bunch objects, which help
+to maintain backward compatibility with a time when shade returned raw
+objects. Bunch allows the returned resource to act as *both* an object
+and a dict. Use of Bunch objects will eventually be deprecated in favor
+of just pure dicts, so do not depend on the Bunch object functionality.
+Expect a pure dict type.
+
+Nova vs. Neutron
+================
+
+- Recognize that not all cloud providers support Neutron, so never
+ assume it will be present. If a task can be handled by either
+ Neutron or Nova, code it to be handled by either.
+
+- For methods that accept either a Nova pool or Neutron network, the
+ parameter should just refer to the network, but documentation of it
+ should explain about the pool. See: `create_floating_ip()` and
+ `available_floating_ip()` methods.
+
+Tests
+=====
+
+- New API methods *must* have unit tests!
+
+- Functional tests should be added, when possible.
+
+- In functional tests, always use unique names (for resources that have this
+ attribute) and use it for clean up (see next point).
+
+- In functional tests, always define cleanup functions to delete data added
+ by your test, should something go wrong. Data removal should be wrapped in
+ a try except block and try to delete as many entries added by the test as
+ possible.
diff --git a/doc/source/future.rst b/doc/source/future.rst
new file mode 100644
index 0000000..61c1a4a
--- /dev/null
+++ b/doc/source/future.rst
@@ -0,0 +1,176 @@
+************************
+Future Design Discussion
+************************
+
+This document discusses a new approach to the Shade library and how
+we might wish for it to operate in a future, not-yet-developed version.
+It presents a more object oriented approach, and design decisions that
+we have learned and decided on while working on the current version.
+
+Object Design
+=============
+
+Shade is a library for managing resources, not for operating APIs. As such,
+it is the resource in question that is the primary object and not the service
+that may or may not provide that resource, much as we may feel warm and fuzzy
+to one of the services.
+
+Every resource at minimum has CRUD functions. Additionally, every resource
+action should have a "do this task blocking" or "request that the cloud start
+this action and give me a way to check its status" The creation and deletion
+of Resources will be handled by a ResourceManager that is attached to the Cloud
+::
+
+ class Cloud:
+ ResourceManager<Server> server
+ servers = server
+ ResourceManager<FloatingIp> floating_ip
+ floating_ips = floating_ip
+ ResourceManager<Image> image
+ images = image
+ ResourceManager<Role> role
+ roles = role
+ ResourceManager<Volume> volume
+ volumes = volume
+
+getting, listing and searching
+------------------------------
+
+In addition to creating a resource, there are different ways of getting your
+hands on a resource. A `get`, a `list` and a `search`.
+
+`list` has the simplest semantics - it takes no parameters and simply returns
+a list of all of the resources that exist.
+
+`search` takes a set of parameters to match against and returns a list of
+resources that match the parameters given. If no resources match, it returns
+an empty list.
+
+`get` takes the same set of parameters that `search` takes, but will only ever
+return a single matching resource or None. If multiple resources are matched,
+an exception will be raised.
+
+::
+
+ class ResourceManager<Resource>:
+ def get -> Resource
+ def list -> List<Resource>
+ def search -> List<Resource>
+ def create -> Resource
+
+Cloud and ResourceManager interface
+===================================
+
+All ResourceManagers should accept a cache object passed in to their constructor
+and should additionally pass that cache object to all Resource constructors.
+The top-level cloud should create the cache object, then pass it to each of
+the ResourceManagers when it creates them.
+
+Client connection objects should exist and be managed at the Cloud level. A
+backreference to the OpenStack cloud should be passed to every resource manager
+so that ResourceManagers can get hold of the ones they need. For instance,
+an Image ResourceManager would potentially need access to both the glance_client
+and the swift_client.
+
+::
+
+ class ResourceManager
+ def __init__(self, cache, cloud)
+ class ServerManager(ResourceManager)
+ class OpenStackCloud
+ def __init__(self):
+ self.cache = dogpile.cache()
+ self.server = ServerManager(self.cache, self)
+ self.servers = self.server
+
+Any resources that have an association action - such as servers and
+floating_ips, should carry reciprocal methods on each resource with absolutely
+no difference in behavior.
+
+::
+
+ class Server(Resource):
+ def connect_floating_ip:
+ class FloatingIp(Resource):
+ def connect_server:
+
+Resource objects should have all of the accessor methods you'd expect, as well
+as any other interesting rollup methods or actions. For instance, since
+a keystone User can be enabled or disabled, one should expect that there
+would be an enable() and a disable() method, and that those methods will
+immediately operate the necessary REST apis. However, if you need to make 80
+changes to a Resource, 80 REST calls may or may not be silly, so there should
+also be a generic update() method which can be used to request the minimal
+amount of REST calls needed to update the attributes to the requested values.
+
+Resource objects should all have a to_dict method which will return a plain
+flat dictionary of their attributes.
+
+::
+
+ class Resource:
+ def update(**new_values) -> Resource
+ def delete -> None, throws on error
+
+Readiness
+---------
+
+`create`, `get`, and `attach` can return resources that are not yet ready. Each
+method should take a `wait` and a `timeout` parameter, that will cause the
+request for the resource to block until it is ready. However, the user may
+want to poll themselves. Each resource should have an `is_ready` method which
+will return True when the resource is ready. The `wait` method then can
+actually be implemented in the base Resource class as an iterate timeout
+loop around calls to `is_ready`. Every Resource should also have an
+`is_failed` and an `is_deleted` method.
+
+Optional Behavior
+-----------------
+
+Not all clouds expose all features. For instance, some clouds do not have
+floating ips. Additionally, some clouds may have the feature but the user
+account does not, which is effectively the same thing.
+This should be handled in several ways:
+
+If the user explicitly requests a resource that they do not have access to,
+an error should be raised. For instance, if a user tries to create a floating
+ip on a cloud that does not expose that feature to them, shade should throw
+a "Your cloud does not let you do that" error.
+
+If the resource concept can be can be serviced by multiple possible services,
+shade should transparently try all of them. The discovery method should use
+the dogpile.cache mechanism so that it can be avoided on subsequent tries. For
+instance, if the user says "please upload this image", shade should figure
+out which sequence of actions need to be performed and should get the job done.
+
+If the resource isn't present on some clouds, but the overall concept the
+resource represents is, a different resource should present the concept. For
+instance, while some clouds do not have floating ips, if what the user wants
+is "a server with an IP" - then the fact that one needs to request a floating
+ip on some clouds is a detail, and the right thing for that to be is a quality
+of a server and managed by the server resource. A floating ip resource should
+really only be directly manipulated by the user if they were doing something
+very floating-ip specific, such as moving a floating ip from one server to
+another.
+
+In short, it should be considered a MASSIVE bug in shade if the shade user
+ever has to have in their own code "if cloud.has_capability("X") do_thing
+else do_other_thing" - since that construct conveys some resource that shade
+should really be able to model.
+
+Functional Interface
+====================
+
+shade should also provide a functional mapping to the object interface that
+does not expose the object interface at all. For instance, for a resource type
+`server`, one could expect the following.
+
+::
+
+ class OpenStackCloud:
+ def create_server
+ return self.server.create().to_dict()
+ def get_server
+ return self.server.get().to_dict()
+ def update_server
+ return self.server.get().update().to_dict()
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 15a603f..af9eaa3 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -4,7 +4,7 @@
contain the root `toctree` directive.
Welcome to shade's documentation!
-========================================================
+=================================
Contents:
@@ -14,6 +14,8 @@ Contents:
installation
usage
contributing
... 20178 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-shade.git
More information about the Python-modules-commits
mailing list