Updating documentation about stateful entities.

docs/entities.rst

@@ -22,6 +22,9 @@ This document brings information about all entities that are used by |travispy|
 .. autoclass:: Entity
     :no-show-inheritance:
 
+.. module:: travispy.entities._stateful
+.. autoclass:: Stateful
+
 .. module:: travispy.entities._restartable
 .. autoclass:: Restartable
 

travispy/entities/_stateful.py

@@ -9,17 +9,62 @@ class Stateful(Entity):
     '''
     Base class for stateful entities such as :class:`.Repo`, :class:`.Build` and :class:`.Job`.
 
+    .. attribute:: CANCELED
+
+        Constant representing state ``canceled``. Should not be changed.
+
+    .. attribute:: CREATED
+
+        Constant representing state ``created``. Should not be changed.
+
+    .. attribute:: QUEUED
+
+        Constant representing state ``queued``. Should not be changed.
+
+    .. attribute:: STARTED
+
+        Constant representing state ``started``. Should not be changed.
+
+    .. attribute:: PASSED
+
+        Constant representing state ``passed``. Should not be changed.
+
+    .. attribute:: FAILED
+
+        Constant representing state ``failed``. Should not be changed.
+
+    .. attribute:: ERRORED
+
+        Constant representing state ``errored``. Should not be changed.
+
+    .. attribute:: READY
+
+        Constant representing state ``ready``. Should not be changed.
+
+    .. attribute:: GREEN
+
+        Constant representing state color ``green``. Should not be changed.
+
+    .. attribute:: YELLOW
+
+        Constant representing state color ``yellow``. Should not be changed.
+
+    .. attribute:: RED
+
+        Constant representing state color ``red``. Should not be changed.
+
     :ivar str state:
+
         Current state. Possible values are:
 
-            - created
-            - queued
-            - started
-            - passed
-            - failed
-            - errored
-            - canceled
-            - ready
+            - :attr:`.CANCELED`
+            - :attr:`.CREATED`
+            - :attr:`.QUEUED`
+            - :attr:`.STARTED`
+            - :attr:`.PASSED`
+            - :attr:`.FAILED`
+            - :attr:`.ERRORED`
+            - :attr:`.READY`
     '''
 
     __slots__ = ['state']
@@ -41,80 +86,173 @@ class Stateful(Entity):
 
     @property
     def created(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if entity build process was created successfully.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return hasattr(self, 'state')
 
 
     @property
     def queued(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if entity was already queued sometime in the build process.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state != self.CREATED
 
 
     @property
     def started(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if entity was already started sometime in the build process.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state not in [self.CREATED, self.QUEUED]
 
 
     @property
     def passed(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process was finished successfully.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state == self.PASSED
 
 
     @property
     def failed(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process failed. This is usually related to failures on tests.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state == self.FAILED
 
 
     @property
     def errored(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process got errors.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state == self.ERRORED
 
 
     @property
     def canceled(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process was canceled.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state == self.CANCELED
 
 
     @property
     def ready(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process is ready.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state == self.READY
 
 
     @property
     def pending(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build was scheduled but was not finished.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state in [self.CREATED, self.STARTED, self.QUEUED]
 
 
     @property
     def running(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process is running.
+
+        .. seealso:: :meth:`.check_state`
+        '''
+        self.check_state()
         return self.state == self.STARTED
 
 
     @property
     def finished(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process is finished.
+        '''
         return not self.pending
 
 
     @property
     def successful(self):
+        '''
+        .. seealso:: :attr:`.passed`
+        '''
         return self.passed
 
 
     @property
     def unsuccessful(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build process was finished unsuccessfully.
+        '''
         return self.errored or self.failed or self.canceled
 
 
     @property
     def color(self):
-        self._check_state()
+        '''
+        :rtype: bool
+        :returns:
+           The color related to current build state. Possible values are:
+
+               - :attr:`.GREEN`: when build has passed or it is ready.
+               - :attr:`.YELLOW`: when build process is running.
+               - :attr:`.RED`: when build has failed somehow.
+        '''
         if self.passed or self.ready:
             return self.GREEN
 
@@ -127,19 +265,41 @@ def color(self):
 
     @property
     def green(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build :attr:`.color` is :attr:`.GREEN`.
+        '''
         return self.color == self.GREEN
 
 
     @property
     def yellow(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build :attr:`.color` is :attr:`.YELLOW`.
+        '''
         return self.color == self.YELLOW
 
 
     @property
     def red(self):
+        '''
+        :rtype: bool
+        :returns:
+            ``True`` if build :attr:`.color` is :attr:`.RED`.
+        '''
         return self.color == self.RED
 
-    def _check_state(self):
+
+    def check_state(self):
+        '''
+        Method responsible for checking and validating current :attr:`.state`.
+
+        :raises AttributeError: when :attr:`.state` does not exist.
+        :raises ValueError: when :attr:`.state` value is not supported.
+        '''
         if self.state not in [
             self.CANCELED,
             self.CREATED,

travispy/entities/job.py

@@ -52,7 +52,6 @@ class Job(Restartable):
         'log_id',
         'number',
         'config',
-        'state',
         'started_at',
         'finished_at',
         'duration',