pychex package¶

Pychex is a library which provides read-only programmatic and CLI access to account information for Paychex Benefits OnLine accounts. The command-line client serves as an example for anyone who wishes to build their own client (hint: Mint). To get started using the client, see Quick start.

Submodules¶

pychex.paychex module¶

This is the heart of the Pychex API. For examples, see Slow start.

class pychex.paychex.PaychexBase[source]¶

Bases: object

Base class for all classes in the paychex module.

Initialization prepares a mechanicalsoup.Browser object with the right presets and sets up some commond member variables.

class pychex.paychex.Paychex(username, security_image_path=None)[source]¶

Bases: pychex.paychex.PaychexBase

The Paychex class provides the ability to login to https://mypaychex.com and retrieve the Benefits OnLine username.

Initialization sets up member variables with the needed URLs and empty variables for credentials.

Arguments:

username – The username for logging in to https://mypaychex.com

Keyword arguments:

security_image_path – The security image path obtained and saved from a previous login. Makes it possible to skip a couple steps in the flow (optional).

get_bol_username()[source]¶

Get the Benefits OnLine app username via a SOAP request

Raises:

PychexUnauthenticatedError – If you haven’t logged in yet
PychexNoBolUsernameError – If there was no Benefits OnLine username in the XML returned from the API. This usually means that there is no Retirement account associated with the Paychex account.

Returns:

string – The Benefits OnLine username for use with the BenefitsOnline class

get_security_image()[source]¶

Returns the absolute url of the security image.

Raises:

PychexSecurityImageMissingError – If we don’t have an image yet

login(password)[source]¶

Login to Paychex using the username supplied previously, along with the password supplied as an argument.

Arguments:

password – The password for https://mypaychex.com

Raises:

PychexSecurityImageMissingError – If we don’t have an image yet
PychexInvalidPasswordError – If the password supplied is invalid

Returns:

bool – Whether login succeed or not

post_username()[source]¶

Post the username and save the security image. It is up to the client to verify this is the corrert security image before proceeding. If security_image_path was supplied during initialization, it will be verified here.

Raises:

PychexSecurityImageMismatchError – If the supplied security_image_path doesn’t match what is returned from Paychex

class pychex.paychex.BenefitsOnline(bol_username, password)[source]¶

Bases: pychex.paychex.PaychexBase

Used to login to the Paychex Benefits OnLine app.

Initialization sets up member variables containing credentials, and an empty variable to use for the RetirementServices object when we get it.

Arguments:

bol_username – The Benefits OnLine username obtained from Pychex.get_bol_username
password – The same password used to log in to https://mypaychex.com

login()[source]¶

Login to the Benefits Online portal using the credentials saved to member variables. If the login is successful, the retirement_services member variable will be populated with a RetirementServices object supplied with the current session, ready to login.

Raises:

PychexInvalidPasswordError – If you supplied the wrong password

Returns:

bool – Whether the login was successful or not

class pychex.paychex.RetirementServices(browser)[source]¶

Bases: pychex.paychex.PaychexBase

A class that provides read-only access to the Paychex Retirement Services app.

Initialization sets up empty member variables and overrides the browser member variable with the one passed in as an argument.

Member variables:

current_balance – The user’s current balance
vested_balance – The user’s vested balance
personal_ror – The user’s personal rate of return
balance_tab_info – The same information that is shown in the balance tab of Retirement Services, stored in a dictionary. An example of this can be seen in Quick start.

Arguments:

browser – A mechanicalsoup.Browser object. This Browser should be the same one that logged in to Benefits OnLine. This primes it for login to Retirement Services

formatted_summary()[source]¶

Format the summary in a more printable manner. This is the format presented by the CLI, as shown in Quick start.

Returns:

string – A formatted table of investment balance information, bearing a striking resemblence to the table in the balance tab of the Paychex Retirement Services app

get_account_summary()[source]¶

Get the 401k account summary. The Paychex Retirement Services app has many endpoints that respond with small snippets of HTML. This method hits a couple of them and saves the account summary information to the current_balance, vested_balance, personal_ror, and balance_tab_info member variables.

Raises:

PychexUnauthenticatedError – If you haven’t logged in to Retirement Services yet

Returns:

bool – Whether the method succeeded or not

login()[source]¶

Login to the retirement services app

Raises:

PychexUnknownError – In all my testing of this method, I never managed to reproduce an error. However, if the response doesn’t have a status code of 200, this exception will be raised.

Returns:

bool – Whether the login was successful or not

parse_balance_tab_data(res)[source]¶

Parse out the balance tab information from the HTML in the given response.

Arguments:

res – A response obj from a call to the Retirement Services accountSummary endpoint

Returns:

bool – Whether the method succeeded or not

pychex.cli module¶

Pychex command-line interface

Usage:
  pychex authorize <username> [--config=<config_file>]
  pychex account_summary [--config=<config_file>] [--json]
  pychex --version
  pychex (--help | -h)

Options:
  -h --help               Show this screen.
  --version               Show the version.
  --config=<config_file>  The config file to use [default: ./pychex.cfg]
  --json                  Optionally display output as JSON

class pychex.cli.PychexCli(arguments)[source]¶

This is the command line interface reference implementation of the API. It is not meant for consumption by third parties.

Initializes a config file and credentials (username, bol_username, security_image_path, and password), then calls the appropriate method to handle the command requested by the user.

Arguments:

arguments – a dictionary of command line arguments generated by docopt.

authorize(arguments)[source]¶

Authorizes a user with Paychex. Takes the following steps:

Collects the user’s username
Posts the username to the Paychex server to get the security image
Displays the security image to the user for verification using the default image viewer
Collects the user’s password
Logs in to Paychex and makes a SOAP request to get the user’s Benefits OnLine username
Encrypts and stores the credentials to a config file

Arguments:

arguments – The same dictionary passed to the __init__ method

get_account_summary(as_json)[source]¶

Log in to Benefits OnLine, get the account summary and display it to the console.

Arguments

as_json – Output the account summary in JSON format. Useful if a program such as a bash script will be used to do further data processing. Default is False and the summary will be printed in a table that is more palatable to a human.

get_input(text)[source]¶

Get’s input from the command line

Arguments: