#203 added get_project status attribute, updated docs

* added get_project status attributre * added Scopestatus Enums * updated the Kecenv enums to include KECHAIN_SCOPE_STATUS to pass as envvar * updated docs of client.login and part.children
KE-works · Sep 28, 2017 · ef4f907 · ef4f907
1 parent f7644ee
commit ef4f907
Show file tree

Hide file tree

Showing 15 changed files with 55 additions and 33 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -3,6 +3,11 @@ Change Log
 
 pykechain changelog
 
+1.12.5 (28SEP17)
+----------------
+ * the `get_project()` helper method will now retrieve a scope a status other than 'ACTIVE' only (#203)
+ * updated the documentation to fix wrongly formatted examples.
+
 1.12.4 (26SEP17)
 ----------------
  * Fixed a bug in the customization code by which the activity was incorrectly updated after a correctly saved customization to the KE-chain server. In some cases the incorrect customisation was retrieved on name basis, which may resulted in an error raised. Thansk to @raduiordache for finding it (#200)

diff --git a/docs/api/client.rst b/docs/api/client.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.Client
-================
+Client
+======
 
 .. autoclass:: pykechain.Client
    :members:
diff --git a/docs/api/enums.rst b/docs/api/enums.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.enums
-===============
+enums
+=====
 
 .. automodule:: pykechain.enums
-   :members:
+   :members:
diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.exceptions
-====================
+exceptions
+==========
 
 .. automodule:: pykechain.exceptions
     :members:
diff --git a/docs/api/helpers.rst b/docs/api/helpers.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.helpers
-=================
+helpers
+=======
 
 .. automodule:: pykechain.helpers
    :members:
diff --git a/docs/api/models_activity.rst b/docs/api/models_activity.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.models.Activity and Customizations
-============================================
+models.Activity and Customizations
+==================================
 
 pykechain.models.Activity
 -------------------------

diff --git a/docs/api/models_base.rst b/docs/api/models_base.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.models.Base
-=====================
+models.Base
+===========
 
 This is the baseclass for all pykechain models.
 

diff --git a/docs/api/models_part.rst b/docs/api/models_part.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.models.Partset and Part
-=================================
+models.Part and PartSet
+=======================
 
 .. autoclass:: pykechain.models.PartSet
 

diff --git a/docs/api/models_property.rst b/docs/api/models_property.rst
@@ -1,8 +1,7 @@
 
 
-pykechain.models.Property
-=========================
-
+models.Property
+===============
 
 .. autoclass:: pykechain.models.Property
    :members:

diff --git a/docs/api/models_scope.rst b/docs/api/models_scope.rst
@@ -1,7 +1,7 @@
 
 
-pykechain.models.Scope
-======================
+models.Scope
+============
 
 .. autoclass:: pykechain.models.Scope
    :members:
diff --git a/pykechain/__about__.py b/pykechain/__about__.py
@@ -2,7 +2,7 @@
 name = 'pykechain'
 description = 'KE-chain Python SDK'
 
-version = '1.12.4'
+version = '1.12.5'
 
 author = 'KE-works BV'
 email = 'support+pykechain@ke-works.com'
diff --git a/pykechain/client.py b/pykechain/client.py
@@ -5,7 +5,7 @@
 from envparse import env
 from requests.compat import urljoin, urlparse  # type: ignore
 
-from pykechain.enums import Category, KechainEnv
+from pykechain.enums import Category, KechainEnv, ScopeStatus
 from .__about__ import version
 from .exceptions import ForbiddenError, NotFoundError, MultipleFoundError, APIError, ClientError, IllegalArgumentError
 from .models import Scope, Activity, Part, PartSet, Property
@@ -129,10 +129,12 @@ def login(self, username=None, password=None, token=None):
         Examples
         --------
         Using Token Authentication (retrieve user Token from the KE-chain instance)
+
         >>> client = Client()
         >>> client.login(token='<some-super-long-secret-token>')
 
         Using Basic authentications (Username/Password)
+
         >>> client = Client()
         >>> client.login(username='user', password='pw')
 
@@ -178,7 +180,7 @@ def _request(self, method, url, **kwargs):
 
         return self.last_response
 
-    def scopes(self, name=None, pk=None, status='ACTIVE'):
+    def scopes(self, name=None, pk=None, status=ScopeStatus.ACTIVE):
         # type: (Optional[str], Optional[str], Optional[str]) -> List[Scope]
         """Return all scopes visible / accessible for the logged in user.
 

diff --git a/pykechain/enums.py b/pykechain/enums.py
@@ -86,6 +86,14 @@ class ActivityStatus(Enum):
     COMPLETED = 'COMPLETED'
 
 
+class ScopeStatus(Enum):
+    """The various status of a scope."""
+
+    ACTIVE = 'ACTIVE'
+    CLOSED = 'CLOSED'
+    TEMPLATE = 'TEMPLATE'
+
+
 class KechainEnv(Enum):
     """Environment variables that can be set for pykechain."""
 
@@ -96,3 +104,4 @@ class KechainEnv(Enum):
     KECHAIN_PASSWORD = 'KECHAIN_PASSWORD'
     KECHAIN_SCOPE = 'KECHAIN_SCOPE'
     KECHAIN_SCOPE_ID = 'KECHAIN_SCOPE_ID'
+    KECHAIN_SCOPE_STATUS = 'KECHAIN_SCOPE_STATUS'
diff --git a/pykechain/helpers.py b/pykechain/helpers.py
@@ -2,12 +2,12 @@
 from envparse import env
 
 from pykechain.client import Client
-from pykechain.enums import KechainEnv as kecenv
+from pykechain.enums import KechainEnv as kecenv, ScopeStatus
 from pykechain.exceptions import ClientError
 
 
 def get_project(url=None, username=None, password=None, token=None, scope=None, scope_id=None,
-                env_filename=None):
+                env_filename=None, status=ScopeStatus.ACTIVE):
     """
     Retrieve and return the KE-chain project to be used throughout an app.
 
@@ -20,13 +20,16 @@ def get_project(url=None, username=None, password=None, token=None, scope=None,
     when the environment variable KECHAIN_FORCE_ENV_USE is set to true, (or ok, on, 1, yes) then the use of
     environmentvariables for the retrieval of the scope are enforced. The following environment variables can be set::
 
-        KECHAIN_URL         - full url of KE-chain where to connect to eg: 'https://<some>.ke-chain.com'
-        KECHAIN_TOKEN       - authentication token for the KE-chain user provided from KE-chain user account control
-        KECHAIN_USERNAME    - the username for the credentials
-        KECHAIN_PASSWORD    - the password for the credentials
-        KECHAIN_SCOPE       - the name of the project / scope. Should be unique, otherwise use scope_id
-        KECHAIN_SCOPE_ID    - the UUID of the project / scope.
+        KECHAIN_URL           - full url of KE-chain where to connect to eg: 'https://<some>.ke-chain.com'
+        KECHAIN_TOKEN         - authentication token for the KE-chain user provided from KE-chain user account control
+        KECHAIN_USERNAME      - the username for the credentials
+        KECHAIN_PASSWORD      - the password for the credentials
+        KECHAIN_SCOPE         - the name of the project / scope. Should be unique, otherwise use scope_id
+        KECHAIN_SCOPE_ID      - the UUID of the project / scope.
         KECHAIN_FORCE_ENV_USE - set to 'true', '1', 'ok', or 'yes' to always use the environment variables.
+        KECHAIN_SCOPE_STATUS  - the status of the Scope to retrieve, defaults to None to retrieve all scopes
+
+    .. versionadded:: 1.12
 
     :param url: (optional) url of KE-chain
     :param username: (optional) username for authentication (together with password, if not token)
@@ -35,6 +38,7 @@ def get_project(url=None, username=None, password=None, token=None, scope=None,
     :param scope: (optional) name of the scope to retrieve from KE-chain.
     :param scope_id: (optional) UUID of the scope to retrieve and return from KE-chain
     :param env_filename: (optional) name of the environment filename to bootstrap the Client
+    :param status: (optional) status of the scope to retrieve, defaults to `Scopestatus.ACTIVE`
     :return: pykechain.models.Scope
     :raises: NotFoundError, ClientError, APIError
 
@@ -89,6 +93,7 @@ def get_project(url=None, username=None, password=None, token=None, scope=None,
         client = Client.from_env(env_filename=env_filename)
         scope_id = env(kecenv.KECHAIN_SCOPE_ID, default=None)
         scope = env(kecenv.KECHAIN_SCOPE, default=None)
+        status = env(kecenv.KECHAIN_SCOPE_STATUS, default=None)
     elif (url and ((username and password) or (token)) and (scope or scope_id)) and \
             not env.bool(kecenv.KECHAIN_FORCE_ENV_USE, default=False):
         client = Client(url=url)
@@ -98,6 +103,6 @@ def get_project(url=None, username=None, password=None, token=None, scope=None,
                           "See documentation of `pykechain.get_project()`")
 
     if scope_id:
-        return client.scope(pk=scope_id)
+        return client.scope(pk=scope_id, status=status)
     else:
-        return client.scope(name=scope)
+        return client.scope(name=scope, status=status)
diff --git a/pykechain/models/part.py b/pykechain/models/part.py
@@ -122,8 +122,10 @@ def children(self, **kwargs):
         >>> direct_descendants_of_bike = bike.children()
 
         An example with providing additional part search parameters 'name__icontains'
+
         >>> bike = project.part('Bike')
         >>> wheel_children_of_bike = bike.children(name__icontains='wheel')
+
         """
         return self._client.parts(parent=self.id, category=self.category, **kwargs)