Feature/controllers (#15)

* Implement controller method

To determine which controllers will be supported by the api we implement
a method which returns all controller names.
To test the module we also add some simple tests that can be run against
an existing phpIPAM installation.
Here you only need to create a `server.yml` in `tests/vars`. Simply copy
the `server.yml.exampl` and fill out with your server data.
To secure your secrets we add `server.yml` to `.gitignore`

* release v0.0.1

Author: cmeissner

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# project specific ignores
+tests/vars/server.yml

README.md

@@ -1,7 +1,18 @@
-# phpypam
+# phpypam: Python API client library for phpIPAM installation
 
-Python API client library for [phpIPAM](https://phpipam.net/) installations.
+phpypam is intended to be a complete library for speaking with phpIPAM API.
 
-## Installation
+Using `phpypam` is as easy as using the UI.
 
-tbd
+```python
+import phpypam
+
+pi = phpypam.api(
+  url='https://ipam.example.com',
+  app_id='ansible',
+  username='apiuser',
+  password='apiP455wd',
+  ssl_verify=True
+)
+pi.get_entity(controller='sections')
+```

phpypam/core/api.py

@@ -129,3 +129,10 @@ def update_entity(self, controller, data, **kwargs):
             _path = '{}/{}'.format(_path, _controller_path)
 
         return self._query(token=self._api_token, method=PATCH, path=_path, data=data)
+
+    def controllers(self):
+        result = self._query(token=self._api_token, method=OPTIONS, path='/')
+
+        controllers = ({v for ctrl in result['controllers'] for (k, v) in ctrl.items() if k == 'rel'})
+
+        return controllers

requirements-dev.txt

@@ -5,3 +5,4 @@ requests
 inflection
 twine
 setuptools
+PyYAML

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="phpypam",
-    version="0.0.1",
+    version="0.0.2",
     author="Christian Meißner",
     author_email="Christian Meißner <[email protected]>",
     description="Python API client library for phpIPAM installation",
@@ -18,8 +18,9 @@
     classifiers=[
         "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
         "Programming Language :: Python :: 3",
-        "Operating System :: OS Independent",
+        "Intended Audience :: Developers",
     ],
+    keywords='api phpipam',
     python_requires='>=3.6',
     install_requires=[
         'requests (>=2.21,<3.0)',

tests/api_connection.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+
+import phpypam
+import json
+import yaml
+
+with open('tests/vars/server.yml') as c:
+    server = yaml.safe_load(c)
+
+from phpypam import PHPyPAMEntityNotFoundException
+
+
+if __name__ == '__main__':
+    pi = phpypam.api(
+        url=server['url'],
+        app_id=server['app_id'],
+        username=server['username'],
+        password=server['password'],
+        ssl_verify=True
+    )
+
+    my_section = dict(
+        name='foobar',
+        description='new section',
+        permissions='{"3":"1","2":"2"}'
+    )
+    try:
+        entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
+    except PHPyPAMEntityNotFoundException:
+        print('create entity')
+        entity = pi.create_entity(controller='sections', data=my_section)
+        entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
+
+    entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
+    print(json.dumps(entity, indent=4, sort_keys=True))
+
+    my_section['description'] = 'new description'
+
+    print('update entity')
+    pi.update_entity(controller='sections', controller_path=entity['id'], data=my_section)
+
+    entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
+    print(json.dumps(entity, indent=4, sort_keys=True))
+
+    print('delete entity')
+    pi.delete_entity(controller='sections', controller_path=entity['id'])

tests/controllers.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+
+import phpypam
+import json
+import yaml
+
+with open('tests/vars/server.yml') as c:
+    server = yaml.safe_load(c)
+
+if __name__ == '__main__':
+    pi = phpypam.api(
+        url=server['url'],
+        app_id=server['app_id'],
+        username=server['username'],
+        password=server['password'],
+        ssl_verify=True
+    )
+
+    controllers = pi.controllers()
+    print(controllers)

tests/vars/server.yml.example

@@ -0,0 +1,5 @@
+# Parameter for all tests
+url: 'https://ipam.example.com'
+app_id: my_app
+username: user
+password: p455w0rd