API Reference¶

The Client Object¶

class pympl.Client(wsdl=None, guid=None, password=None, server_name=None, user_id=0, params=None)[source]¶

The central object for interacting with a specific Ministry Platform server. Clients can be instantiated in the traditional pattern, such as:

client = Client('https://path/to/wsdl', guid, password, server_name)

Or, alternatively, you can place a .pympl file in your application’s directory and specify configuration parameters in that. This file is INI formatted. An example looks like:

[pympl]
wsgi = http://path/to/wsdl
guid = your_guid
password = your_password
server_name = your_server_name

If a .pympl file is found upon Client instantiation, it will be used for fallback parameters. This allows you to instantiate the client more simply:

client = Client()

Parameters:	wsdl (str) – The URL of the Ministry Platform WSDL. guid (str) – The Ministry Platform API GUID to connect with. password (str) – The API password to use. server_name (str) – The name of the Ministry Platform server. user_id (int) – The default user ID to use for API calls.

fn¶

An instance of pympl.function.FunctionRegistry. This object is used for initiating Ministry Platform SOAP function calls. For example, if one wants to call the MP function AuthenticateUser, the following can be done:

response = client.fn.AuthenticateUser('username', 'password')

In the instance of AuthenticateUser, a dictionary will be returned. Or, if an error occurred, a pympl.exc.FunctionError will be thrown.

sp¶

An instance of pympl.storedproc.StoredProcedureFactory. This object is used for initiating stored procedure calls on the MP MSSQL Server instance.

For example:

response = client.sp.api_GetFormResponseById(ResponseID=3)

table¶

An instance of pympl.table.TableFactory. Used to easily create Table objects bound to the client.

Request String Objects¶

class pympl.RequestString[source]¶

A simple class for creating properly-encoded Ministry Platform request strings. This is really just a standard dict with a custom __str__() method, which farms out the encoding.

Table Objects¶

class pympl.table.Table(client, name, primary_key=None)[source]¶

Table objects are a simple abstraction that sit on top of pympl’s SOAP function interface. They facilitate interacting with tables and records more akin to what you’d expect from an ORM.

To instantiate a table object, you should use the Client object’s table attribute, as this is an instance of TableFactory. Accessing any attribute on the TableFactory will create a Table object with that attribute’s name. By default, the primary key field is guessed by taking the singular form of the last word of the table’s name and appending _ID to it.

For example, if we wanted to get an Table object for the Contacts table, we can simply do:

Contacts = client.table.Contacts

This will return a Table object with the primary key field Contact_ID.

If the primary key for the table does not follow this convention, you may specify it manually like so:

Some_Table = client.table['Some_Table', 'Some_Table_ID']

Once a Table object is acquired, Record objects can be created by either calling the Table object or by calling the Table object’s record() method:

record = client.table.Contacts(First_Name='Bob')
# or, alternatively:
record2 = client.table.Contacts.record(First_Name='Bob')

__call__(*args, **kwargs)[source]¶

Creates a new Record object. Any keyword arguments passed will be used to initialize the record object with data.

This is calls Table.record() internally.

Returns:	A new record
Return type:	Record

record(*args, **initial_data)[source]¶

See documentation for Table.__call__().

class pympl.table.Record(table, initial_data)[source]¶

Provides an ORM-like interface to Ministry Platform records. These objects should almost always be instantiated by utilizing a Table object, generated via pympl.Client.table.

as_request_string()[source]¶

Returns the data as a pympl.RequestString object.

new¶

Whether or not the record all ready has a home in Ministry Platform or not. This is determined by checking if the table’s primary key field exists in the record and is truthy.

save(user_id=None)[source]¶

Saves the record to the database. If the record is “new”, then AddRecord is called; otherwise, UpdateRecord is.

Parameters:	user_id (int) – Optionally, one can specify which user should be used for the add/update operation. If none is provided, the user ID provided to the Client on initialization will be used (if any).
Returns:	The response from the database.
Return type:	tuple
Raises:	pympl.exc.AddRecordError – If new and operation fails. pympl.exc.UpdateRecordError – If not new and operation fails.

Functions¶

class pympl.function.FunctionRegistry(client)[source]¶

A simple object that facilitates instantiating function objects. Accessing an attribute of the function registry will return an instantiated function object, which can be used to query Ministry Platform:

# A function registry is always instantiated at Client.fn
function_instance = client.fn.AuthenticateUser

Functions are callables. Calling them will call Ministry Platform with the parameters specified:

response = function_instance('username', 'password')

For specific information about the various functions, the parameters they receive and the objects they return, please reference the various Function class docs:

• AddRecord
• UpdateRecord
• AuthenticateUser
• GetUserInfo
• AttachFile
• UpdateDefaultImage
• ExecuteStoredProcedure
• FindOrCreateUserAccount
• UpdateUserAccount
• ResetPassword

class pympl.function.Function(client)[source]¶

The base Function class that all of the others inherit from.

__call__(*args, **kwargs)[source]¶

A simple helper to make the function request and immediately return the result of its call() method.

This allows us to do things like:

# Get the function object
AuthenticateUser = client.fn.AuthenticateUser

# Now call it with the requested parameters
response = AuthenticateUser('username', 'password')

This is short hand for:

request = client.fn.AuthenticateUser.make_request(
    'username', 'password')
response = request.call()

make_request(*args, **kwargs)[source]¶

Creates and returns a request object for the function. This method is often overridden by specific functions to augment behavior.

Returns:	The request
Return type:	FunctionRequest

class pympl.function.AddRecord(client)[source]¶

Adds a record to a Ministry Platform table. Please note that it’s generally easier to use the pympl.Client.table attribute to access a table object and create/update records via that mechanism.

make_request(*args, **kwargs)[source]¶

Parameters:	TableName (str) – The name of the Ministry Platform table to add a record to. PrimaryKeyField (str) – The primary key field name of the table that you want to add a record to. This is typically the singular form of the table name, suffixed with _ID. For example, if you wanted to add a record to the Contacts table, the primary key field would be Contact_ID. RequestString (str|dict|RequestString) – Either an instance of pympl.RequestString or a manually-formatted Ministry Platform request string. See the Ministry Platform documentation on request strings if you want to perform the formatting yourself. Alternatively, you can also pass a dict as the request string and it will be converted to a RequestString object and used that way.
Returns:	A new request object, which can be used to query the Ministry Platform API.
Return type:	AddRecordRequest

class pympl.function.UpdateRecord(client)[source]¶

Like AddRecord but updates instead.

make_request(*args, **kwargs)[source]¶

Parameters:	TableName (str) – The name of the Ministry Platform table to add a record to. PrimaryKeyField (str) – The primary key field name of the table that you want to add a record to. This is typically the singular form of the table name, suffixed with _ID. For example, if you wanted to add a record to the Contacts table, the primary key field would be Contact_ID. RequestString (str|dict|RequestString) – Either an instance of pympl.RequestString or a manually-formatted Ministry Platform request string. See the Ministry Platform documentation on request strings if you want to perform the formatting yourself. Alternatively, you can also pass a dict as the request string and it will be converted to a RequestString object and used that way.
Returns:	A new request object, which can be used to query the Ministry Platform API
Return type:	UpdateRecordRequest

class pympl.function.AuthenticateUser(client)[source]¶

Calls the MP SOAP function ‘AuthenticateUser’. This is a common way to validate a user’s credentials and check for basic authorization.

For example, one might want to do something like this:

user_info = client.fn.AuthenticateUser('username', 'password')
user_info['CanImpersonate']
user_info['UserID']

make_request(*args, **kwargs)¶

Parameters:	UserName (str) – The user name to check. Password (str) – The password to check.
Returns:	The function request object
Return type:	FunctionRequest

class pympl.function.GetUserInfo(client)[source]¶

Gets information about the requested user ID. The response from the server is returned as a GetUserInfoResponse.

Example:

user_info = client.fn.GetUserInfo(UserID=234)
user_info.contact   # A Contact table object for the user
user_info.user  # A User table object for the user

make_request(*args, **kwargs)[source]¶

Parameters:	UserID (int) – The user ID to look up.
Returns:	The function request object.
Return type:	GetUserInfoRequest

class pympl.function.AttachFile(client)[source]¶

Attaches a file to a Ministry Platform record.

For example:

file_guid, error_code, message = client.fn.AttachFile(
    FileContents=open('/path/to/file.jpg'),
    FileName='myfile.jpg',
    PageID=23,
    RecordID=798,
    FileDescription='A picture of a thing',
    IsImage=True,
    ResizeLongestDimension=0  # Don't resize the image
)

make_request(*args, **kwargs)[source]¶

Parameters:	FileContents (file) – The file object to send to Ministry Platform. FileName (str) – The name of the file. PageID (int) – The page ID that the record belongs to. RecordID (int) – The record ID that you want to attach the file to. FileDescription (str) – A description of the file. IsImage (bool) – Whether or not the file is an image. ResizeLongestDimension (int) – The maximum size, in pixels, of an image’s longest side. Set to 0 to disable resize.
Returns:	The function request object
Return type:	AttachFileRequest

class pympl.function.ExecuteStoredProcedure(client)[source]¶

Executes a stored procedure on the Ministry Platform MSSQL Server instance.

NOTE: The pympl.client.Client.sp attribute is the preferred method of executing stored procedures.

make_request(*args, **kwargs)[source]¶

Parameters:	StoredProcedureName (str) – The name of the stored procedure to execute. Only stored procedures that begin with api can be called. RequestString (str|dict|RequestString) – The parameters to pass to the stored procedure.
Returns:	The function request object
Return type:	ExecuteStoredProcedureRequest

SOAP Function Request and Response Types¶

These objects are used primarily for parsing requests and responses to and from the Ministry Platform API. Normally, there’s no need to interact with them directly.

Function Request Objects¶

class pympl.function.FunctionRequest(function, args, kwargs)[source]¶

A simple object that binds the function being called with the arguments that are to be passed to that function when it is called.

This class is also responsible for creating the appropriate response, upon completion of the request. By default, the response is parsed to a standard dict. However, some functions return subclassed FunctionRequest which in turn parse responses into various other types of objects.

call()[source]¶

Parses arguments and calls the underlying Ministry Platform SOAP function.

class pympl.function.AddRecordRequest(function, args, kwargs)[source]¶

Parses the response into a tuple, if the request succeeds: (record_id, 0, message).

class pympl.function.UpdateRecordRequest(function, args, kwargs)[source]¶

Virtually identical to pympl.function.AddRecordRequest.

class pympl.function.GetUserInfoRequest(function, args, kwargs)[source]¶

A simple FunctionRequest object that returns a GetUserInfoResponse object, upon response parsing.

class pympl.function.AttachFileRequest(function, args, kwargs)[source]¶

A simple function request that parsers the string response into a convenient tuple: (guid, error_code, message).

class pympl.function.ExecuteStoredProcedureRequest(function, args, kwargs)[source]¶

The function request for stored procedures. Parses the API response into an instance of ExecuteStoredProcedureResponse.

Function Response Objects¶

class pympl.function.GetUserInfoResponse(request, response)[source]¶

Aggregates all of the data from GetUserInfo API call and dumps it into easy-to-use objects.

request¶

The function request object.

raw¶

The raw response XML.

contact¶

A Contacts Table object instantiated with the user’s contact record data.

user¶

A dp_Users Table object instantiated with the user’s user record data.

prefixes¶

A list of name prefixes from Ministry Platform.

Example:

[{'Prefix': 'Mr.', 'Prefix_ID': 1}, {'Prefix': 'Mrs.', 'Prefix_ID': 2}, ... ]

suffixes¶

A list of name suffixes from Ministry Platform.

Example:

[{'Suffix_ID': 1, 'Suffix': 'Jr.'}, {'Suffix_ID': 2, 'Suffix': 'Sr.'}, ... ]

genders¶

A list of genders from Ministry Platform.

Example:

[{'Gender_ID': 1, 'Gender': 'Male'}, {'Gender_ID': 2, 'Gender': 'Female'}]

marital_statuses¶

A list of marital satuses from Ministry Platform.

Example:

[
  {'Marital_Status': 'Single', 'Marital_Status_ID': 1},
  {'Marital_Status': 'Married', 'Marital_Status_ID': 2},
  ...
]

class pympl.function.ExecuteStoredProcedureResponse(request, response)[source]¶

Contains all of the table information returned by a stored procedure call. This object can be iterated over, which yields each of the response tables. In addition, each table can be accessed via attributes on the object, e.g. response.table, response.table2, response.table3.

as_dict()[source]¶

Converts the response tables as a dictionary.

Returns:	The stored procedure response.
Return type:	dict