salmon.confirm module

Confirmation handling API that helps you get the whole confirm/pending/verify process correct. It doesn’t implement any handlers, but what it does do is provide the logic for doing the following:

• Take an email, put it in a “pending” queue, and then send out a confirm email with a strong random id.

• Store the pending message ID and the random secret someplace for later verification.

• Verify an incoming email against the expected ID, and get back the original.

You then just work this into your project’s state flow, write your own templates, and possibly write your own storage.

class salmon.confirm.ConfirmationEngine(pending_queue, storage)

Bases: object

The confirmation engine is what does the work of sending a confirmation, and verifying that it was confirmed properly. In order to use it you have to construct the ConfirmationEngine (usually in settings module) and you write your confirmation message templates for sending.

The primary methods you use are ConfirmationEngine.send and ConfirmationEngine.verify.

The pending_queue should be a string with the path to the salmon.queue.Queue that will store pending messages. These messages are the originals the user sent when they tried to confirm.

Storage should be something that is like ConfirmationStorage so that this can store things for later verification.

cancel(target, from_address, expect_secret)

Used to cancel a pending confirmation.

clear()

Used in testing to make sure there’s nothing in the pending queue or storage.

delete_pending(pending_id)

Removes the pending message from the pending queue.

get_pending(pending_id)

Returns the pending message for the given ID.

make_random_secret()

Generates a random uuid as the secret, in hex form.

push_pending(message)

Puts a pending message into the pending queue.

register(target, message)

Don’t call this directly unless you know what you are doing. It does the job of registering the original message and the expected confirmation into the storage.

send(relay, target, message, template, vars)

This is the method you should use to send out confirmation messages. You give it the relay, a target (i.e. “subscribe”), the message they sent requesting the confirm, your confirmation template, and any vars that template needs.

The result of calling this is that the template message gets sent through the relay, the original message is stored in the pending queue, and data is put into the storage for later calls to verify.

verify(target, from_address, expect_secret)

Given a target (i.e. “subscribe”, “post”, etc), a from_address of someone trying to confirm, and the secret they should use, this will try to verify their confirmation. If the verify works then you’ll get the original message back to do what you want with.

If the verification fails then you are given None.

The message is not deleted from the pending queue. You can do that yourself with delete_pending.

class salmon.confirm.ConfirmationStorage(db={})

Bases: object

This is the basic confirmation storage. For simple testing purposes you can just use the default hash db parameter. If you do a deployment you can probably get away with a shelf hash instead.

You can write your own version of this and use it. The confirmation engine only cares that it gets something that supports all of these methods.

Change the db parameter to a shelf to get persistent storage.

clear()

Used primarily in testing, this clears out all pending confirmations.

delete(target, from_address)

Removes a target+from_address from the storage.

get(target, from_address)

Given a target and a from address, this returns a tuple of (expected_secret, pending_message_id). If it doesn’t find that target+from_address, then it should return a (None, None) tuple.

key(target, from_address)

Used internally to construct a string key, if you write your own you don’t need this.

NOTE: To support proper equality and shelve storage, this encodes the key into ASCII. Make a different subclass if you need Unicode and your storage supports it.

store(target, from_address, expected_secret, pending_message_id)

Given a target, from_address it will store the expected_secret and pending_message_id of later verification. The target should be a string indicating what is being confirmed. Like “subscribe”, “post”, etc.

When implementing your own you should never allow more than one target+from_address combination.