Skip to content

Commit d9b5a2a

Browse files
sudorandomsudorandom
committed
Adds CLI docs from GH Wiki to Sphinx
* Fixes small issue with fabric publish_docs script. * Adds link to documentation in the README.md
1 parent 81c0da8 commit d9b5a2a

9 files changed

Lines changed: 556 additions & 46 deletions

File tree

‎README.md‎

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

97
This library provides a simple interface to interact with SoftLayer's XML-RPC
108
API and provides support for many of SoftLayer API's features like
11-
[object masks](http://sldn.softlayer.com/article/Using-Object-Masks-SoftLayerAPI).
9+
[object masks](http://sldn.softlayer.com/article/Using-Object-Masks-SoftLayerAPI).
10+
It also contains a command-line interface that can be used to access various
11+
SoftLayer services using the API.
1212

1313
Installation
1414
------------
@@ -32,19 +32,11 @@ library.
3232

3333
System Requirements
3434
-------------------
35-
3635
* This library has been tested on Python 2.5, 2.6, 2.7, 3.2 and 3.3.
3736
* A valid SoftLayer API username and key are required to call SoftLayer's API
3837
* A connection to SoftLayer's private network is required to connect to
3938
SoftLayer’s private network API endpoints.
4039

41-
Suggested Reading
42-
-----------------
43-
44-
* [Our wiki](https://github.com/softlayer/softlayer-api-python-client/wiki)
45-
* [The API](https://github.com/softlayer/softlayer-api-python-client/wiki/API-Usage)
46-
* [CLI tool](https://github.com/softlayer/softlayer-api-python-client/wiki/Cli)
47-
4840

4941
Copyright
5042
---------

‎SoftLayer/API.py‎

Lines changed: 12 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -186,24 +186,14 @@ def set_result_limit(self, limit, offset=0):
186186
def __getitem__(self, name):
187187
""" Get a SoftLayer Service.
188188
189-
:param name: The name of the service. E.G. SoftLayer_Account
189+
:param name: The name of the service. E.G. Account
190190
191-
"""
192-
if not name.startswith(self._prefix):
193-
name = self._prefix + name
194-
return Service(self, name)
195-
196-
def __call__(self, *args, **kwargs):
197-
""" Perform a SoftLayer API call.
198-
199-
:param service: the name of the SoftLayer API service
200-
:param method: the method to call on the service
201-
:param \*args: same optional arguments that ``Client.call`` takes
202-
:param \*\*kwargs: same optional keyword arguments that ``Client.call``
203-
takes
191+
Usage:
192+
>>> client['Account']
193+
<Service: Account>
204194
205195
"""
206-
return self.call(*args, **kwargs)
196+
return Service(self, name)
207197

208198
def call(self, service, method, *args, **kwargs):
209199
""" Make a SoftLayer API call
@@ -229,6 +219,9 @@ def call(self, service, method, *args, **kwargs):
229219
if kwargs.get('iter'):
230220
return self.iter_call(service, method, *args, **kwargs)
231221

222+
if not service.startswith(self._prefix):
223+
service = self._prefix + service
224+
232225
objectid = kwargs.get('id')
233226
objectmask = kwargs.get('mask')
234227
objectfilter = kwargs.get('filter')
@@ -274,6 +267,8 @@ def call(self, service, method, *args, **kwargs):
274267
http_headers=http_headers, timeout=self.timeout,
275268
verbose=self.verbose)
276269

270+
__call__ = call
271+
277272
def iter_call(self, service, method,
278273
chunk=100, limit=None, offset=0, *args, **kwargs):
279274
""" A generator that deals with paginating through results.
@@ -402,6 +397,8 @@ def call(self, name, *args, **kwargs):
402397
"""
403398
return self.client.call(self.name, name, *args, **kwargs)
404399

400+
__call__ = call
401+
405402
def iter_call(self, name, *args, **kwargs):
406403
""" A generator that deals with paginating through results.
407404
@@ -422,8 +419,6 @@ def iter_call(self, name, *args, **kwargs):
422419
"""
423420
return self.client.iter_call(self.name, name, *args, **kwargs)
424421

425-
__call__ = call
426-
427422
def __getattr__(self, name):
428423
if name in ["__name__", "__bases__"]:
429424
raise AttributeError("'Obj' object has no attribute '%s'" % name)

‎SoftLayer/tests/API/client_tests.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -273,12 +273,12 @@ def test_mask_call_invalid_mask(self, make_api_call):
273273
@patch('SoftLayer.API.Client.iter_call')
274274
def test_iterate(self, _iter_call):
275275
self.client['SERVICE'].METHOD(iter=True)
276-
_iter_call.assert_called_with('SoftLayer_SERVICE', 'METHOD', iter=True)
276+
_iter_call.assert_called_with('SERVICE', 'METHOD', iter=True)
277277

278278
@patch('SoftLayer.API.Client.iter_call')
279279
def test_service_iter_call(self, _iter_call):
280280
self.client['SERVICE'].iter_call('METHOD')
281-
_iter_call.assert_called_with('SoftLayer_SERVICE', 'METHOD')
281+
_iter_call.assert_called_with('SERVICE', 'METHOD')
282282

283283
@patch('SoftLayer.API.Client.call')
284284
def test_iter_call(self, _call):

‎docs/api/client.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ Developer Interface
55
===================
66
This is the primary API client to make API calls. It deals with constructing and executing XML-RPC calls against the SoftLayer API.
77

8-
Client setup
9-
------------
8+
Getting Started
9+
---------------
1010
You can pass in your username and api_key when creating a SoftLayer client instance. However, you can set these in the environmental variables 'SL_USERNAME' and 'SL_API_KEY'
1111

1212
Creating a client instance by passing in the username/api_key:

‎docs/cli.rst‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
.. _cli:
2+
3+
Command-line Interface
4+
======================
5+
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.
7+
8+
9+
Configuration Setup
10+
-------------------
11+
To check the configuration, you can use `sl config show`.
12+
::
13+
14+
$ sl config setup
15+
Username: username
16+
API Key: oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha
17+
Endpoint URL [https://api.softlayer.com/xmlrpc/v3/]:
18+
Are you sure you want to write settings to "/path/to/home/.softlayer"? [y/N]: y
19+
20+
To check the configuration, you can use `sl config show`.
21+
::
22+
23+
$ sl config show
24+
:..............:..................................................................:
25+
: Name : Value :
26+
:..............:..................................................................:
27+
: Username : username :
28+
: API Key : oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha :
29+
: Endpoint URL : https://api.softlayer.com/xmlrpc/v3/ :
30+
:..............:..................................................................:
31+
32+
33+
Configuration File Details
34+
--------------------------
35+
The CLI loads your settings from a number of different locations.
36+
37+
* Enviorment variables (SL_USERNAME, SL_API_KEY)
38+
* Config file (~/.softlayer)
39+
* Or argument (-C/path/to/config or --config=/path/to/config)
40+
41+
The configuration file is INI based and requires the `softlayer` section to be present.
42+
The only required fields are `username` and `api_key`. You can optionally also/exclusively supply the `endpoint_url` as well.
43+
44+
*Full config*
45+
::
46+
47+
[softlayer]
48+
username = username
49+
api_key = oyVmeipYQCNrjVS4rF9bHWV7D75S6pa1fghFl384v7mwRCbHTfuJ8qRORIqoVnha
50+
endpoint_url = http://api.softlayer.com/xmlrpc/v3/
51+
52+
*exclusive url*
53+
::
54+
55+
[softlayer]
56+
endpoint_url = http://api.softlayer.com/xmlrpc/v3/
57+
58+
59+
Usage Examples
60+
--------------
61+
To discover the available commands, simply type `sl`.
62+
::
63+
64+
$ sl
65+
usage: sl <command> [<args>...]
66+
sl help <command>
67+
sl [-h | --help]
68+
69+
SoftLayer Command-line Client
70+
71+
The available commands are:
72+
firewall Firewall rule and security management
73+
image Manages compute and flex images
74+
ssl Manages SSL
75+
cci Manage, delete, order compute instances
76+
dns Manage DNS
77+
config View and edit configuration for this tool
78+
metadata Get details about this machine. Also available with 'my' and 'meta'
79+
nas View NAS details
80+
iscsi View iSCSI details
81+
82+
See 'sl help <command>' for more information on a specific command.
83+
84+
To use most commands your SoftLayer username and api_key need to be configured.
85+
The easiest way to do that is to use: 'sl config setup'
86+
87+
As you can see, there are a number of commands. To look at the list of subcommands for Cloud Compute Instances, type `sl <command>`. For example:
88+
::
89+
90+
$ sl cci
91+
usage: sl cci [<command>] [<args>...] [options]
92+
93+
Manage, delete, order compute instances
94+
95+
The available commands are:
96+
network Manage network settings
97+
create Order and create a CCI
98+
(see `sl cci create-options` for choices)
99+
manage Manage active CCI
100+
list List CCI's on the account
101+
detail Output details about a CCI
102+
dns DNS related actions to a CCI
103+
cancel Cancel a running CCI
104+
create-options Output available available options when creating a CCI
105+
reload Reload the OS on a CCI based on its current configuration
106+
107+
Standard Options:
108+
-h --help Show this screen
109+
110+
Finally, we can make an actual call. Let's list out the CCIs on our account using `sl cci list`.
111+
112+
::
113+
114+
$ sl cci list
115+
:.........:............:....................:.......:........:................:..............:....................:
116+
: id : datacenter : host : cores : memory : primary_ip : backend_ip : active_transaction :
117+
:.........:............:....................:.......:........:................:..............:....................:
118+
: 1234567 : dal05 : test.example.com : 4 : 4G : 12.34.56 : 65.43.21 : - :
119+
:.........:............:....................:.......:........:................:..............:....................:
120+
121+
Most commands will take in additional options/arguments. To see all available actions, use `--help`.
122+
::
123+
124+
$ sl cci list --help
125+
usage: sl cci list [--hourly | --monthly] [--sortby=SORT_COLUMN] [--tags=TAGS]
126+
[options]
127+
128+
List CCIs
129+
130+
Examples:
131+
sl cci list --datacenter=dal05
132+
sl cci list --network=100 --cpu=2
133+
sl cci list --memory='>= 2048'
134+
sl cci list --tags=production,db
135+
136+
Options:
137+
--sortby=ARG Column to sort by. options: id, datacenter, host,
138+
Cores, memory, primary_ip, backend_ip
139+
140+
Filters:
141+
--hourly Show hourly instances
142+
--monthly Show monthly instances
143+
-H --hostname=HOST Host portion of the FQDN. example: server
144+
-D --domain=DOMAIN Domain portion of the FQDN example: example.com
145+
-c --cpu=CPU Number of CPU cores
146+
-m --memory=MEMORY Memory in mebibytes (n * 1024)
147+
-d DC, --datacenter=DC datacenter shortname (sng01, dal05, ...)
148+
-n MBPS, --network=MBPS Network port speed in Mbps
149+
--tags=ARG Only show instances that have one of these tags.
150+
Comma-separated. (production,db)
151+
152+
For more on filters see 'sl help filters'
153+
154+
Standard Options:
155+
--format=ARG Output format. [Options: table, raw] [Default: table]
156+
-C FILE --config=FILE Config file location. [Default: ~/.softlayer]
157+
-h --help Show this screen

0 commit comments

Comments
 (0)