Python client

ConsentClient calls the API from your Python server with a secret key. Each method is listed here with its parameters, what it returns and the errors it raises.

Requirements#

• Python 3.9 or later. The package uses only the standard library and is fully typed.
• A secret key, sk_…. See Keys and where to use them.

Install#

Your deployment serves the wheel, version 1.0.4.

PACKAGES=https://console.dpconsent.com/consent/sdk/v1/packages
pip install $PACKAGES/piedap_consent-1.0.4-py3-none-any.whl

The distribution is named piedap-consent. The module you import is piedap_consent.

Create the client#

ConsentClient()#

Creates a client that holds no open connections and no state that changes. Create one at start-up and share it, across threads too.

Returns a ConsentClient. Its api_url property holds the address requests are sent to.

Errors Raises ValueError when secret_key is empty or a publishable key, pk_…, and when another argument is not valid.

import os

from piedap_consent import ConsentClient

client = ConsentClient(
    api_url="https://console.dpconsent.com/consent",
    secret_key=os.environ["PIEDAP_SECRET_KEY"],
)

Retries and timeouts#

• Only calls that are safe to repeat are retried: every GET, and any write you gave an idempotency_key.
• A retry follows a connection failure, a timeout, or a 502, 503 or 504 response.
• Every other failure, including 429, is raised at once.
• check_consent() waits one second unless you pass timeout, and never retries.
• Redirects are never followed, so the key is never sent to another host.
• Retries are logged at INFO on the piedap_consent logger.
• Each request sends User-Agent: piedap-consent-python/1.0.4.

Methods#

The scope is what the secret key must hold. Every secret key holds consent:read and consent:write.

Every method raises a ConsentError when a call fails. A key without the scope gets the code SCOPE_REQUIRED. An argument that cannot be sent raises ValueError or TypeError before any request is made.

resolve_form()#

Returns the published form for a place or a form key, with its purposes.

Returns dict, the API's JSON with the API's own field names. form is None when no form is served for that place.

Errors Raises NotFoundError when no form has that form_key.

resolved = client.resolve_form(form_key="kalpa-account", country="IN")
form = resolved["form"]
keys = [p["key"] for p in form["purposes"] if not p.get("alwaysOn")]

record_consent()#

Records one person's answers to a form. Every argument is keyword only.

Returns Consent, the record as stored.

Errors Raises ValueError for both or neither of form_key and form_id, an empty decision list, a purpose listed twice, more than five identifiers, or a collected_at without a timezone. Raises ValueError for a basis other than PRE_COMMENCEMENT or a malformed notice_sha256. Raises ConsentError with the code INVALID_PURPOSE_DECISIONS when a purpose is not answered or not on the form. A write with collected_at that the records overrule raises ConsentError with status 409; is_skipped_import(error) is then True. See Bring in consent given earlier.

from piedap_consent import Decision, Identifier

consent = client.record_consent(
    form_key="kalpa-account",
    subject_id="usr_8f2K1xQz",
    subject_type="USER_ID",
    country_code="IN",
    interaction="SAVE_PREFERENCES",
    decisions=[
        Decision("course-updates-by-email", True),
        Decision("class-reminders-by-sms", False),
    ],
    identifiers=[Identifier("EMAIL", "kavya.menon@example.in")],
    idempotency_key="signup-usr_8f2K1xQz",
)
print(consent.consent_id, consent.status)

Decisions and identifiers may also be plain mappings, such as {"purpose_key": "analytics", "granted": True}. The API's camel-case names work too. See Record consent.

get_consent()#

Returns one record by its id.

Returns Consent, or None.

Errors Raises ConsentError, except for a 404. The method then returns None: the id is not known, or the record's expiry has passed.

consent = client.get_consent("cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8")
if consent and consent.granted("course-updates-by-email"):
    send_course_update()

update_consent()#

Changes answers on an existing record.

Returns Consent, the record as updated.

Errors Raises NotFoundError for an unknown id. The call takes no idempotency key, so it is never retried.

client.update_consent(
    "cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8",
    [Decision("class-reminders-by-sms", True)],
    interaction="PREFERENCE_CENTRE",
)

withdraw_consent()#

Withdraws one record.

Returns Consent, the record as withdrawn.

Errors Raises NotFoundError for an unknown id.

consent = client.withdraw_consent(
    "cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8",
    reason="Asked by phone",
)
print(consent.status, consent.withdrawn_on)

verify()#

Returns the signed receipt for one record. The Node.js client calls this method receipt().

Returns Receipt. valid is True when the server replayed the proof chain and it matched.

Errors Raises NotFoundError for an unknown id.

receipt = client.verify("cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8")
print(receipt.valid)
archive(receipt.to_dict())

start_email_consent()#

Starts a double opt-in for an email address.

Returns PendingEmailConsent. Send its verification_url to the address in your own email.

Errors Raises ConsentError.

pending = client.start_email_consent(
    "rohan.das@example.in",
    "newsletter",
    [Decision("newsletter", True)],
    return_url="https://www.example.in/subscribed",
)

See Email double opt-in.

record_activity()#

Reports that a person signed in or used your service.

Returns dict with records and activeOn.

Errors Raises ConsentError.

client.record_activity("usr_8f2K1xQz", "USER_ID")

consent_portal_link()#

Creates a seven-day link to the hosted page where the person reviews, withdraws and downloads their consents.

Returns dict with url and expiresOn.

Errors Raises ConsentError.

link = client.consent_portal_link("usr_8f2K1xQz", "USER_ID")
print(link["url"], link["expiresOn"])

See Hosted pages.

find_subject()#

Returns every record held for a person.

Returns dict with subjectType, fingerprint and records. Each record's matchedBy lists the identifier types that matched.

Errors Raises ConsentError.

found = client.find_subject("+919846011223", "PHONE")
for record in found["records"]:
    print(record["consentId"], record["status"], record["matchedBy"])

See Find a person.

export_subject()#

Returns signed receipts and a processing summary for an access request.

Returns dict, the API's JSON.

Errors Raises ConsentError.

pack = client.export_subject("usr_8f2K1xQz", "USER_ID")

See Answer an access request.

withdraw_subject()#

Withdraws every consent the person has given, linked records included.

Returns int, the number of records withdrawn.

Errors Raises ConsentError.

withdrawn = client.withdraw_subject(
    "usr_8f2K1xQz",
    "USER_ID",
    reason="Account closed",
    idempotency_key="close-usr_8f2K1xQz",
)

erase_subject()#

Erases the person's identifiers on every record, linked records included, and removes the links.

Returns int, the number of records erased.

Errors Raises ConsentError.

erased = client.erase_subject(
    "usr_8f2K1xQz",
    "USER_ID",
    idempotency_key="erase-usr_8f2K1xQz",
)

See Withdraw and erase.

link_identifiers()#

Links more identifiers to every live record of a person.

Returns dict with records and added: records linked, and links added.

Errors Raises ValueError for an empty list, more than five identifiers, or an identifier that repeats.

client.link_identifiers(
    "usr_8f2K1xQz",
    "USER_ID",
    [Identifier("PHONE", "+919846099887")],
)

See Identifiers.

link_request()#

Points a rights request at the identifier the person's records are kept under.

Returns dict with reference and linkedRecordCount.

Errors Raises NotFoundError when no request in the project has that reference.

client.link_request("DSR-2026-4F2A91", "usr_8f2K1xQz", "USER_ID")

check_consent()#

Asks whether one person allows a purpose now.

Returns ConsentCheck. allowed is True only when the server answered granted. When no answer arrived, unavailable is True, reason is "unavailable", allowed is False, and cause is timeout, network, rate_limited or server_error.

Errors Raises ConsentError for 400, 401, 403 and 404, such as SCOPE_REQUIRED or PURPOSE_NOT_FOUND. Raises ValueError before any request for a timeout that is not positive, more than four also_known_as entries, or a repeated identifier.

from piedap_consent import Identifier

check = client.check_consent(
    "CIF00412873",
    "USER_ID",
    "offers-by-sms",
    also_known_as=[Identifier("PHONE", "+919846011223")],
)
if check.allowed:
    send_offer(check.based_on[0].consent_id)

See Check consent before you process.

Models#

All models are frozen dataclasses. Each from_dict ignores fields it does not know. Every time is a timezone-aware datetime.

• SubjectType is one of COOKIE_ID, SESSION_ID, EMAIL, USER_ID, PHONE and DEVICE_ID.
• DecisionInput is a Decision or a mapping. IdentifierInput is an Identifier or a mapping.
• Decision and AgeDeclaration accept only a real bool; a string such as "false" raises TypeError.
• Consent.granted() is True only when the purpose was allowed and the record is in force. Its status is then GRANTED, PARTIAL or DENIED, and expires_on has not passed.
• Receipt.payload is the signed document as the server sent it. Keep it unchanged.

Errors#

Everything the package raises for a failed call is a ConsentError.

Every exception carries these attributes:

from piedap_consent import ConsentError, RateLimitError

try:
    client.erase_subject(user.id, "USER_ID")
except RateLimitError as error:
    retry_later(error.retry_after or 60)
except ConsentError as error:
    if error.code == "SCOPE_REQUIRED":
        log_missing_scope("subjects:erase")
    raise

Every code is listed in Errors.