diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a82eb151..460e436e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,9 +3,9 @@ We are happy to accept contributions to softlayer-python. Please follow the guidelines below. -* Sign our contributor agreement (CLA) You can find the [CLA here](./docs/cla-individual.md). +* Sign our contributor agreement (CLA) You can find the [CLA here](./docs/dev/cla-individual.md). -* If you're contributing on behalf of your employer we'll need a signed copy of our corporate contributor agreement (CCLA) as well. You can find the [CCLA here](./docs/cla-corporate.md). +* If you're contributing on behalf of your employer we'll need a signed copy of our corporate contributor agreement (CCLA) as well. You can find the [CCLA here](./docs/dev/cla-corporate.md). * Fork the repo, make your changes, and open a pull request. diff --git a/SoftLayer/managers/block.py b/SoftLayer/managers/block.py index 260403214..62dccf827 100644 --- a/SoftLayer/managers/block.py +++ b/SoftLayer/managers/block.py @@ -17,7 +17,12 @@ class BlockStorageManager(utils.IdentifierMixin, object): - """Manages Block Storage volumes.""" + """Manages SoftLayer Block Storage volumes. + + See product information here: http://www.softlayer.com/block-storage + + :param SoftLayer.API.BaseClient client: the client instance + """ def __init__(self, client): self.configuration = {} diff --git a/SoftLayer/managers/cdn.py b/SoftLayer/managers/cdn.py index d93f148ad..994ab8fab 100644 --- a/SoftLayer/managers/cdn.py +++ b/SoftLayer/managers/cdn.py @@ -15,7 +15,13 @@ class CDNManager(utils.IdentifierMixin, object): - """Manage CDN accounts.""" + """Manage CDN accounts and content. + + See product information here: + http://www.softlayer.com/content-delivery-network + + :param SoftLayer.API.BaseClient client: the client instance + """ def __init__(self, client): self.client = client diff --git a/SoftLayer/managers/dns.py b/SoftLayer/managers/dns.py index c2524800b..c1b7b3b60 100644 --- a/SoftLayer/managers/dns.py +++ b/SoftLayer/managers/dns.py @@ -11,9 +11,11 @@ class DNSManager(utils.IdentifierMixin, object): - """Domain Name System manager. + """Manage SoftLayer DNS. - :param SoftLayer.API.Client client: the client instance + See product information here: http://www.softlayer.com/DOMAIN-SERVICES + + :param SoftLayer.API.BaseClient client: the client instance """ diff --git a/SoftLayer/managers/firewall.py b/SoftLayer/managers/firewall.py index 4ed350b46..097231ee0 100644 --- a/SoftLayer/managers/firewall.py +++ b/SoftLayer/managers/firewall.py @@ -29,9 +29,11 @@ def has_firewall(vlan): class FirewallManager(utils.IdentifierMixin, object): - """Manages firewalls. + """Manages SoftLayer firewalls - :param SoftLayer.API.Client client: the API client instance + See product information here: http://www.softlayer.com/firewalls + + :param SoftLayer.API.BaseClient client: the client instance """ diff --git a/SoftLayer/managers/hardware.py b/SoftLayer/managers/hardware.py index 3a77d0572..83d742618 100644 --- a/SoftLayer/managers/hardware.py +++ b/SoftLayer/managers/hardware.py @@ -19,7 +19,7 @@ class HardwareManager(utils.IdentifierMixin, object): - """Manage hardware devices. + """Manage SoftLayer hardware servers. Example:: @@ -32,7 +32,9 @@ class HardwareManager(utils.IdentifierMixin, object): client = SoftLayer.Client() mgr = SoftLayer.HardwareManager(client) - :param SoftLayer.API.Client client: an API client instance + See product information here: http://www.softlayer.com/bare-metal-servers + + :param SoftLayer.API.BaseClient client: the client instance :param SoftLayer.managers.OrderingManager ordering_manager: an optional manager to handle ordering. If none is provided, one will be diff --git a/SoftLayer/managers/image.py b/SoftLayer/managers/image.py index 57389bd89..81eee9282 100644 --- a/SoftLayer/managers/image.py +++ b/SoftLayer/managers/image.py @@ -13,9 +13,12 @@ class ImageManager(utils.IdentifierMixin, object): - """Manages server images. + """Manages SoftLayer server images. - :param SoftLayer.API.Client client: an API client instance + See product information here: + https://knowledgelayer.softlayer.com/topic/image-templates + + :param SoftLayer.API.BaseClient client: the client instance """ def __init__(self, client): diff --git a/SoftLayer/managers/iscsi.py b/SoftLayer/managers/iscsi.py index 9c07a15da..85df7d401 100644 --- a/SoftLayer/managers/iscsi.py +++ b/SoftLayer/managers/iscsi.py @@ -10,7 +10,14 @@ class ISCSIManager(utils.IdentifierMixin, object): - """Manages iSCSI storages.""" + """Manages SoftLayer iSCSI storage accounts. + + See product information here: + https://knowledgelayer.softlayer.com/topic/iscsi + + :param SoftLayer.API.BaseClient client: the client instance + + """ def __init__(self, client): self.configuration = {} diff --git a/SoftLayer/managers/load_balancer.py b/SoftLayer/managers/load_balancer.py index 47fa362d5..854c8c620 100644 --- a/SoftLayer/managers/load_balancer.py +++ b/SoftLayer/managers/load_balancer.py @@ -9,9 +9,12 @@ class LoadBalancerManager(utils.IdentifierMixin, object): - """Manages load balancers. + """Manages SoftLayer load balancers. + + See product information here: http://www.softlayer.com/load-balancing + + :param SoftLayer.API.BaseClient client: the client instance - :param SoftLayer.API.Client client: the API client instance """ def __init__(self, client): diff --git a/SoftLayer/managers/messaging.py b/SoftLayer/managers/messaging.py index 8c273b6b5..8c0a0519b 100644 --- a/SoftLayer/managers/messaging.py +++ b/SoftLayer/managers/messaging.py @@ -23,7 +23,7 @@ class QueueAuth(requests.auth.AuthBase): - """Message Queue authentication for requests. + """SoftLayer Message Queue authentication for requests. :param endpoint: endpoint URL :param username: SoftLayer username @@ -72,7 +72,13 @@ def __call__(self, resp): class MessagingManager(object): - """Manage SoftLayer Message Queue.""" + """Manage SoftLayer Message Queue accounts. + + See product information here: http://www.softlayer.com/message-queue + + :param SoftLayer.API.BaseClient client: the client instance + + """ def __init__(self, client): self.client = client diff --git a/SoftLayer/managers/metadata.py b/SoftLayer/managers/metadata.py index 38aa4db5c..0246d7f70 100644 --- a/SoftLayer/managers/metadata.py +++ b/SoftLayer/managers/metadata.py @@ -35,7 +35,10 @@ class MetadataManager(object): - """Provides an interface for the metadata service. + """Provides an interface for the SoftLayer metadata service. + + See product information here: + http://sldn.softlayer.com/reference/services/SoftLayer_Resource_Metadata This provides metadata about the resourse it is called from. See `METADATA_ATTRIBUTES` for full list of attributes. @@ -51,6 +54,8 @@ class MetadataManager(object): >>> meta.get('fqdn') 'test.example.com' + :param SoftLayer.API.BaseClient client: the client instance + """ attribs = METADATA_MAPPING diff --git a/SoftLayer/managers/network.py b/SoftLayer/managers/network.py index 904b91f92..690da99b5 100644 --- a/SoftLayer/managers/network.py +++ b/SoftLayer/managers/network.py @@ -36,7 +36,13 @@ class NetworkManager(object): - """Manage Networks.""" + """Manage SoftLayer network objects: VLANs, subnets, IPs and rwhois + + See product information here: http://www.softlayer.com/networking + + :param SoftLayer.API.BaseClient client: the client instance + + """ def __init__(self, client): self.client = client self.account = client['Account'] diff --git a/SoftLayer/managers/object_storage.py b/SoftLayer/managers/object_storage.py index 71da8d227..395c6e2fe 100644 --- a/SoftLayer/managers/object_storage.py +++ b/SoftLayer/managers/object_storage.py @@ -16,7 +16,13 @@ class ObjectStorageManager(object): - """Manager for Object Storage.""" + """Manager for SoftLayer Object Storage accounts. + + See product information here: http://www.softlayer.com/object-storage + + :param SoftLayer.API.BaseClient client: the client instance + + """ def __init__(self, client): self.client = client diff --git a/SoftLayer/managers/ordering.py b/SoftLayer/managers/ordering.py index f7026b9e1..798a8464e 100644 --- a/SoftLayer/managers/ordering.py +++ b/SoftLayer/managers/ordering.py @@ -8,9 +8,9 @@ class OrderingManager(object): - """Manages hardware devices. + """Manager to help ordering via the SoftLayer API. - :param SoftLayer.API.Client client: an API client instance + :param SoftLayer.API.BaseClient client: the client instance """ def __init__(self, client): diff --git a/SoftLayer/managers/sshkey.py b/SoftLayer/managers/sshkey.py index e7f424f33..a294d5257 100644 --- a/SoftLayer/managers/sshkey.py +++ b/SoftLayer/managers/sshkey.py @@ -10,9 +10,12 @@ class SshKeyManager(utils.IdentifierMixin, object): - """Manages account SSH keys. + """Manages account SSH keys in SoftLayer. - :param SoftLayer.API.Client client: an API client instance + See product information here: + https://knowledgelayer.softlayer.com/procedure/ssh-keys + + :param SoftLayer.API.BaseClient client: the client instance """ def __init__(self, client): diff --git a/SoftLayer/managers/ssl.py b/SoftLayer/managers/ssl.py index ef407def1..f0d75dc37 100644 --- a/SoftLayer/managers/ssl.py +++ b/SoftLayer/managers/ssl.py @@ -8,9 +8,9 @@ class SSLManager(object): - """Manages SSL certificates. + """Manages SSL certificates in SoftLayer. - :param SoftLayer.API.Client client: an API client instance + See product information here: http://www.softlayer.com/ssl-certificates Example:: @@ -23,6 +23,8 @@ class SSLManager(object): client = SoftLayer.Client() mgr = SoftLayer.SSLManager(client) + :param SoftLayer.API.BaseClient client: the client instance + """ def __init__(self, client): diff --git a/SoftLayer/managers/ticket.py b/SoftLayer/managers/ticket.py index d95f5c83c..553f32600 100644 --- a/SoftLayer/managers/ticket.py +++ b/SoftLayer/managers/ticket.py @@ -10,9 +10,12 @@ class TicketManager(utils.IdentifierMixin, object): - """Manages support Tickets. + """Manages SoftLayer support tickets. + + See product information here: http://www.softlayer.com/support + + :param SoftLayer.API.BaseClient client: the client instance - :param SoftLayer.API.Client client: an API client instance """ def __init__(self, client): @@ -46,8 +49,7 @@ def get_ticket(self, ticket_id): """Get details about a ticket. :param integer ticket_id: the ticket ID - :returns: A dictionary containing a large amount of information about - the specified ticket. + :returns: dict -- information about the specified ticket """ mask = ('id, title, assignedUser[firstName, lastName],status,' @@ -91,7 +93,8 @@ def upload_attachment(self, ticket_id=None, file_path=None, :param string file_name: The name of the attachment shown in the ticket - :returns The uploaded attachment + + :returns: dict -- The uploaded attachment """ file_content = None with open(file_path, 'rb') as attached_file: @@ -109,7 +112,8 @@ def attach_hardware(self, ticket_id=None, hardware_id=None): :param integer ticket_id: the id of the ticket to attach to :param integer hardware_id: the id of the hardware to attach - :returns The new ticket attachment + + :returns: dict -- The new ticket attachment """ return self.ticket.addAttachedHardware(hardware_id, id=ticket_id) @@ -118,7 +122,8 @@ def attach_virtual_server(self, ticket_id=None, virtual_id=None): :param integer ticket_id: the id of the ticket to attach to :param integer virtual_id: the id of the virtual server to attach - :returns The new ticket attachment + + :returns: dict -- The new ticket attachment """ return self.ticket.addAttachedVirtualGuest(virtual_id, id=ticket_id) @@ -127,7 +132,8 @@ def detach_hardware(self, ticket_id=None, hardware_id=None): :param ticket_id: the id of the ticket to detach from :param hardware_id: the id of the hardware to detach - :return: Whether the detachment was successful + + :returns: bool -- Whether the detachment was successful """ return self.ticket.removeAttachedHardware(hardware_id, id=ticket_id) @@ -136,6 +142,7 @@ def detach_virtual_server(self, ticket_id=None, virtual_id=None): :param ticket_id: the id of the ticket to detach from :param virtual_id: the id of the virtual server to detach - :return: Whether the detachment was successful + + :returns: bool -- Whether the detachment was successful """ return self.ticket.removeAttachedVirtualGuest(virtual_id, id=ticket_id) diff --git a/SoftLayer/managers/vs.py b/SoftLayer/managers/vs.py index 25090e078..b16faf2ca 100644 --- a/SoftLayer/managers/vs.py +++ b/SoftLayer/managers/vs.py @@ -17,13 +17,9 @@ class VSManager(utils.IdentifierMixin, object): - """Manages Virtual Servers. + """Manages SoftLayer Virtual Servers. - :param SoftLayer.API.Client client: an API client instance - :param SoftLayer.managers.OrderingManager ordering_manager: an optional - manager to handle ordering. - If none is provided, one will be - auto initialized. + See product information here: http://www.softlayer.com/virtual-servers Example:: @@ -36,6 +32,13 @@ class VSManager(utils.IdentifierMixin, object): client = SoftLayer.Client() mgr = SoftLayer.VSManager(client) + + :param SoftLayer.API.BaseClient client: the client instance + :param SoftLayer.managers.OrderingManager ordering_manager: an optional + manager to handle ordering. + If none is provided, one will be + auto initialized. + """ def __init__(self, client, ordering_manager=None): diff --git a/docs/cla-corporate.md b/docs/dev/cla-corporate.md similarity index 100% rename from docs/cla-corporate.md rename to docs/dev/cla-corporate.md diff --git a/docs/cla-individual.md b/docs/dev/cla-individual.md similarity index 100% rename from docs/cla-individual.md rename to docs/dev/cla-individual.md diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 4814920b0..21bb0d403 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -20,7 +20,7 @@ Code Organization Setting Up A Dev Environment ---------------------------- Before working with the SoftLayer Python API client source, we strongly -recommend that you know how to use Python's virtualization environment, +recommend that you know how to use Python's virtual environment, `virtualenv `_. Virtualenv allows you to create isolated Python environments that are individually tailored to particular development projects. Each environment can have its own set of @@ -62,9 +62,13 @@ the root of the source tree: tox In addition to testing different versions of Python, tox checks for common -mistakes in the code using `Flake8 `_. -You should eliminate the simple errors reported by Flake8 before submitting -your code. +mistakes in the code using `Flake8 `_ and `pylint `_. +You should eliminate the linting errors that are reported before submitting +your code. You can run only the linting checks by using this command: + +:: + + tox -eanalysis The project's configuration instructs tox to test against many different versions of Python. A tox test will use as many of those as it can find on your @@ -73,7 +77,7 @@ you point the `Travis `_ continuous integration tool at your GitHub fork. Travis will run the test against the full suite of Python versions every time you push new code. -Using tox to running the tests in multiple environments can be very time +Using tox to run tests in multiple environments can be very time consuming. If you wish to quickly run the tests in your own environment, you may do so using `py.test `_. The command to do that is: @@ -109,7 +113,7 @@ The primary docs are built at Style ----- -This project follows :pep:`8` and most of the style suggestions that pyflakes +This project tries to follow :pep:`8` and most of the style suggestions that pyflakes recommends. Run `Flake8 `_ regularly. Flake8, with project-specific exceptions, can be run by using tox: @@ -120,12 +124,15 @@ Flake8, with project-specific exceptions, can be run by using tox: Contributing ------------ -Contributing to the Python API bindings follows the fork-pull-request model on +Contributing to the Python API bindings follows the `fork-pull-request model `_ on `GitHub `_. The project uses GitHub's `issue tracker `_ and `pull requests `_ to manage source control, bug fixes and new feature development regarding the API -bindings and the CLI. +bindings and the CLI. In order to contribute, we require that you sign a contributer agreemenet: + +* Sign our contributor agreement (CLA) You can find the :download:`CLA here `. +* If you're contributing on behalf of your employer we'll need a signed copy of our corporate contributor agreement (CCLA) as well. You can find the :download:`CCLA here `. Developer Resources