Internal API Documentation

Adhocracy does not have a public programming API. There is a plan to develop a common Kernel interface for Liquid Democracy projects. Once such an API becomes available, Adhocracy will be modified to implement that API.

Core polling logic

class adhocracy.lib.democracy.decision.Decision(user, poll, at_time=None, votes=None)

A decision describes the current or past opinion that a user has expressed on a given poll. This includes opinions that were determined by an agent as a result of delegation.

classmethod average_decisions(instance)

The average number of decisions that a Poll in the given instance has. For each proposal, this only includes the current poll in order to not accumulate too much historic data.

Parameter:instance – the Instance for which to calculate the average.

create_time

Utility property to see when this decision became effective. Equals the latest relevant vote creation date.

Returns:datetime

delegations

The set of delegations which have determined this decision, as per relevant_votes.

Returns:list of Delegation

classmethod for_poll(poll, at_time=None)

Get all decisions that have been made on a poll.

Parameter:poll – The poll on which to get decisions.

classmethod for_user(user, instance, at_time=None)

Give a list of all decisions the user made within an instance context.

Parameters:

• user – The user for which to list Decisions
• instance – an Instance context.

is_decided()

Determine if a given decision was made by the user, i.e. if the user or one of his/her agents has voted on the proposal.

is_self_decided()

Determine if a given decision was made by the user him-/herself. This does not consider decisions determined by delegation.

make(orientation, _edge=None)

Make a decision on a given proposal, i.e. vote. Voting recursively propagates through the delegation graph to all principals who have assigned voting power to the User. Each delegated vote will be marked as such by saving the Delegation as a part of the Vote.

Parameter:orientation – orientation of the vote, Vote.YES, Vote.NO or Vote.ABSTAIN Returns:the Votes that has been cast

relevant_votes

Currently relevant votes for the polling interval.

WARNING: A non-empty list of relevant votes does not always mean a decision was made. This is not true, for example, when multiple delegates match a proposal and their opinions differ.

Returns:List of Vote

reload()

Load all votes by the user regarding the poll.

classmethod replay_decisions(delegation)

For a new delegation, have the principal reproduce all of the agents past decisions within the delegation scope. This process is not perfect, since not the full voting history is reproduced, but only the latest interim result. The resulting decisions should be the same, though.

Parameter:delegation – The delegation that is newly created.

result

The result is an orientation and reflects the User‘s current decision on the Proposal. Values match those in Vote. Given multiple delegates who have voted on the proposal, the current approach is to check for an unanimous decision and to discard all other constellations. Another approach would be to require only a certain majority of agents to support an opinion, thus creating an inner vote.

to_dict()

without_vote(vote)

Return the same decision given that a certain vote had not been cast.

exception adhocracy.lib.democracy.decision.DecisionException

A general exception for Decision errors

exception adhocracy.model.poll.NoPollException

class adhocracy.model.poll.Poll(scope, user, action, subject=None)

action

Public-facing descriptor, placed in the mapped class dictionary.

begin_time

Public-facing descriptor, placed in the mapped class dictionary.

classmethod by_subjects(subjects, include_deleted=True)

can_end()

check_stable(at_time)

classmethod create(scope, user, action, subject=None, with_vote=False)

delete(delete_time=None)

end(end_time=None)

end_time

Public-facing descriptor, placed in the mapped class dictionary.

classmethod find(id, instance_filter=True, include_deleted=True)

has_ended(at_time=None)

id

Public-facing descriptor, placed in the mapped class dictionary.

is_deleted(at_time=None)

is_stable(at_time=None)

scope

Public-facing descriptor, placed in the mapped class dictionary.

scope_id

Public-facing descriptor, placed in the mapped class dictionary.

selection

subject

A combination of InsturmentedAttribute and a regular descriptor.

tally

to_dict()

user

Public-facing descriptor, placed in the mapped class dictionary.

user_id

Public-facing descriptor, placed in the mapped class dictionary.

variant

classmethod within_scope(scope)

class adhocracy.model.tally.Tally(poll, num_for, num_against, num_abstain)

classmethod all_samples(poll, start_time, end_time)

classmethod combine_polls(polls, at_time=None)

classmethod create_from_poll(poll, at_time=None)

classmethod create_from_vote(vote)

create_time

Public-facing descriptor, placed in the mapped class dictionary.

classmethod find_by_vote(vote)

has_majority()

has_participation()

id

Public-facing descriptor, placed in the mapped class dictionary.

num_abstain

Public-facing descriptor, placed in the mapped class dictionary.

num_against

Public-facing descriptor, placed in the mapped class dictionary.

num_for

Public-facing descriptor, placed in the mapped class dictionary.

poll

Public-facing descriptor, placed in the mapped class dictionary.

poll_id

Public-facing descriptor, placed in the mapped class dictionary.

rel_against

rel_for

score

to_dict()

vote

Public-facing descriptor, placed in the mapped class dictionary.

vote_id

Public-facing descriptor, placed in the mapped class dictionary.

class adhocracy.model.vote.Vote(user, poll, orientation, delegation=None)

classmethod all()

create_time

Public-facing descriptor, placed in the mapped class dictionary.

delegation

Public-facing descriptor, placed in the mapped class dictionary.

delegation_id

Public-facing descriptor, placed in the mapped class dictionary.

classmethod find(id, instance_filter=True, include_deleted=False)

id

Public-facing descriptor, placed in the mapped class dictionary.

orientation

Public-facing descriptor, placed in the mapped class dictionary.

poll

Public-facing descriptor, placed in the mapped class dictionary.

poll_id

Public-facing descriptor, placed in the mapped class dictionary.

to_dict()

user

Public-facing descriptor, placed in the mapped class dictionary.

user_id

Public-facing descriptor, placed in the mapped class dictionary.

Delegation management and traversal

class adhocracy.lib.democracy.delegation_node.DelegationNode(user, delegateable)

A DelegationNode describes a part of the voting delegation graph sorrounding a Delegateable (i.e. a Category, Issue or Proposal) and a User.

Right now the delegation graph is a graph of incomming and outgoing delegations on multiple levels - one level per scope.

Each DelegationNode represents the incomming and outgoing delegations of one user on one level (scope/delegateable) in this graph.

TODO: Developing a good caching strategy for this class would be useful in order to cache the delegation graph to memcached.

Parameters:

• user – The User at the center of this DelegationNode.
• delegateable – A Delegateable.

classmethod filter_less_specific_delegations(delegations)

Given a set of delegations, remove those that are overriden by others. A delegation is overridden whenever there is another delegation with a narrower scope that still applies.

Parameter:delegations – The list of delegations that are to be filtered. They need to all be be from the same principal. Returns:A filtered list of delegations.

inbound(recurse=True, at_time=None, is_counting_delegations=False)

Retrieve all inbound delegations (i.e. those that the user has received from other users in order to vote on their behalf) that apply to the Delegateable.

Parameters:

• recurse – if True, search will include delegations on parent Delegateables in breadth-first traversal order.
• at_time – return the delegation graph at the given time, defaults to the current time.

outbound(recurse=True, at_time=None, filter=True)

Retrieve all outbound delegations (i.e. those that the user has given to other users in order allow them to vote on his/her behalf) that apply to the Delegateable.

Parameters:

• recurse – if True, search will include delegations on parent Delegateables in breadth-first traversal order.
• at_time – return the delegation graph at the given time, defaults to the current time.

Returns:

list of Delegation

propagate(callable, _edge=None, _propagation_path=None)

Propagate a given action along the delegation graph against its direction, i.e. from the agent node towards its principal. This is the natural direction to propagate actions along this network since it allows principals to reproduce the actions of their agents.

Propagation will abort on circular dependencies but has no recursion depth limit.

Parameter:callable – A callable that is to be called on each node. It must take three arguments, a User, a Delegateable and the Delegation which served as a transitory edge during the last step of the propagation. Returns:a list of all results produced by the callable.

transitive_inbound(recurse=True, at_time=None, _path=None, is_counting_delegations=False)

Retrieve inbound delegations recursing through the delegation graph as well as through the category tree.

Parameters:

• recurse – if True, search will include delegations on parent Delegateables in breadth-first traversal order.
• at_time – return the delegation graph at the given time, defaults to the current time.

Returns:

list of Delegation