calitp-littlepay 2025.4.1

Cal-ITP API implementations and admin tasks for Littlepay.

Cal-ITP Littlepay

Cal-ITP API implementations and admin tasks for Littlepay.

This library is open-source software that is designed, developed, and maintained by Compiler LLC on behalf of Caltrans, Cal-ITP, and our agency partners.

Usage

$ littlepay -h
usage: littlepay [-h] [-v] [-c CONFIG_PATH] {config,groups,products,switch} ...

positional arguments:
  {config,groups,products,switch}
    config              Get or set configuration
    groups              Interact with groups in the active environment
    products            Interact with products in the active environment
    switch              Switch the active environment or participant

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -c CONFIG_PATH, --config CONFIG_PATH
                        Path to a readable and writeable config file to use.
                        File will be created if it does not exist.

Install

Use pip to install from GitHub:

pip install git+https://github.com/cal-itp/littlepay.git@main

Getting started

If this is your first time using littlepay, create a configuration file (using defaults):

littlepay config

The location and basic info from your current config file are printed in the terminal:

$ littlepay config
Creating config file: /home/calitp/.littlepay/config.yaml
Config: /home/calitp/.littlepay/config.yaml
Envs: prod, qa
Participants: cst
Active: qa, [no participant]

Add configuration

The configuration file is a YAML dictionary tracking envs and participants:

active:
  env: qa
  participant: ""
envs:
  prod:
    url: ""
  qa:
    url: ""
participants:
  cst:
    qa:
      audience: ""
      client_id: ""
      client_secret: ""
    prod:
      audience: ""
      client_id: ""
      client_secret: ""

There are two envs by default, the base API URL should be completed for each:

• qa is for the testing system
• prod is for the live system

Add specifics for the participants you manage based on information received from Littlepay support.

Use a different config file

littlepay config /path/to/new/config.yaml

Or

littlepay --config /path/to/new/config.yaml

The most recent config used is saved for next time.

Switch the active target

Use one or both of the -e/--env and -p/--participant flags:

littlepay switch -e <env_name> -p <participant_id>

Work with groups

$ littlepay groups -h
usage: littlepay groups [-h] [-f GROUP_TERMS] [--csv] {create,funding_sources,link,migrate,products,remove,unlink} ...

positional arguments:
  {create,funding_sources,link,migrate,products,remove,unlink}
    create              Create a new concession group
    funding_sources     List funding sources for one or more concession groups
    link                Link one or more concession groups to a product
    migrate             Migrate a group from the old Customer Group format to the current format
    products            List products for one or more concession groups
    remove              Remove an existing concession group
    unlink              Unlink a product from one or more concession groups

options:
  -h, --help            show this help message and exit
  -f GROUP_TERMS, --filter GROUP_TERMS
                        Filter for groups with matching group ID or label
  --csv                 Output results in simple CSV format

List existing groups

Print all groups in the active environment:

littlepay groups

Filter for groups with a matching ID or label:

littlepay groups -f <term>

Multiple filters are OR'd together:

littlepay groups -f <term1> -f <term2>

Create a new group

littlepay groups create <label>

Delete an existing group

With confirmation:

littlepay groups remove <group_id>

Without confirmation:

littlepay groups remove --force <group_id>

Work with products

$ littlepay products -h
usage: littlepay products [-h] [-f PRODUCT_TERMS] [-s {ACTIVE,INACTIVE,EXPIRED}] [--csv] {link,unlink} ...

positional arguments:
  {link,unlink}
    link                Link one or more products to a concession group
    unlink              Unlink a concession group from one or more products

options:
  -h, --help            show this help message and exit
  -f PRODUCT_TERMS, --filter PRODUCT_TERMS
                        Filter for products with matching product ID, code, or description
  -s {ACTIVE,INACTIVE,EXPIRED}, --status {ACTIVE,INACTIVE,EXPIRED}
                        Filter for products with matching status
  --csv                 Output results in simple CSV format

List existing products

littlepay products

Filtering works the same as for groups, matching against product ID, code, or description:

littlepay products -f <term>

littlepay products -f <term1> -f <term2>

Also supports filtering by status (ACTIVE, INACTIVE, EXPIRED):

littlepay products -s EXPIRED

littlepay products -f <term> -s ACTIVE

List linked products for one or more groups

For each group, output the group's linked products. Builds on the filtering sytax.

E.g. to list linked products for all groups:

littlepay groups products

Or to list linked products for a specific group:

littlepay groups -f <group_id> products

Link and unlink a product to one or more groups

For each group, link the given product to the group. Builds on the filtering syntax.

E.g. to link a product to all groups:

littlepay groups link <product_id>

Or to link a product to a specific group:

littlepay groups -f <group_id> link <product_id>

Unlinking groups from a product works the same:

littlepay groups -f <group_id> unlink <product_id>

Link and unlink a group to one or more products

For each product, link the given group to the product. Builds on the filtering syntax.

E.g. to link a group to all products:

littlepay products link <group_id>

Or to link a group to a specific product:

littlepay products -f <product_id> link <group_id>

Unlinking products from a group works the same:

littlepay products -f <product_id> unlink <group_id>

Version and release

The package version is derived from git metadata via setuptools_scm.

Pushing a tag with the correct format generates a new GitHub release, which can then be finalized and published.

Release a new version

1. Ensure you are on the latest commit of main:

   git checkout main
   git pull
   

2. Create an annotated, Calver-formatted tag based on the release year, month, and sequence counter:

   git tag -a YYYY.MM.N
   

   You may also create a release candidate, by appending -rcX where X is the release candidate sequence counter:

   git tag -a YYYY.MM.N-rcX
   

   In either case, provide a short comment for the tag.

3. Push the tag to GitHub:

   git push origin YYYY.MM.N
   

4. Observe the Release workflow