django-connections 0.1

Defining relationships

Assume you’re LitHub, a social coding site in its infancy, and you need to let your users star repositories they find interesting. With connections, you would first define a relationship:

>>> from django.contrib.auth.models import User
>>> from connections import define_relationship
>>> from lithub.models import Repo
>>> repo_stars = define_relationship('star_repo', from_model=User, to_model=Repo)

define_relationship creates and registers a new Relationship instance between the given models, with the name 'star_repo'. Names of relationships must be unique across your project. You may alternatively specify the models of the relationship as strings, e.g. 'auth.User' or 'lithub.Repo'.

Any time you need to reference a relationship, you can either import the module variable (as defined above), or use connections.get_relationship(name).

Managing connections

Let’s say that milo found a nice Python project on LitHub that he’d like to star, for future reference. In connections this can be modelled by creating a connection between milo and the repository instance:

>>> milo = User.objects.get(pk=104)
>>> foopy = Repo.objects.get(pk=47)
>>> star_repo.create_connection(milo, foopy)
'star_repo (auth.User:104 -> lithub.Repo:47)'

Connections are unidirectional, meaning that if foo is connected with bar, the reverse – that bar is connected to foo – is not implied. If you’d like to model a symmetrical relationship, that is, one that only makes sense if both sides have agreed in the relationship (e.g. friendship or even marriage), you’d have to create two opposite connections, one for each side of the relationship.

Let’s see what repositories milo has starred:

>>> repo_stars.connected_objects(milo)
[<Repo: foopy>]

We can also query for the reverse, that is, what users have starred foopy:

>>> repo_stars.connected_to_objects(foopy)
[<User: milo>]

There are several other methods you may use to query or manage connections, that you may read about in API Reference.

Class Relationship

Represents a predefined type of connection between two nodes in a (directed) graph. You may imagine relationships as the kind of an edge in the graph.

>>> from connections.models import Relationship
>>> rel = Relationship('rel_name', from_content_type, to_content_type)

Class Connection

Represents a connection between two nodes in the graph. Connections must be treated as unidirectional, i.e. creating a connection from one node to another should not imply the reverse.