Class Association

source code

object --+
         |
        Association

Known Subclasses:

• BelongsTo
• , Has

Associations

Associations allow you to retrieve a model or collection of models that are related to one another in some way. Here we are concerned with how associations are defined and implemented. For documentation on how to use associations in your models, please see the belongs_to, has_one, and has_many methods on pyperry.Base.

Terminology

To understand how associations work, we must define the concepts of a source class and a target class for an association.

• target class: the class on which you define the association
• source class: the class of the records returned by calling the association method on the target class

An example showing the difference between source and target classes:

   class Car(pyperry.Base): pass
   class Part(pyperry.Base): pass

   # Car is the target class and Part is the source class
   Car.has_many('parts', class_name='Part')

   # Part is the target class and Car is the source class
   Part.belongs_to('car', class_name='Car')

   c = Car.first()
   # returns a collection of Part models (Part is the source class)
   c.parts()

   p = Part.first()
   # returns a Car model (Car is the source class)
   p.car()

What happens when you define an association

Now let's look at what happens when you define an association on a model. We will use the association Car.has_many('parts', class_name='Part') as an example because all associations work in the same general way. In this example, a HasMany class (an Association subclass) is instantiated where Car is given as the target_klass argument, and 'parts' is given as the id argument. Because we passed in 'Part' for the class_name option, it is used as the source class for this association.

The association id is used as the name of the association method that gets defined on the target class. So in our example, all Car instances now have a parts() method that can be called to retrieve a collection of parts for a car. When you call the association method on the target class, a relation (or scope) is constructed for the source class representing all of the records related to the target class. For associations that represent collections, such as has_many, a relation is returned that you can further modify. For associations that represent a single object, such as belongs_to or has_one, an instance of that model is returned.

In summary, all an association does is create a scope on the source class that represents records from the source class that are related to (or associated with) the target class. Then a method on the target class is created that returns this scope.

This means that calling car.parts() is just returning a scope like:

   Part.scoped().where({'car_id': car.id})

Similarly, calling part.car() is just returning a scope like:

   Car.scoped().where({'id': part.car_id}).first()