Object Models¶
Environment module¶
Support for an Environment resource in Skytap.
In nearly every case, you’ll access an Environment via the
Environments
object:
envs = skytap.Environments()
for environment in envs:
print (environment.name)
You can access anything from an environment that Skytap includes in their API. Most of these can be access directly as attributes of the given Environment object:
environment = skytap.Environments()[12345]
print(environment.name)
print(environment.json)
Some data conversions are handled for you. Specifically:
- Dates are converted into
datetime
objects, likecreated_at
. - The
vms
list is loaded into askytap.models.Vms
class. - The
notes
are put into askytap.models.Notes
class. - The
user_data
is put into askytap.models.UserData
class.
There’s also the ability to change the runstate of the environment through
the function change_state()
:
environment = skytap.Environments()[12345]
environment.change_state('suspended')
# Passing `True` will wait for the suspend to complete
# before returning to the script:
environment.change_state('suspended', True)
The various state change options also have easy aliases available to them:
run()
halt()
suspend()
reset()
stop()
Passing True to any of these will also cause the script to wait until the action is completed by Skytap.
Note
Some pieces of a given environment, specifically notes and user_data, are only available via additional calls to the API. These fields will not exist when first creating the environments object, but any direct access to those fields will trigger the API call behind the scenes.
This is important if you’re listing the entire contents (say, sending it to a JSON) - these fields won’t be included if you haven’t made that direct access.
This is by design to conserve API calls as most usage doesn’t need or use those fields.
-
class
skytap.models.Environment.
Environment
(env_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
,skytap.framework.Suspendable.Suspendable
One Skytap environment.
-
__getattr__
(key)¶ Load values for anything that doesn’t get loaded by default.
For user_data and notes, a secondary API call is needed. Only make that call when the info is requested.
-
delete
()¶ Delete the environment.
In general, it’d seem wise not to do this very often.
-
Group module¶
Support for Skytap groups.
-
class
skytap.models.Group.
Group
(initial_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One Skytap Group.
-
__getattr__
(key)¶ Load values for anything that doesn’t get loaded by default.
For user_data and notes, a secondary API call is needed. Only make that call when the info is requested.
-
add_user
(user)¶ Add a
User
to the group.Parameters: user (int) – id of the user to add.
Raises: TypeError
– If user is not anint
.KeyError
– If user is not inUsers
list.
Returns: True if the user was added.
Return type: bool
Example
>>> groups = skytap.Groups() >>> users = skytap.Users() >>> for u in users: ... groups[12345].add(u.id)
-
delete
()¶ Delete the group.
-
remove_user
(user)¶ Remove a
user
from the group.Parameters: user (int) – id of the user to remove.
Raises: TypeError
– If user is not anint
.KeyError
– If user is not inUsers
list.
Returns: True if the user was removed.
Return type: bool
Example
>>> groups = skytap.Groups() >>> groups[1234].remove_user(12345)
-
Note module¶
Support for a single note in a Skytap environment or vm.
-
class
skytap.models.Note.
Note
(note_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One note.
-
__str__
()¶ Represent the Note as a string.
-
Notes module¶
Support for notes that are attached to VMs and environments.
-
class
skytap.models.Notes.
Notes
(note_json, env_url)¶ Bases:
skytap.models.SkytapGroup.SkytapGroup
A collection of notes.
-
add
(note)¶ Add one note.
Parameters: note (str) – The note text to add. Returns: The response from Skytap, typically the new note. Return type: str
-
delete
(note)¶ Delete one note.
Parameters: note – The Note
to delete.Returns: The response from Skytap. Return type: str Raises: TypeError
– If note is not a Note object.
-
delete_all
()¶ Delete all notes.
Returns: count of deleted notes. Return type: int Use with care!
-
oldest
()¶ Return the oldest note.
Returns: The oldest note. Return type: Note Used most often to delete the oldest note.
Example:
notes = skytap.Environtments().first.notes print(notes.oldest().text) # notes.delete(notes.oldest()) # most common use case.
-
refresh
()¶ Refresh the notes.
Raises: KeyError
– if the Notes object doesn’t have a url attribute for some reason.Go back to Skytap and get the notes again. Useful when you’ve changed the notes and to make sure you’re current.
-
Project module¶
Support for Projects.
-
class
skytap.models.Project.
Project
(project_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One Skytap project.
Quota module¶
Support for Skytap quotas.
-
class
skytap.models.Quota.
Quota
(quota_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One piece of quota information.
-
__str__
()¶ Represent object as a string.
-
SkytapGroup module¶
Base object to handle groups of Skytap objects.
-
class
skytap.models.SkytapGroup.
SkytapGroup
¶ Bases:
skytap.framework.ApiClient.ApiClient
,six.Iterator
Base object for use with Skytap resource groups.
A SkytapGroup is essentially a set of SkytapResource objects. This allows us to more easily interact with ‘VMs’ as collections of VM objects. A list or dictionary could do much of this, but this allows us to also batch API calls intelligently (since many calls return a ‘group’ of data) and run other operations on multiple objects, when appropriate, like doing something across every VM inside an environment.
-
__contains__
(key)¶ Check if the object contains an element.
-
__getitem__
(key)¶ Return a data element from self.data.
-
__iter__
()¶ Allow this object to be iterated over.
-
__len__
()¶ Get length of the object.
-
__next__
()¶ Get the next item in iteration.
-
__str__
()¶ Represent the group as a string.
It’d be good to consider something more clever here, but returning the object back as a JSON also doesn’t seem unreasonable as a way to make this data accessible to other processes.
-
find
(search)¶ Return a list of objects, based on the search criteria.
This looks for matching ids if the search is a number, or searches the name if search is a string.
Parameters: search (int or str) – What to search for. Returns: Any environments matching the search criteria. Return type: List Example
>>> envs = skytap.Environments().search('testing')
-
first
()¶ Return the first record in the list.
Mainly used to get a single arbitrary object for testing.
Returns: An object from the list. Return type: SkytapResource
-
json
()¶ Convert our list into a json.
-
keys
()¶ Return the keys from the group list.
-
load_list_from_api
(url, target, params=None)¶ Load something from the Skytap API and fill this object.
Parameters: - url (str) – The Skytap URL to load (‘/v2/users’).
- target – The
SkytapResource
type to load (For example: ‘User’) - params (dict) – Any URL parameters to add to URL.
This should look like, in the child object:
self.load_list_from_api('/v2/projects', Project)
-
load_list_from_json
(json_list, target, url=None, params=None)¶ Load items from a json list and fill this object.
Parameters: - json_list (list) – The list to load the items from.
- target – The
SkytapResource
type to load (for example: ‘User’)
This should look like, in the child object:
-
main
(argv)¶ What to do when called from the command line.
This function is usually accessed via the command line:
python -m skytap.Environments
but can be used to return quick sets of formatted JSON:
>>> print(skytap.Environments().main())
Anything passed to the function will be searched for:
python -m skytap.Users fozzy
and:
>>> print(skytap.Users().main('scooter'))
Parameters: argv (list) – Command line arguments Returns: Formatted JSON of the request. Return type: str
-
refresh
()¶ Reload our data.
-
SkytapResource module¶
Base class for all Skytap Resources.
-
class
skytap.models.SkytapResource.
SkytapResource
(initial_json)¶ Bases:
object
Represents one Skytap Resource - a VM, Environment, User, whatever.
-
__contains__
(key)¶ Check if this resource has a particular key in its data.
-
__eq__
(other)¶ Compare the resource to another one, helpful for sorting.
-
__getattr__
(key)¶ Access custom attributes.
This allows us to access members of self.data as if they’re attributes of the resource. This transparently extends the object with all of the keys returned from the Skytap API without each resource having to do anything special except for exception cases.
-
__gt__
(other)¶ Compare the resource to another one, helpful for sorting.
-
__hash__
()¶ Represent the resource as a hash.
-
__int__
()¶ Represent the resource as an int.
-
__lt__
(other)¶ Compare the resource to another one, helpful for sorting.
-
__str__
()¶ Represent the resource as a string.
-
json
()¶ Convert the object to JSON.
-
refresh
()¶ Refresh the data in our object, if we have a URL to pull from.
-
Template module¶
Support for an Template resource in Skytap.
-
class
skytap.models.Template.
Template
(tmp_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One Skytap template.
-
__getattr__
(key)¶ Load values for anything that doesn’t get loaded by default.
For user_data, a secondary API call is needed. Only make that call when the info is requested.
-
User module¶
Support for a User resource in Skytap.
-
class
skytap.models.User.
User
(user_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One Skytap User resource.
-
delete
(transfer_user)¶ Delete the user.
-
UserData module¶
Support for the UserData resource in Skytap.
Specifically, this is for custom (‘user data’) that’s applied to an environment or VM. This data can be text or, in the context of using it with this Skytap script, it can also be JSON or YAML and will then be re-parsed.
This allows users to put data into a VM user data block and it’ll filter down and be accessible to this script. We use this to expose variables to the user like shutdown time and other automation pieces.
-
class
skytap.models.UserData.
UserData
(contents, env_url)¶ Bases:
skytap.models.SkytapResource.SkytapResource
UserData object to handle custom user data for a Skytap object.
This typically would be for a VM or Environment.
-
__str__
()¶ Express the userdata as a string.
-
add
(key, value)¶ Add value to environment’s userdata.
Parameters: - key (str) – The name of the value’s key.
- value (str) – The value to add.
Returns: The response from Skytap, or “{}”.
Return type: str
-
add_line
(text, line=-1)¶ Add line to environment’s userdata.
Parameters: - text (str) – line of text to be added. (Required)
- line (int) – line number to add to. If too large, default to last.
Returns: The response from Skytap.
Return type: str
-
delete
(key)¶ Delete key/value from environment’s userdata.
Parameters: key (str) – The name of key to delete, along with value Returns: The response from Skytap, or “{}”. Return type: str
-
delete_line
(line)¶ Delete line from environment’s userdata.
Parameters: line (int) – line number to delete. Returns: The response from Skytap. Return type: str
-
get_line
(line)¶ Return content of line from environment’s userdata.
Parameters: line (int) – line number to get. Returns: The content of the line, or “”. Return type: str
-
Vm module¶
Support for a VM resource in Skytap.
-
class
skytap.models.Vm.
Vm
(vm_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
,skytap.framework.Suspendable.Suspendable
One Skytap VM.
-
__getattr__
(key)¶ Load values for anything that doesn’t get loaded by default.
For user_data, notes, and interfaces, a secondary API call is needed. Only make that call when the info is requested.
-
delete
()¶ Delete a VM.
In general, it’d seem wise not to do this very often.
-
Vms module¶
Support for Skytap VMs.
-
class
skytap.models.Vms.
Vms
(vms_json, env_url)¶ Bases:
skytap.models.SkytapGroup.SkytapGroup
A list of VMs.
Vpn module¶
Support for Skytap VPNs.
-
class
skytap.models.Vpn.
Vpn
(vpn_json)¶ Bases:
skytap.models.SkytapResource.SkytapResource
One Skytap VPN object.