README.rst
1SoftLayer API Python Client
2===========================
3.. image:: https://github.com/softlayer/softlayer-python/workflows/Tests/badge.svg
4 :target: https://github.com/softlayer/softlayer-python/actions?query=workflow%3ATests
5
6.. image:: https://github.com/softlayer/softlayer-python/workflows/documentation/badge.svg
7 :target: https://github.com/softlayer/softlayer-python/actions?query=workflow%3Adocumentation
8
9.. image:: https://landscape.io/github/softlayer/softlayer-python/master/landscape.svg
10 :target: https://landscape.io/github/softlayer/softlayer-python/master
11
12.. image:: https://badge.fury.io/py/SoftLayer.svg
13 :target: http://badge.fury.io/py/SoftLayer
14
15.. image:: https://coveralls.io/repos/github/softlayer/softlayer-python/badge.svg?branch=master
16 :target: https://coveralls.io/github/softlayer/softlayer-python?branch=master
17
18.. image:: https://snapcraft.io//slcli/badge.svg
19 :target: https://snapcraft.io/slcli
20
21
22This library provides a simple Python client to interact with `SoftLayer's
23XML-RPC API <https://softlayer.github.io/reference/softlayerapi>`_.
24
25A command-line interface is also included and can be used to manage various
26SoftLayer products and services.
27
28
29Documentation
30-------------
31Documentation for the Python client is available at `Read the Docs <https://softlayer-python.readthedocs.io/en/latest/index.html>`_ .
32
33Additional API documentation can be found on the SoftLayer Development Network:
34
35* `SoftLayer API reference
36 <https://sldn.softlayer.com/reference/softlayerapi>`_
37* `Object mask information and examples
38 <https://sldn.softlayer.com/article/object-masks>`_
39* `Code Examples
40 <https://sldn.softlayer.com/python/>`_
41
42Installation
43------------
44Install via pip:
45
46.. code-block:: bash
47
48 $ pip install softlayer
49
50
51Or you can install from source. Download source and run:
52
53.. code-block:: bash
54
55 $ python setup.py install
56
57Another (safer) method of installation is to use the published snap. Snaps are available for any Linux OS running snapd, the service that runs and manage snaps. Snaps are "auto-updating" packages and will not disrupt the current versions of libraries and software packages on your Linux-based system. To learn more, please visit: https://snapcraft.io/
58
59To install the slcli snap:
60
61.. code-block:: bash
62
63 $ sudo snap install slcli
64
65 (or to get the latest release)
66
67 $ sudo snap install slcli --edge
68
69
70
71
72The most up-to-date version of this library can be found on the SoftLayer
73GitHub public repositories at http://github.com/softlayer. For questions regarding the use of this library please post to Stack Overflow at https://stackoverflow.com/ and your posts with “SoftLayer” so our team can easily find your post. To report a bug with this library please create an Issue on github.
74
75InsecurePlatformWarning Notice
76------------------------------
77This library relies on the `requests <http://docs.python-requests.org/>`_ library to make HTTP requests. On Python versions below Python 2.7.9, requests has started emitting a security warning (InsecurePlatformWarning) due to insecurities with creating SSL connections. To resolve this, upgrade to Python 2.7.9+ or follow the instructions here: http://stackoverflow.com/a/29099439.
78
79Basic Usage
80-----------
81
82- `The Complete Command Directory <https://softlayer-python.readthedocs.io/en/latest/cli_directory/>`_
83
84Advanced Usage
85--------------
86
87You can automatically set some parameters via environment variables with by using the SLCLI prefix. For example
88
89.. code-block:: bash
90
91 $ export SLCLI_VERBOSE=3
92
93 $ export SLCLI_FORMAT=json
94
95 $ slcli vs list
96
97is equivalent to
98
99.. code-block:: bash
100
101 $ slcli -vvv --format=json vs list
102
103Getting Help
104------------
105Bugs and feature requests about this library should have a `GitHub issue <https://github.com/softlayer/softlayer-python/issues>`_ opened about them.
106
107Issues with the Softlayer API itself should be addressed by opening a ticket.
108
109
110Examples
111--------
112
113A curated list of examples on how to use this library can be found at `SLDN <https://softlayer.github.io/python/>`_
114
115Debugging
116---------
117To get the exact API call that this library makes, you can do the following.
118
119For the CLI, just use the -vvv option. If you are using the REST endpoint, this will print out a curl command that you can use, if using XML, this will print the minimal python code to make the request without the softlayer library.
120
121.. code-block:: bash
122
123 $ slcli -vvv vs list
124
125
126If you are using the library directly in python, you can do something like this.
127
128.. code-block:: python
129
130 import SoftLayer
131 import logging
132
133 class invoices():
134
135 def __init__(self):
136 self.client = SoftLayer.Client()
137 debugger = SoftLayer.DebugTransport(self.client.transport)
138 self.client.transport = debugger
139
140 def main(self):
141 mask = "mask[id]"
142 account = self.client.call('Account', 'getObject', mask=mask);
143 print("AccountID: %s" % account['id'])
144
145 def debug(self):
146 for call in self.client.transport.get_last_calls():
147 print(self.client.transport.print_reproduceable(call))
148
149 if __name__ == "__main__":
150 main = example()
151 main.main()
152 main.debug()
153
154
155
156System Requirements
157-------------------
158* Python 3.5, 3.6, 3.7, 3.8, or 3.9.
159* A valid SoftLayer API username and key.
160* A connection to SoftLayer's private network is required to use
161 our private network API endpoints.
162
163Python 2.7 Support
164------------------
165As of version 5.8.0 SoftLayer-Python will no longer support python2.7, which is `End Of Life as of 2020 <https://www.python.org/dev/peps/pep-0373/>`_ .
166If you cannot install python 3.6+ for some reason, you will need to use a version of softlayer-python <= 5.7.2
167
168
169
170Python Packages
171---------------
172* ptable >= 0.9.2
173* click >= 7
174* requests >= 2.20.0
175* prompt_toolkit >= 2
176* pygments >= 2.0.0
177* urllib3 >= 1.24
178
179Copyright
180---------
181This software is Copyright (c) 2016-2021 SoftLayer Technologies, Inc.
182
183See the bundled LICENSE file for more information.
184
