Skip to content

Commit aa6c593

Browse files
sudorandomsudorandom
committed
Consistency Updates/Puts CLI more on par with API in docs
* Moves auth handlers to its own module * Made CLI and API landing pages in the docs. The primary index links to those pages and little else. * Links to both the CLI and API landing pages in the README.md * Fixes several spacing inconsistencies in the docopt sections
1 parent e4212b8 commit aa6c593

File tree

11 files changed

+137
-148
lines changed

11 files changed

+137
-148
lines changed

‎README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
SoftLayer API Python Client
22
===========================
33
SoftLayer API bindings for Python. For use with
4-
[SoftLayer's API](http://sldn.softlayer.com/reference/softlayerapi). For more
5-
documentation, [go here](http://softlayer.github.com/softlayer-api-python-client/).
4+
[SoftLayer's API](http://sldn.softlayer.com/reference/softlayerapi).
5+
6+
* [Module Documentation](http://softlayer.github.com/softlayer-api-python-client)
7+
* [API Documentation](http://softlayer.github.com/softlayer-api-python-client/client.html)
8+
* [CLI Documentation](http://softlayer.github.com/softlayer-api-python-client/cli.html)
69

710
This library provides a simple interface to interact with SoftLayer's XML-RPC
811
API and provides support for many of SoftLayer API's features like

‎SoftLayer/API.py‎

Lines changed: 5 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,14 @@
66
:copyright: (c) 2013, SoftLayer Technologies, Inc. All rights reserved.
77
:license: BSD, see LICENSE for more details.
88
"""
9-
from SoftLayer.consts import API_PUBLIC_ENDPOINT, API_PRIVATE_ENDPOINT, \
10-
USER_AGENT
11-
from SoftLayer.transport import make_xml_rpc_api_call
12-
from SoftLayer.exceptions import SoftLayerError
9+
from consts import API_PUBLIC_ENDPOINT, API_PRIVATE_ENDPOINT, USER_AGENT
10+
from transport import make_xml_rpc_api_call
11+
from exceptions import SoftLayerError
12+
from auth import BasicAuthentication, TokenAuthentication
1313
import os
1414

1515

16-
__all__ = ['Client', 'BasicAuthentication', 'TokenAuthentication',
17-
'API_PUBLIC_ENDPOINT', 'API_PRIVATE_ENDPOINT']
16+
__all__ = ['Client', 'API_PUBLIC_ENDPOINT', 'API_PRIVATE_ENDPOINT']
1817

1918
API_USERNAME = None
2019
API_KEY = None
@@ -30,46 +29,6 @@
3029
])
3130

3231

33-
class AuthenticationBase(object):
34-
def get_headers(self):
35-
raise NotImplementedError
36-
37-
38-
class TokenAuthentication(AuthenticationBase):
39-
def __init__(self, user_id, auth_token):
40-
self.user_id = user_id
41-
self.auth_token = auth_token
42-
43-
def get_headers(self):
44-
return {
45-
'authenticate': {
46-
'complexType': 'PortalLoginToken',
47-
'userId': self.user_id,
48-
'authToken': self.auth_token,
49-
}
50-
}
51-
52-
def __repr__(self):
53-
return "<TokenAuthentication: %s %s>" % (self.user_id, self.auth_token)
54-
55-
56-
class BasicAuthentication(AuthenticationBase):
57-
def __init__(self, username, api_key):
58-
self.username = username
59-
self.api_key = api_key
60-
61-
def get_headers(self):
62-
return {
63-
'authenticate': {
64-
'username': self.username,
65-
'apiKey': self.api_key,
66-
}
67-
}
68-
69-
def __repr__(self):
70-
return "<BasicAuthentication: %s>" % (self.username)
71-
72-
7332
class Client(object):
7433
""" A SoftLayer API client.
7534

‎SoftLayer/CLI/modules/bmetal.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -473,7 +473,7 @@ class CancelInstance(CLIRunnable):
473473
474474
Options:
475475
--immediate Cancels the instance immediately (instead of on the billing
476-
anniversary).
476+
anniversary).
477477
"""
478478

479479
action = 'cancel'

‎SoftLayer/CLI/modules/dns.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,16 @@
33
44
Manage DNS
55
6-
The available commands are:
7-
edit Update resource records (bulk/single)
6+
The available zone commands are:
87
create Create zone
8+
delete Delete zone
99
list List zones or a zone's records
10-
remove Remove resource records
11-
add Add resource record
1210
print Print zone in BIND format
13-
delete Delete zone
11+
12+
The available record commands are:
13+
add Add resource record
14+
edit Update resource records (bulk/single)
15+
remove Remove resource records
1416
"""
1517
# :copyright: (c) 2013, SoftLayer Technologies, Inc. All rights reserved.
1618
# :license: BSD, see LICENSE for more details.

‎SoftLayer/CLI/modules/hardware.py‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55
Manage hardware
66
77
The available commands are:
8-
list List hardware devices
9-
detail Retrieve hardware details
10-
reload Perform an OS reload
11-
cancel Cancel a dedicated server.
8+
list List hardware devices
9+
detail Retrieve hardware details
10+
reload Perform an OS reload
11+
cancel Cancel a dedicated server.
1212
cancel-reasons Provides the list of possible cancellation reasons
13-
network Manage network settings
13+
network Manage network settings
1414
list-chassis Provide a list of all chassis available for ordering
1515
create-options Display a list of creation options for a specific chassis
16-
create Create a new dedicated server
16+
create Create a new dedicated server
1717
1818
For several commands, <identifier> will be asked for. This can be the id,
1919
hostname or the ip address for a piece of hardware.
@@ -35,9 +35,9 @@ class ListHardware(CLIRunnable):
3535
List hardware servers on the acount
3636
3737
Examples:
38-
sl hardware list --datacenter=dal05
39-
sl hardware list --network=100 --domain=example.com
40-
sl hardware list --tags=production,db
38+
sl hardware list --datacenter=dal05
39+
sl hardware list --network=100 --domain=example.com
40+
sl hardware list --tags=production,db
4141
4242
Options:
4343
--sortby=ARG Column to sort by. options: id, datacenter, host, cores,
@@ -180,8 +180,8 @@ class HardwareReload(CLIRunnable):
180180
Reload the OS on a hardware server based on its current configuration
181181
182182
Optional:
183-
-i, --postinstall=URI Post-install script to download
184-
(Only HTTPS executes, HTTP leaves file in /root)
183+
-i, --postinstall=URI Post-install script to download
184+
(Only HTTPS executes, HTTP leaves file in /root)
185185
"""
186186

187187
action = 'reload'
@@ -261,7 +261,7 @@ class NetworkHardware(CLIRunnable):
261261
262262
Options:
263263
--speed=SPEED Port speed. 0 disables the port.
264-
[Options: 0, 10, 100, 1000, 10000]
264+
[Options: 0, 10, 100, 1000, 10000]
265265
--public Public network
266266
--private Private network
267267
"""

‎SoftLayer/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@
1818

1919
from API import * # NOQA
2020
from managers import * # NOQA
21-
from SoftLayer.exceptions import * # NOQA
21+
from exceptions import * # NOQA
22+
from auth import * # NOQA
2223

2324
__title__ = 'SoftLayer'
2425
__version__ = VERSION

‎SoftLayer/auth.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
"""
2+
SoftLayer.auth
3+
~~~~~~~~~~~~~~
4+
Module with the supported auth mechanisms for the SoftLayer API
5+
6+
:copyright: (c) 2013, SoftLayer Technologies, Inc. All rights reserved.
7+
:license: BSD, see LICENSE for more details.
8+
"""
9+
__all__ = ['BasicAuthentication', 'TokenAuthentication', 'AuthenticationBase']
10+
11+
12+
class AuthenticationBase(object):
13+
def get_headers(self):
14+
raise NotImplementedError
15+
16+
17+
class TokenAuthentication(AuthenticationBase):
18+
def __init__(self, user_id, auth_token):
19+
self.user_id = user_id
20+
self.auth_token = auth_token
21+
22+
def get_headers(self):
23+
return {
24+
'authenticate': {
25+
'complexType': 'PortalLoginToken',
26+
'userId': self.user_id,
27+
'authToken': self.auth_token,
28+
}
29+
}
30+
31+
def __repr__(self):
32+
return "<TokenAuthentication: %s %s>" % (self.user_id, self.auth_token)
33+
34+
35+
class BasicAuthentication(AuthenticationBase):
36+
def __init__(self, username, api_key):
37+
self.username = username
38+
self.api_key = api_key
39+
40+
def get_headers(self):
41+
return {
42+
'authenticate': {
43+
'username': self.username,
44+
'apiKey': self.api_key,
45+
}
46+
}
47+
48+
def __repr__(self):
49+
return "<BasicAuthentication: %s>" % (self.username)

‎docs/api/client.rst‎

Lines changed: 40 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,23 @@
11
.. _client:
22

33

4-
Developer Interface
5-
===================
6-
This is the primary API client to make API calls. It deals with constructing and executing XML-RPC calls against the SoftLayer API.
4+
API Documentation
5+
=================
6+
This is the primary API client to make API calls. It deals with constructing and executing XML-RPC calls against the SoftLayer API. Below are some links that will help to use the SoftLayer API.
7+
8+
.. toctree::
9+
10+
SoftLayer API Documentation <http://sldn.softlayer.com/reference/softlayerapi>
11+
Source on Github <https://github.com/softlayer/softlayer-api-python-client>
12+
13+
::
14+
15+
>>> import SoftLayer
16+
>>> client = SoftLayer.Client(username="username", api_key="api_key")
17+
>>> resp = client['Account'].getObject()
18+
>>> resp['companyName']
19+
'Your Company'
20+
721

822
Getting Started
923
---------------
@@ -121,33 +135,44 @@ API Reference
121135
:undoc-members:
122136

123137

138+
Managers
139+
--------
140+
::
141+
142+
>>> from SoftLayer import CCIManager, Client
143+
>>> client = Client(...)
144+
>>> cci = CCIManager(client)
145+
>>> cci.list_instances()
146+
[...]
147+
148+
Managers mask out a lot of the complexities of using the API into classes that provide a simpler interface to various services. These are higher-level interfaces to the SoftLayer API.
149+
150+
.. toctree::
151+
:maxdepth: 2
152+
:glob:
153+
154+
managers/*
155+
156+
124157
Backwards Compatibility
125158
-----------------------
126-
If you've been using the older Python client (<2.0), you'll be happy to know that the old API is still currently working. However, you should deprecate use of the old stuff. Below is an example of the old API converted to the new one.
127-
128-
.. automodule:: SoftLayer.deprecated
129-
:members:
130-
:undoc-members:
159+
As of 3.0, the old API methods and parameters no longer work. Below are examples of converting the old API to the new one.
131160

161+
**Get the IP address for an account**
132162
::
133163

164+
# Old
134165
import SoftLayer.API
135166
client = SoftLayer.API.Client('SoftLayer_Account', None, 'username', 'api_key')
136167
client.set_object_mask({'ipAddresses' : None})
137168
client.set_result_limit(10, offset=10)
138169
client.getObject()
139170

140-
... changes to ...
141-
::
142-
171+
# New
143172
import SoftLayer
144173
client = SoftLayer.Client(username='username', api_key='api_key')
145174
client['Account'].getObject(mask="mask[ipAddresses]", limit=10, offset=0)
146175

147-
Deprecated APIs
148-
^^^^^^^^^^^^^^^
149-
Below are examples of how the old usages to the new API.
150-
151176
**Importing the module**
152177
::
153178

‎docs/api/managers.rst‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎docs/cli.rst‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,13 @@
33
Command-line Interface
44
======================
55

6-
The SoftLayer command line interface is available via the `sl` command available in your `PATH`. The `sl` command is a reference implementation of SoftLayer API bindings for python and how to efficiently make API calls.
6+
The SoftLayer command line interface is available via the `sl` command available in your `PATH`. The `sl` command is a reference implementation of SoftLayer API bindings for python and how to efficiently make API calls. See the :ref:`usage-examples` section to see how to discover all of the functionality not fully documented here.
7+
8+
.. toctree::
9+
:maxdepth: 2
10+
11+
cli/cci
12+
cli/dev
713

814

915
Configuration Setup
@@ -55,6 +61,7 @@ The only required fields are `username` and `api_key`. You can optionally also/e
5561
[softlayer]
5662
endpoint_url = https://api.softlayer.com/xmlrpc/v3/
5763

64+
.. _usage-examples:
5865

5966
Usage Examples
6067
--------------

0 commit comments

Comments
 (0)