Skip to content

Commit 0d54593

Browse files
brianclinebriancline
committed
Various consistency updates in documentation.
- Consistent docblock formats - Standardize on Sphinx param formatting - Word wrap super long lines in README and LICENSE - Add some missing doc blocks - Add TODO items where doc blocks need explanation - Simplify some wording - Remove a few needless blank lines - Fix some minor comment formatting (PEP8 consistency)
1 parent 7be5529 commit 0d54593

14 files changed

Lines changed: 226 additions & 112 deletions

File tree

‎LICENSE‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,24 @@
11
Copyright (c) 2013, SoftLayer Technologies, Inc. All rights reserved.
22

3-
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
3+
Redistribution and use in source and binary forms, with or without modification,
4+
are permitted provided that the following conditions are met:
45

5-
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
6-
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
7-
* Neither SoftLayer Technologies, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
6+
* Redistributions of source code must retain the above copyright notice, this
7+
list of conditions and the following disclaimer.
8+
* Redistributions in binary form must reproduce the above copyright notice,
9+
this list of conditions and the following disclaimer in the documentation
10+
and/or other materials provided with the distribution.
11+
* Neither SoftLayer Technologies, Inc. nor the names of its contributors may be
12+
used to endorse or promote products derived from this software without
13+
specific prior written permission.
814

9-
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
15+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
16+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
19+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
22+
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
SoftLayer API Python Client
22
===========================
3-
This code provides a simple Python library to use the [SoftLayer API](http://sldn.softlayer.com/reference/softlayerapi).
3+
This code provides a simple Python library to use the
4+
[SoftLayer API](http://sldn.softlayer.com/reference/softlayerapi).
45

56
Overview
67
--------
78

8-
This library provides a simple interface to interact with SoftLayer's XML-RPC API and provides support for many of SoftLayer API's features like [object masks](http://sldn.softlayer.com/article/Using-Object-Masks-SoftLayerrAPI).
9+
This library provides a simple interface to interact with SoftLayer's XML-RPC
10+
API and provides support for many of SoftLayer API's features like
11+
[object masks](http://sldn.softlayer.com/article/Using-Object-Masks-SoftLayerAPI).
912

1013
Installation
1114
------------
@@ -21,14 +24,19 @@ python setup.py install
2124
```
2225

2326

24-
The most up to date version of this library can be found on the SoftLayer github public repositories: http://github.com/softlayer. Please post to the SoftLayer forums http://forums.softlayer.com/ or open a support ticket in the SoftLayer customer portal if you have any questions regarding use of this library.
27+
The most up to date version of this library can be found on the SoftLayer
28+
GitHub public repositories: http://github.com/softlayer. Please post to the
29+
SoftLayer forums http://forums.softlayer.com/ or open a support ticket in the
30+
SoftLayer customer portal if you have any questions regarding use of this
31+
library.
2532

2633
System Requirements
2734
-------------------
2835

2936
* This library has been tested on Python 2.5, 2.6, 2.7, 3.2 and 3.3.
3037
* A valid SoftLayer API username and key are required to call SoftLayer's API
31-
* A connection to SoftLayer's private network is required to connect to SoftLayer’s private network API endpoints.
38+
* A connection to SoftLayer's private network is required to connect to
39+
SoftLayer’s private network API endpoints.
3240

3341
Suggested Reading
3442
-----------------
@@ -40,4 +48,5 @@ Suggested Reading
4048

4149
Copyright
4250
---------
43-
This software is Copyright (c) 2013 [SoftLayer Technologies, Inc](http://www.softlayer.com/). See the bundled LICENSE file for more information.
51+
This software is Copyright (c) 2013 [SoftLayer Technologies, Inc](http://www.softlayer.com/).
52+
See the bundled LICENSE file for more information.

‎SoftLayer/API.py‎

Lines changed: 64 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -41,21 +41,21 @@
4141

4242

4343
class Client(object):
44-
"""A SoftLayer API client
44+
""" A SoftLayer API client.
4545
46-
:param service_name: The name of the SoftLayer API service to query.
47-
:param id: An optional object if if you're instantiating a particular
48-
SoftLayer_API object. Setting an id defines this client's
46+
:param service_name: the name of the SoftLayer API service to query
47+
:param integer id: an optional object ID if you're instantiating a
48+
particular SoftLayer_API object. Setting an ID defines this client's
4949
initialization parameter.
50-
:param username: An optional API username if you wish to bypass the
51-
package's built-in username.
52-
:param api_key: An optional API key if you wish to bypass the package's
53-
built in API key.
54-
:param endpoint_url: The API endpoint base URL you wish to connect to.
50+
:param username: an optional API username if you wish to bypass the
51+
package's built-in username
52+
:param api_key: an optional API key if you wish to bypass the package's
53+
built in API key
54+
:param endpoint_url: the API endpoint base URL you wish to connect to.
5555
Set this to API_PRIVATE_ENDPOINT to connect via SoftLayer's private
5656
network.
57-
:param timeout: Timeout for API requests
58-
:param verbose: When true, prints details about every HTTP request.
57+
:param integer timeout: timeout for API requests
58+
:param boolean verbose: prints details about every HTTP request if true
5959
6060
Usage::
6161
@@ -88,17 +88,22 @@ def __init__(self, service_name=None, id=None, username=None, api_key=None,
8888
self.timeout = timeout
8989

9090
def add_raw_header(self, name, value):
91-
""" Set HTTP headers for API calls
91+
""" Set HTTP headers for API calls.
9292
.. deprecated:: 2.0.0
93+
94+
:param name: the header name
95+
:param value: the header value
96+
9397
"""
9498
self._raw_headers[name] = value
9599

96100
def add_header(self, name, value):
97-
""" Set a SoftLayer API call header
101+
""" Set a SoftLayer API call header.
98102
.. deprecated:: 2.0.0
99103
100-
:param name: The name of the header to add
101-
:param value: The header to add.
104+
:param name: the header name
105+
:param value: the header value
106+
102107
"""
103108
name = name.strip()
104109
if name is None or name == '':
@@ -107,17 +112,17 @@ def add_header(self, name, value):
107112
self._headers[name] = value
108113

109114
def remove_header(self, name):
110-
""" Remove a SoftLayer API call header
115+
""" Remove a SoftLayer API call header.
111116
.. deprecated:: 2.0.0
112117
113-
:param name: The name of the header to remove.
114-
"""
118+
:param name: the header name
115119
120+
"""
116121
if name in self._headers:
117122
del self._headers[name.strip()]
118123

119124
def set_authentication(self, username, api_key):
120-
""" Set user and key to authenticate a SoftLayer API call
125+
""" Set user and key to authenticate a SoftLayer API call.
121126
.. deprecated:: 2.0.0
122127
123128
Use this method if you wish to bypass the API_USER and API_KEY class
@@ -126,37 +131,37 @@ def set_authentication(self, username, api_key):
126131
See U{https://manage.softlayer.com/Administrative/apiKeychain} for more
127132
information.
128133
129-
:param username: The username to authenticate an API call.
130-
:param api_key: The user's API key.
131-
"""
134+
:param username: the username to authenticate with
135+
:param api_key: the user's API key
132136
137+
"""
133138
self.add_header('authenticate', {
134139
'username': username.strip(),
135140
'apiKey': api_key.strip(),
136141
})
137142

138143
def set_init_parameter(self, id):
139-
""" Set an initialization parameter header
144+
""" Set an initialization parameter header.
140145
.. deprecated:: 2.0.0
141146
142147
Initialization parameters instantiate a SoftLayer API service object to
143148
act upon during your API method call. For instance, if your account has
144-
a server with id number 1234, then setting an initialization parameter
149+
a server with ID number 1234, then setting an initialization parameter
145150
of 1234 in the SoftLayer_Hardware_Server Service instructs the API to
146151
act on server record 1234 in your method calls.
147152
148153
See U{http://sldn.softlayer.com/article/Using-Initialization-Parameters-SoftLayer-API} # NOQA
149154
for more information.
150155
151-
:param id: The id number of the SoftLayer API object to instantiate
152-
"""
156+
:param id: the ID of the SoftLayer API object to instantiate
153157
158+
"""
154159
self.add_header(self._service_name + 'InitParameters', {
155160
'id': int(id)
156161
})
157162

158163
def set_object_mask(self, mask):
159-
""" Set an object mask to a SoftLayer API call
164+
""" Set an object mask to a SoftLayer API call.
160165
.. deprecated:: 2.0.0
161166
162167
Use an object mask to retrieve data related your API call's result.
@@ -166,9 +171,9 @@ def set_object_mask(self, mask):
166171
U{http://sldn.softlayer.com/article/Using-Object-Masks-SoftLayer-API}
167172
for more information.
168173
169-
:param mask: The object mask you wish to define
170-
"""
174+
:param mask: the object mask you wish to define
171175
176+
"""
172177
header = 'SoftLayer_ObjectMask'
173178

174179
if isinstance(mask, dict):
@@ -177,34 +182,42 @@ def set_object_mask(self, mask):
177182
self.add_header(header, {'mask': mask})
178183

179184
def set_result_limit(self, limit, offset=0):
180-
""" Set a result limit on a SoftLayer API call
185+
""" Set a result limit on a SoftLayer API call.
181186
.. deprecated:: 2.0.0
182187
183188
Many SoftLayer API methods return a group of results. These methods
184189
support a way to limit the number of results retrieved from the
185190
SoftLayer API in a way akin to an SQL LIMIT statement.
186191
187-
:param limit: The number of results to limit a SoftLayer API call to.
188-
:param offset: An optional offset to begin a SoftLayer API call's
189-
returned result at.
190-
"""
192+
:param limit: the number of results to limit a SoftLayer API call to
193+
:param offset: An optional offset at which to begin a SoftLayer API
194+
call's returned result
191195
196+
"""
192197
self.add_header('resultLimit', {
193198
'limit': int(limit),
194199
'offset': int(offset)
195200
})
196201

197202
def __getitem__(self, name):
198-
""" Get a SoftLayer Service
203+
""" Get a SoftLayer Service.
199204
200205
:param name: The name of the service. E.G. SoftLayer_Account
206+
201207
"""
202208
if not name.startswith(self._prefix):
203209
name = self._prefix + name
204210
return Service(self, name)
205211

206212
def __call__(self, service, method, *args, **kwargs):
207-
""" Place a SoftLayer API call """
213+
""" Perform a SoftLayer API call.
214+
215+
:param service: the name of the SoftLayer API service
216+
:param method: the method to call on the service
217+
:param dict *args: arguments for the specified method
218+
:param dict **kwargs: response-level arguments (limit, offset, etc.)
219+
220+
"""
208221
objectid = kwargs.get('id')
209222
objectmask = kwargs.get('mask')
210223
objectfilter = kwargs.get('filter')
@@ -252,7 +265,12 @@ def __call__(self, service, method, *args, **kwargs):
252265
verbose=self.verbose)
253266

254267
def __format_object_mask(self, objectmask, service):
255-
""" Formats new and old style object masks into proper headers. """
268+
""" Format new and old style object masks into proper headers.
269+
270+
:param objectmask: a string- or dict-based object mask
271+
:param service: a SoftLayer API service name
272+
273+
"""
256274
if isinstance(objectmask, dict):
257275
mheader = '%sObjectMask' % service
258276
else:
@@ -272,7 +290,11 @@ def __format_object_mask(self, objectmask, service):
272290
return {mheader: {'mask': objectmask}}
273291

274292
def __format_filter_dict(self, d):
275-
""" Formats given filters to the SL-API header """
293+
""" Format given filters to the SL-API header.
294+
295+
:param d: a dict of filters
296+
297+
"""
276298
for key, value in d.iteritems():
277299
if isinstance(value, dict):
278300
d[key] = self.__format_filter_dict(value)
@@ -282,14 +304,17 @@ def __format_filter_dict(self, d):
282304
return d
283305

284306
def __getattr__(self, name):
285-
""" Attempt a SoftLayer API call
307+
""" Attempt a SoftLayer API call.
286308
.. deprecated:: 2.0.0
287309
288310
Use this as a catch-all so users can call SoftLayer API methods
289311
directly against their client object. If the property or method
290312
relating to their client object doesn't exist then assume the user is
291313
attempting a SoftLayer API call and return a simple function that makes
292314
an XML-RPC call.
315+
316+
:param name: method name
317+
293318
"""
294319
if name in ["__name__", "__bases__"]:
295320
raise AttributeError("'Obj' object has no attribute '%s'" % name)

‎SoftLayer/CCI.py‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,19 @@ def __init__(self, *args):
1212

1313

1414
class CCIManager(object):
15-
""" Manage CCI's """
15+
""" Manage CCIs """
1616
def __init__(self, client):
1717
self.client = client
1818
self.account = client['Account']
1919
self.guest = client['Virtual_Guest']
2020

2121
def list_instances(self, hourly=True, monthly=True):
22+
""" Retrieve a list of all CCIs on the account.
23+
24+
:param boolean hourly: include hourly instances
25+
:param boolean monthly: include monthly instances
26+
27+
"""
2228
items = set([
2329
'id',
2430
'globalIdentifier',
@@ -84,11 +90,19 @@ def get_create_options(self):
8490
return self.guest.getCreateObjectOptions()
8591

8692
def cancel_instance(self, id):
93+
""" Cancel an instance immediately, deleting all its data.
94+
95+
:param integer id: the instance ID to cancel
96+
97+
"""
8798
return self.guest.deleteObject(id=id)
8899

89100
def reload_instance(self, id):
90-
""" Performs an OS reload of an instance with its current
91-
configuration. """
101+
""" Perform an OS reload of an instance with its current configuration.
102+
103+
:param integer id: the instance ID to reload
104+
105+
"""
92106
return self.guest.reloadCurrentOperatingSystemConfiguration(id=id)
93107

94108
def _generate_create_dict(
@@ -150,11 +164,11 @@ def _generate_create_dict(
150164
return data
151165

152166
def verify_create_instance(self, **kwargs):
153-
""" see _generate_create_dict """
167+
""" see _generate_create_dict """ # TODO: document this
154168
create_options = self._generate_create_dict(**kwargs)
155169
return self.guest.generateOrderTemplate(create_options)
156170

157171
def create_instance(self, **kwargs):
158-
""" see _generate_create_dict """
172+
""" see _generate_create_dict """ # TODO: document this
159173
create_options = self._generate_create_dict(**kwargs)
160174
return self.guest.createObject(create_options)

‎SoftLayer/CLI/environment.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@
99

1010

1111
class Environment(object):
12-
1312
# {'module_name': {'action': 'actionClass'}}
1413
plugins = {}
1514
aliases = {

0 commit comments

Comments
 (0)