Merge branch 'dev'

Author: aruhier

.travis.yml

@@ -2,14 +2,16 @@ language: python
 
 matrix:
   include:
-    - python: 3.6-dev
+    - python: 3.7-dev
       env: TOXENV=coveralls
     - python: 3.4
       env: TOXENV=py34
     - python: 3.5-dev
       env: TOXENV=py35
     - python: 3.6-dev
       env: TOXENV=py36
+    - python: 3.7-dev
+      env: TOXENV=py37
 
 sudo: required
 dist: trusty

README.md

@@ -125,6 +125,26 @@ It is possible to get a subresourses of an object, and/or specify a query:
 
 Any `kwargs` (here `q=`) is used as a GET parameter for the request.
 
+#### Foreign keys
+
+Foreign keys are handle automatically by the mapper.
+
+```python
+>>> site = next(netbox_mapper.get())
+>>> print(site.region.name)
+"Some region"
+```
+
+When accessing to `site.region`, a query will be done to fetch the foreign
+object. It will then be saved in cache to avoid unnecessary queries for next
+accesses.
+
+To refresh an object and its foreign keys, just do:
+
+```python
+>>> site = next(site.get())
+```
+
 ### POST
 
 Use the `kwargs` of a mapper to send a post request and create a new object:
@@ -134,6 +154,9 @@ Use the `kwargs` of a mapper to send a post request and create a new object:
 <NetboxMapper>  # corresponding to the new created object
 ```
 
+If a mapper is sent as parameter, `post()` will automatically take its id.
+However, it will not update the foreign object.
+
 ### PUT
 
 Use `put()` in a child mapper to update the resource upstream by reflecting
@@ -143,7 +166,7 @@ the changes made in the object attributes:
 >>> child_mapper = netbox_mapper.get(1)
 >>> child_mapper.name = "another name"
 >>> child_mapper.put()
-<NetboxMapper>  # corresponding to the updated object
+<requests>  # requests object containing the netbox response
 ```
 
 ### PATCH

netboxapi/exceptions.py

@@ -1,4 +1,7 @@
-
-
 class ForbiddenAsChildError(Exception):
     pass
+
+
+class ForbiddenAsPassiveMapperError(Exception):
+    def __init__(self):
+        super().__init__("No action is possible for this type of mapper")

netboxapi/mapper.py

@@ -1,6 +1,12 @@
+import logging
+import re
+import requests
 
 from .api import NetboxAPI
-from .exceptions import ForbiddenAsChildError
+from .exceptions import ForbiddenAsChildError, ForbiddenAsPassiveMapperError
+
+
+logger = logging.getLogger("netboxapi")
 
 
 class NetboxMapper():
@@ -9,6 +15,10 @@ def __init__(self, netbox_api, app_name, model, route=None):
         self.__app_name__ = app_name
         self.__model__ = model
         self.__upstream_attrs__ = []
+        self.__foreign_keys__ = []
+
+        #: cache for foreign keys properties
+        self._fk_cache = {}
 
         self._route = (
             route or
@@ -31,6 +41,10 @@ def get(self, *args, **kwargs):
             >>> netbox_mapper.get("1", "racks", q="name_to_filter")
 
             Will do a request to "/dcim/sites/1/racks/?q=name_to_filter"
+
+        Some specific routes will not return objects with ID (this one for
+        example: `/ipam/prefixes/{id}/available-prefixes/`). In this case, no
+        mapper will be built from the result and it will be yield as received.
         """
         if args:
             route = self._route + "/".join(str(a) for a in args) + "/"
@@ -43,10 +57,15 @@ def get(self, *args, **kwargs):
 
         if isinstance(new_mappers_dict, dict):
             new_mappers_dict = [new_mappers_dict]
-        for d in new_mappers_dict:
-            yield self._build_new_mapper_from(
-                d, route + "{}/".format(d["id"])
-            )
+        try:
+            for d in new_mappers_dict:
+                yield self._build_new_mapper_from(
+                    d, route + "{}/".format(d["id"])
+                )
+        except KeyError:
+            # Result objects have no id, cannot build a mapper from them,
+            # yield them as received
+            yield from new_mappers_dict
 
     def post(self, **json):
         """
@@ -65,10 +84,30 @@ def post(self, **json):
 
         :returns: child_mapper: Mapper containing the created object
         """
+        for k, v in json.items():
+            if isinstance(v, NetboxMapper):
+                try:
+                    json[k] = v.id
+                except AttributeError:
+                    raise ValueError("Mapper {} has no id".format(k))
         new_mapper_dict = self.netbox_api.post(self._route, json=json)
-        route = self._route + "{}/".format(new_mapper_dict["id"])
-
-        return self._build_new_mapper_from(new_mapper_dict, route)
+        try:
+            return next(self.get(new_mapper_dict["id"]))
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                logger.debug(
+                    "Rare case of weird endpoint where object cannot be fetch "
+                    "after POST by using the same endpoint. Returning a "
+                    "mapper based on this answer instead of fetching the "
+                    "entire object."
+                    ""
+                    "Do not try to put this mapper as it will fail."
+                )
+                return self._build_new_mapper_from(
+                    new_mapper_dict,
+                    self._route + "{}/".format(new_mapper_dict["id"]),
+                    passive_mapper=True
+                )
 
     def put(self):
         """
@@ -83,17 +122,42 @@ def put(self):
             >>> child_mapper = netbox_mapper.get(1)
             >>> child_mapper.name = "another name"
             >>> child_mapper.put()
-            <child_mapper>
 
-        :returns: child_mapper: Mapper containing the updated object
+        :returns: request_reponse: requests object containing the netbox
+                                   response
         """
         assert getattr(self, "id", None) is not None, "self.id does not exist"
 
-        new_mapper_dict = self.netbox_api.put(self._route, json=self.to_dict())
-        return self._build_new_mapper_from(new_mapper_dict, self._route)
+        return self.netbox_api.put(self._route, json=self.to_dict())
 
     def to_dict(self):
-        return {a: getattr(self, a, None) for a in self.__upstream_attrs__}
+        serialize = {}
+        foreign_keys = self.__foreign_keys__.copy()
+        for a in self.__upstream_attrs__:
+            val = getattr(self, a, None)
+            if isinstance(val, dict):
+                if "value" in val and "label" in val:
+                    val = val["value"]
+            elif isinstance(val, NetboxMapper):
+                foreign_keys.append(a)
+                continue
+
+            serialize[a] = val
+
+        for fk in foreign_keys:
+            attr = getattr(self, fk, None)
+            if isinstance(attr, int):
+                serialize[fk] = attr
+                continue
+
+            try:
+                # check that attr is iterable
+                iter(attr)
+                serialize[fk] = [getattr(i, "id", None) for i in attr]
+            except TypeError:
+                serialize[fk] = getattr(attr, "id", None)
+
+        return serialize
 
     def delete(self, id=None):
         """
@@ -128,12 +192,76 @@ def delete(self, id=None):
         delete_route = self._route + "{}/".format(id) if id else self._route
         return self.netbox_api.delete(delete_route)
 
-    def _build_new_mapper_from(self, mapper_attributes, new_route):
-        mapper = type(self)(
+    def _build_new_mapper_from(
+            self, mapper_attributes, new_route, passive_mapper=False
+    ):
+        cls = NetboxPassiveMapper if passive_mapper else NetboxMapper
+        mapper_class = type(
+            "NetboxMapper_{}_{}".format(
+                re.sub("_|-", "", self.__model__.title()),
+                re.sub("_|-", "", "".join(
+                    s.title() for s in new_route.split("/")
+                ))
+            ), (cls,), {}
+        )
+
+        mapper = mapper_class(
             self.netbox_api, self.__app_name__, self.__model__, new_route
         )
-        mapper.__upstream_attrs__ = list(mapper_attributes.keys())
+        mapper.__upstream_attrs__ = []
+        mapper.__foreign_keys__ = []
         for attr, val in mapper_attributes.items():
-            setattr(mapper, attr, val)
+            if isinstance(val, dict) and "id" in val:
+                mapper.__foreign_keys__.append(attr)
+                mapper._set_property_foreign_key(attr, val)
+            else:
+                mapper.__upstream_attrs__.append(attr)
+                setattr(mapper, attr, val)
 
         return mapper
+
+    def _set_property_foreign_key(self, attr, value):
+        def get_foreign_object(*args):
+            if hasattr(self, "_{}".format(attr)):
+                return getattr(self, "_{}".format(attr))
+
+            if attr in self._fk_cache:
+                return self._fk_cache[attr]
+
+            url = value["url"]
+            route = url.replace(self.netbox_api.url, "", 1).lstrip("/")
+            model, app_name, *params = route.split("/")
+
+            fk = list(NetboxMapper(self.netbox_api, model, app_name).get(
+                *[p for p in params if p]
+            ))
+            if not fk:
+                fk = None
+            elif len(fk) == 1:
+                fk = fk[0]
+
+            self._fk_cache[attr] = fk
+            return fk
+
+        def setter(cls, value):
+            setattr(self, "_{}".format(attr), value)
+
+        try:
+            self._fk_cache.pop(attr)
+        except KeyError:
+            pass
+        setattr(type(self), attr, property(get_foreign_object, setter))
+
+
+class NetboxPassiveMapper(NetboxMapper):
+    def get(self, *args, **kwargs):
+        raise ForbiddenAsPassiveMapperError()
+
+    def post(self, *args, **kwargs):
+        raise ForbiddenAsPassiveMapperError()
+
+    def put(self, *args, **kwargs):
+        raise ForbiddenAsPassiveMapperError()
+
+    def delete(self, *args, **kwargs):
+        raise ForbiddenAsPassiveMapperError()

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.0.1
+current_version = 1.1.0b1
 commit = True
 tag = True
 tag_name = {new_version}

setup.py

@@ -9,7 +9,7 @@
 
 setup(
     name="netboxapi",
-    version="1.0.1",
+    version="1.1.0",
 
     description="Client API for Netbox",