Understanding PeeWee's related_name property

Question

I'm really enjoying the Peewee ORM. It's lightweight, easy to use, and pretty well documented. One thing I'm having trouble grasping is the related_name property used when implementing foreign keys. I'm never sure whether the property should relate to the table, or to the column. Could someone explain to me exactly what I should be using the name for, and how? For example, with the Student/Courses example found in the Peeewee docs themselves.

https://peewee.readthedocs.org/en/2.0.2/peewee/fields.html#implementing-many-to-many

class Student(Model):
    name = CharField()

class Course(Model):
    name = CharField()

class StudentCourse(Model):
    student = ForeignKeyField(Student)
    course = ForeignKeyField(Course)

Assuming I have Student, Course, StudentCourse models. What would the related names be for the StudentCourse columns?

Answer 1

I'm never sure whether the property should relate to the table, or to the column. Could someone explain to me exactly what I should be using the name for, and how?

A foreign key is like a pointer, a 1-to-1. But there is also an implied back-reference -- this is the related name. Examples:

• Tweet has a foreign key to the User who tweeted it. The back-reference is the tweets created by a user, so related_name='tweets'.
• Category has a foreign key to itself to indicate the parent category. The backreference is the child categories for a given parent, so related_name='children'.
• Code snippet has a foreign key to the language it's written in. The back-reference is the snippets for a language, so related_name='snippets'.

For example, with the Student/Courses example found in the Peeewee docs themselves.

That is a many-to-many, and so the back-references aren't quite as "clear" because the foreign keys exist on a junction table. Your frame of reference is the junction table, so the back-references would be studentcourses in both cases, though this isn't helpful because the backreferences just take you to the junction table. So, with many-to-many, generally the backreferences can be left at the default since your queries will usually look like:

# get students in english 101
Student.select().join(StudentCourse).join(Course).where(Course.name == 'ENGL 101')

# get huey's courses
Course.select().join(StudentCourse).join(Student).where(Student.name == 'Baby Huey')