Update description of Rate and Device; remove PhotoboxRate schemas

ereuse_devicehub/resources/device/models.py

@@ -103,22 +103,23 @@ class Device(Thing):
 
     @property
     def rate(self):
-        """Gets the last aggregate rate."""
+        """The last AggregateRate of the device."""
         with suppress(LookupError, ValueError):
             from ereuse_devicehub.resources.event.models import AggregateRate
             return self.last_event_of(AggregateRate)
 
     @property
     def price(self):
-        """Gets the actual Price of the device or None
+        """The actual Price of the device, or None if no price has
-        if no price has ever been set."""
+        ever been set."""
         with suppress(LookupError, ValueError):
             from ereuse_devicehub.resources.event.models import Price
             return self.last_event_of(Price)
 
     @property
     def trading(self):
-        """The actual trading state or None if there is no trading info."""
+        """The actual trading state, or None if no Trade event has
+        ever been performed to this device."""
         from ereuse_devicehub.resources.device import states
         with suppress(LookupError, ValueError):
             event = self.last_event_of(*states.Trading.events())
@@ -126,7 +127,7 @@ class Device(Thing):
 
     @property
     def physical(self):
-        """The actual physical state, None if there is no state."""
+        """The actual physical state, None otherwise."""
         from ereuse_devicehub.resources.device import states
         with suppress(LookupError, ValueError):
             event = self.last_event_of(*states.Physical.events())

ereuse_devicehub/resources/device/schemas.py

@@ -31,11 +31,14 @@ class Device(Thing):
     events = NestedOn('Event', many=True, dump_only=True, description=m.Device.events.__doc__)
     events_one = NestedOn('Event', many=True, load_only=True, collection_class=OrderedSet)
     url = URL(dump_only=True, description=m.Device.url.__doc__)
-    lots = NestedOn('Lot', many=True, dump_only=True)
+    lots = NestedOn('Lot',
-    rate = NestedOn('AggregateRate', dump_only=True)
+                    many=True,
-    price = NestedOn('Price', dump_only=True)
+                    dump_only=True,
-    trading = EnumField(states.Trading, dump_only=True)
+                    description='The lots where this device is directly under.')
-    physical = EnumField(states.Physical, dump_only=True)
+    rate = NestedOn('AggregateRate', dump_only=True, description=m.Device.rate.__doc__)
+    price = NestedOn('Price', dump_only=True, description=m.Device.price.__doc__)
+    trading = EnumField(states.Trading, dump_only=True, description=m.Device.trading.__doc__)
+    physical = EnumField(states.Physical, dump_only=True, description=m.Device.physical.__doc__)
     physical_possessor = NestedOn('Agent', dump_only=True, data_key='physicalPossessor')
 
     @pre_load

ereuse_devicehub/resources/event/__init__.py

@@ -64,16 +64,6 @@ class WorkbenchRateDef(RateDef):
     SCHEMA = schemas.WorkbenchRate
 
 
-class PhotoboxUserDef(RateDef):
-    VIEW = None
-    SCHEMA = schemas.PhotoboxUserRate
-
-
-class PhotoboxSystemRateDef(RateDef):
-    VIEW = None
-    SCHEMA = schemas.PhotoboxSystemRate
-
-
 class ManualRateDef(RateDef):
     VIEW = None
     SCHEMA = schemas.ManualRate

ereuse_devicehub/resources/event/models.py

@@ -356,8 +356,11 @@ class SnapshotRequest(db.Model):
 
 class Rate(JoinedWithOneDeviceMixin, EventWithOneDevice):
     rating = Column(Float(decimal_return_scale=2), check_range('rating', *RATE_POSITIVE))
+    rating.comment = """The rating for the content."""
     software = Column(DBEnum(RatingSoftware))
+    software.comment = """The algorithm used to produce this rating."""
     version = Column(StrictVersionType)
+    version.comment = """The version of the software."""
     appearance = Column(Float(decimal_return_scale=2), check_range('appearance', *RATE_NEGATIVE))
     functionality = Column(Float(decimal_return_scale=2),
                            check_range('functionality', *RATE_NEGATIVE))
@@ -392,13 +395,9 @@ class ManualRate(IndividualRate):
     be removed.
     """
     appearance_range = Column(DBEnum(AppearanceRange))
-    appearance_range.comment = """Grades the imperfections that 
+    appearance_range.comment = AppearanceRange.__doc__
-    aesthetically affect the device, but not its usage.
-    """
     functionality_range = Column(DBEnum(FunctionalityRange))
-    functionality_range.comment = """Grades the defects of a device 
+    functionality_range.comment = FunctionalityRange.__doc__
-    affecting usage.
-    """
 
 
 class WorkbenchRate(ManualRate):
@@ -412,9 +411,7 @@ class WorkbenchRate(ManualRate):
     bios = Column(Float(decimal_return_scale=2),
                   check_range('bios', *RATE_POSITIVE))
     bios_range = Column(DBEnum(Bios))
-    bios_range.comment = """How difficult it has been to set the bios
+    bios_range.comment = Bios.__doc__
-    to boot from the network.
-    """
 
     # todo ensure for WorkbenchRate version and software are not None when inserting them
 
@@ -431,6 +428,12 @@ class WorkbenchRate(ManualRate):
 class AggregateRate(Rate):
     id = Column(UUID(as_uuid=True), ForeignKey(Rate.id), primary_key=True)
     manual_id = Column(UUID(as_uuid=True), ForeignKey(ManualRate.id))
+    manual_id.comment = """The ManualEvent used to generate this
+    aggregation, or None if none used.
+
+    An example of ManualEvent is using the web or the Android app
+    to rate a device.
+    """
     manual = relationship(ManualRate,
                           backref=backref('aggregate_rate_manual',
                                           lazy=True,
@@ -438,6 +441,9 @@ class AggregateRate(Rate):
                                           collection_class=OrderedSet),
                           primaryjoin=manual_id == ManualRate.id)
     workbench_id = Column(UUID(as_uuid=True), ForeignKey(WorkbenchRate.id))
+    workbench_id.comment = """The WorkbenchRate used to generate
+    this aggregation, or None if none used.
+    """
     workbench = relationship(WorkbenchRate,
                              backref=backref('aggregate_rate_workbench',
                                              lazy=True,
@@ -483,10 +489,19 @@ class AggregateRate(Rate):
 
 class Price(JoinedWithOneDeviceMixin, EventWithOneDevice):
     currency = Column(DBEnum(Currency), nullable=False)
+    currency.comment = """The currency of this price as for ISO 4217."""
     price = Column(Numeric(precision=19, scale=4), check_range('price', 0), nullable=False)
+    price.comment = """The value."""
     software = Column(DBEnum(PriceSoftware))
+    software.comment = """The software used to compute this price,
+    if the price was computed automatically. This field is None
+    if the price has been manually set.
+    """
     version = Column(StrictVersionType)
+    version.comment = """The version of the software, or None."""
     rating_id = Column(UUID(as_uuid=True), ForeignKey(AggregateRate.id))
+    rating_id.comment = """The AggregateRate used to auto-compute
+    this price, if it has not been set manually."""
     rating = relationship(AggregateRate,
                           backref=backref('price',
                                           lazy=True,

ereuse_devicehub/resources/event/models.pyi

@@ -146,6 +146,8 @@ class Rate(EventWithOneDevice):
     rating = ...  # type: Column
     appearance = ...  # type: Column
     functionality = ...  # type: Column
+    software = ...  # type: Column
+    version = ...  # type: Column
 
     def __init__(self, **kwargs) -> None:
         super().__init__(**kwargs)

ereuse_devicehub/resources/event/schemas.py

@@ -102,12 +102,12 @@ class Rate(EventWithOneDevice):
     rating = Integer(validate=Range(*RATE_POSITIVE),
                      dump_only=True,
                      data_key='rating',
-                     description='The rating for the content.')
+                     description=m.Rate.rating.comment)
     software = EnumField(RatingSoftware,
                          dump_only=True,
-                         description='The algorithm used to produce this rating.')
+                         description=m.Rate.software.comment)
     version = Version(dump_only=True,
-                      description='The version of the software.')
+                      description=m.Rate.version.comment)
     appearance = Integer(validate=Range(-3, 5), dump_only=True)
     functionality = Integer(validate=Range(-3, 5),
                             dump_only=True,
@@ -118,26 +118,6 @@ class IndividualRate(Rate):
     pass
 
 
-class PhotoboxRate(IndividualRate):
-    num = Integer(dump_only=True)
-    # todo Image
-
-
-class PhotoboxUserRate(IndividualRate):
-    assembling = Integer()
-    parts = Integer()
-    buttons = Integer()
-    dents = Integer()
-    decolorization = Integer()
-    scratches = Integer()
-    tag_adhesive = Integer()
-    dirt = Integer()
-
-
-class PhotoboxSystemRate(IndividualRate):
-    pass
-
-
 class ManualRate(IndividualRate):
     appearance_range = EnumField(AppearanceRange,
                                  required=True,
@@ -162,8 +142,11 @@ class WorkbenchRate(ManualRate):
 
 
 class AggregateRate(Rate):
-    workbench = NestedOn(WorkbenchRate, dump_only=True)
+    workbench = NestedOn(WorkbenchRate, dump_only=True,
-    manual = NestedOn(ManualRate, dump_only=True)
+                         description=m.AggregateRate.workbench_id.comment)
+    manual = NestedOn(ManualRate,
+                      dump_only=True,
+                      description=m.AggregateRate.manual_id.comment)
     processor = Float(dump_only=True)
     ram = Float(dump_only=True)
     data_storage = Float(dump_only=True)
@@ -172,11 +155,14 @@ class AggregateRate(Rate):
 
 
 class Price(EventWithOneDevice):
-    currency = EnumField(Currency, required=True)
+    currency = EnumField(Currency, required=True, description=m.Price.currency.comment)
-    price = Decimal(places=4, rounding=decimal.ROUND_HALF_EVEN, required=True)
+    price = Decimal(places=4,
-    software = EnumField(PriceSoftware, dump_only=True)
+                    ounding=decimal.ROUND_HALF_EVEN,
-    version = Version(dump_only=True)
+                    required=True,
-    rating = NestedOn(AggregateRate, dump_only=True)
+                    description=m.Price.price.comment)
+    software = EnumField(PriceSoftware, dump_only=True, description=m.Price.software.comment)
+    version = Version(dump_only=True, description=m.Price.version.comment)
+    rating = NestedOn(AggregateRate, dump_only=True, description=m.Price.rating_id.comment)
 
 
 class EreusePrice(Price):

tests/test_basic.py

@@ -39,4 +39,4 @@ def test_api_docs(client: Client):
         'scheme': 'basic',
         'name': 'Authorization'
     }
-    assert 77 == len(docs['definitions'])
+    assert 75 == len(docs['definitions'])