pypco package

Submodules

pypco.auth_config module

Internal authentication helper objects for pypco.

class pypco.auth_config.PCOAuthConfig(application_id: Optional[str] = None, secret: Optional[str] = None, token: Optional[str] = None, cc_name: Optional[str] = None)[source]

Bases: object

Auth configuration for PCO.

Parameters:
  • application_id (str) – The application ID for your application (PAT).
  • secret (str) – The secret for your application (PAT).
  • token (str) – The token for your application (OAUTH).
  • cc_name (str) – The vanity name portion of the <vanity_name>.churchcenter.com url
  • auth_type (PCOAuthType) – The authentication type specified by this config object.
auth_header

Get the authorization header for this authentication configuration scheme.

Returns:The authorization header text to pass as a request header.
Return type:str
auth_type

The authentication type specified by this configuration.

Raises:PCOCredentialsException – You have specified invalid authentication information.
Returns:The authentication type for this config.
Return type:PCOAuthType
class pypco.auth_config.PCOAuthType[source]

Bases: enum.Enum

Defines PCO authentication types.

OAUTH = 2
ORGTOKEN = 3
PAT = 1

pypco.exceptions module

All pypco exceptions.

exception pypco.exceptions.PCOCredentialsException[source]

Bases: pypco.exceptions.PCOException

Unusable credentials are supplied to pypco.

exception pypco.exceptions.PCOException[source]

Bases: Exception

A base class for all pypco exceptions.

exception pypco.exceptions.PCORequestException(status_code, message, response_body=None)[source]

Bases: pypco.exceptions.PCOException

The response from the PCO API indicated an error with your request.

Parameters:
  • status_code (int) – The HTTP status code corresponding to the error.
  • message (str) – The error message string.
  • response_body (str) – The body of the response (may include helpful information). Defaults to None.
status_code

The HTTP status code returned.

Type:int
message

The error message string.

Type:str
response_body

Text included in the response body. Often includes additional informative errors describing the problem encountered.

Type:str
exception pypco.exceptions.PCORequestTimeoutException[source]

Bases: pypco.exceptions.PCOException

Request to PCO timed out after the maximum number of retries.

exception pypco.exceptions.PCOUnexpectedRequestException[source]

Bases: pypco.exceptions.PCOException

An unexpected exception has occurred attempting to make the request.

We don’t have any additional information associated with this exception.

pypco.pco module

The primary module for pypco containing main wrapper logic.

class pypco.pco.PCO(application_id: Optional[str] = None, secret: Optional[str] = None, token: Optional[str] = None, cc_name: Optional[str] = None, api_base: str = 'https://api.planningcenteronline.com', timeout: int = 60, upload_url: str = 'https://upload.planningcenteronline.com/v2/files', upload_timeout: int = 300, timeout_retries: int = 3)[source]

Bases: object

The entry point to the PCO API.

Note

You must specify either an application ID and a secret or an oauth token. If you specify an invalid combination of these arguments, an exception will be raised when you attempt to make API calls.

Parameters:
  • application_id (str) – The application_id; secret must also be specified.
  • secret (str) – The secret for your app; application_id must also be specified.
  • token (str) – OAUTH token for your app; application_id and secret must not be specified.
  • api_base (str) – The base URL against which REST calls will be made. Default: https://api.planningcenteronline.com
  • timeout (int) – How long to wait (seconds) for requests to timeout. Default 60.
  • upload_url (str) – The URL to which files will be uploaded. Default: https://upload.planningcenteronline.com/v2/files
  • upload_timeout (int) – How long to wait (seconds) for uploads to timeout. Default 300.
  • timeout_retries (int) – How many times to retry requests that have timed out. Default 3.
delete(url: str, **params) → requests.models.Response[source]

Perform a DELETE request against the PCO API.

Performs a fully managed DELETE request (handles ratelimiting, timeouts, etc.).

Parameters:
  • url (str) – The URL against which to perform the request. Can include what’s been set as api_base, which will be ignored if this value is also present in your URL.
  • params – Any named arguments will be passed as query parameters. Values must be of type str!
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The response object returned by the API for this request. A successful delete request will return a response with an empty payload, so we return the response object here instead.
Return type:

requests.Response
get(url: str, **params) → Optional[dict][source]

Perform a GET request against the PCO API.

Performs a fully managed GET request (handles ratelimiting, timeouts, etc.).

Parameters:
  • url (str) – The URL against which to perform the request. Can include what’s been set as api_base, which will be ignored if this value is also present in your URL.
  • params – Any named arguments will be passed as query parameters.
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The payload returned by the API for this request.
Return type:

dict
iterate(url: str, offset: int = 0, per_page: int = 25, **params) → Iterator[dict][source]

Iterate a list of objects in a response, handling pagination.

Basically, this function wraps get in a generator function designed for processing requests that will return multiple objects. Pagination is transparently handled.

Objects specified as includes will be injected into their associated object and returned.

Parameters:
  • url (str) – The URL against which to perform the request. Can include what’s been set as api_base, which will be ignored if this value is also present in your URL.
  • offset (int) – The offset at which to start. Usually going to be 0 (the default).
  • per_page (int) – The number of results that should be requested in a single page. Valid values are 1 - 100, defaults to the PCO default of 25.
  • params – Any additional named arguments will be passed as query parameters. Values must be of type str!
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Yields:

dict – Each object returned by the API for this request. Returns “data”, “included”, and “meta” nodes for each response. Note that data is processed somewhat before being returned from the API. Namely, includes are injected into the object(s) with which they are associated. This makes it easier to process includes associated with specific objects since they are accessible directly from each returned object.
patch(url: str, payload: Optional[dict] = None, **params) → Optional[dict][source]

Perform a PATCH request against the PCO API.

Performs a fully managed PATCH request (handles ratelimiting, timeouts, etc.).

Parameters:
  • url (str) – The URL against which to perform the request. Can include what’s been set as api_base, which will be ignored if this value is also present in your URL.
  • payload (dict) – The payload for the PUT request. Must be serializable to JSON!
  • params – Any named arguments will be passed as query parameters. Values must be of type str!
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The payload returned by the API for this request.
Return type:

dict
post(url: str, payload: Optional[dict] = None, **params) → Optional[dict][source]

Perform a POST request against the PCO API.

Performs a fully managed POST request (handles ratelimiting, timeouts, etc.).

Parameters:
  • url (str) – The URL against which to perform the request. Can include what’s been set as api_base, which will be ignored if this value is also present in your URL.
  • payload (dict) – The payload for the POST request. Must be serializable to JSON!
  • params – Any named arguments will be passed as query parameters. Values must be of type str!
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The payload returned by the API for this request.
Return type:

dict
request_json(method: str, url: str, payload: Optional[Any] = None, upload: Optional[str] = None, **params) → Optional[dict][source]

A generic entry point for making a managed request against PCO.

This function will return the payload from the PCO response (a dict).

Parameters:
  • method (str) – The HTTP method to use for this request.
  • url (str) – The URL against which this request will be executed.
  • payload (obj) – A json-serializable Python object to be sent as the post/put payload.
  • upload (str) – The path to a file to upload.
  • params (obj) – A dictionary or list of tuples or bytes to send in the query string.
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The payload from the response to this request.
Return type:

dict
request_response(method: str, url: str, payload: Optional[Any] = None, upload: Optional[str] = None, **params) → requests.models.Response[source]

A generic entry point for making a managed request against PCO.

This function will return a Requests response object, allowing access to all request data and metadata. Executed request could be one of the standard HTTP verbs or a file upload. If you’re just looking for your data (json), use the request_json() function or get(), post(), etc.

Parameters:
  • method (str) – The HTTP method to use for this request.
  • url (str) – The URL against which this request will be executed.
  • payload (obj) – A json-serializable Python object to be sent as the post/put payload.
  • upload (str) – The path to a file to upload.
  • params (obj) – A dictionary or list of tuples or bytes to send in the query string.
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The response to this request.
Return type:

requests.Response
static template(object_type: str, attributes: Optional[dict] = None) → dict[source]

Get template JSON for creating a new object.

Parameters:
  • object_type (str) – The type of object to be created.
  • attributes (dict) – The new objects attributes. Defaults to empty.
Returns:

A template from which to set the new object’s attributes.
Return type:

dict
upload(file_path: str, **params) → Optional[dict][source]

Upload the file at the specified path to PCO.

Parameters:
  • file_path (str) – The path to the file to be uploaded to PCO.
  • params – Any named arguments will be passed as query parameters. Values must be of type str!
Raises:
  • PCORequestTimeoutException – The request to PCO timed out the maximum number of times.
  • PCOUnexpectedRequestException – An unexpected error occurred when making your request.
  • PCORequestException – The response from the PCO API indicated an error with your request.
Returns:

The PCO response from the file upload.
Return type:

dict

pypco.user_auth_helpers module

User-facing authentication helper functions for pypco.

pypco.user_auth_helpers.get_browser_redirect_url(client_id: str, redirect_uri: str, scopes: List[str]) → str[source]

Get the URL to which the user’s browser should be redirected.

This helps you perform step 1 of PCO OAUTH as described at: https://developer.planning.center/docs/#/introduction/authentication

Parameters:
  • client_id (str) – The client id for your app.
  • redirect_uri (str) – The redirect URI.
  • scopes (list) – A list of the scopes to which you will authenticate (see above).
Returns:

The url to which a user’s browser should be directed for OAUTH.
Return type:

str
pypco.user_auth_helpers.get_cc_org_token(cc_name: Optional[str] = None) → Optional[str][source]

Get a non-authenticated Church Center OrganizationToken.

Parameters:cc_name (str) – The organization_name part of the organization_name.churchcenter.com url.

Raises:

Returns:String of organization token
Return type:str
pypco.user_auth_helpers.get_oauth_access_token(client_id: str, client_secret: str, code: int, redirect_uri: str) → dict[source]

Get the access token for the client.

This assumes you have already completed steps 1 and 2 as described at: https://developer.planning.center/docs/#/introduction/authentication

Parameters:
  • client_id (str) – The client id for your app.
  • client_secret (str) – The client secret for your app.
  • code (int) – The code returned by step one of your OAUTH sequence.
  • redirect_uri (str) – The redirect URI, identical to what was used in step 1.
Raises:
  • PCORequestTimeoutException – The request timed out.
  • PCOUnexpectedRequestException – Something unexpected went wrong with the request.
  • PCORequestException – The HTTP response from PCO indicated an error.
Returns:

The PCO response to your OAUTH request.
Return type:

dict
pypco.user_auth_helpers.get_oauth_refresh_token(client_id: str, client_secret: str, refresh_token: str) → dict[source]

Refresh the access token.

This assumes you have already completed steps 1, 2, and 3 as described at: https://developer.planning.center/docs/#/introduction/authentication

Parameters:
  • client_id (str) – The client id for your app.
  • client_secret (str) – The client secret for your app.
  • refresh_token (str) – The refresh token for the user.
Raises:
  • PCORequestTimeoutException – The request timed out.
  • PCOUnexpectedRequestException – Something unexpected went wrong with the request.
  • PCORequestException – The HTTP response from PCO indicated an error.
Returns:

The PCO response to your token refresh request.
Return type:

dict

Module contents

A Pythonic Object-Oriented wrapper to the PCO API

pypco is a Python wrapper for the Planning Center Online (PCO) REST API intended to help you accomplish useful things with Python and the PCO API more quickly. pypco provides simple helpers wrapping the REST calls you’ll place against the PCO API, meaning that you’ll be spending your time directly in the PCO API docs rather than those specific to your API wrapper tool of choice.

usage:
>>> import pypco
>>> pco = pypco.PCO()

pypco supports both OAUTH and Personal Access Token (PAT) authentication.