apollo-lunar 2024.4.16

A Python SDK/CLI for Lunar API

lunar-sdk

Contents

• Description
• Installation
• How to use
  • credentials
  • SDK
  • CLI
• Development
  • Requirements for development
  • Python environment
  • Documents generation

SDK for lunar microservices

Description

A Python based SDK & CLI for Lunar microservices

This python package includes

• Functions for lunar-rec
• CLI (Command Line Interface) named lunar

Installation

Build package and wheel files with poetry.

# installation
poetry install

poetry run lunar -h

How to use

Credentials

lunar uses a credentials file to setup a config(env, apikey) with a init file type.
The path for credentials file and format must be as follow:

[Path]

.lunar/credentials

[default]
env=local
apikey=ABCDEFG123

[dev]
env=dev
apikey=AERSDF123

[stg]
env=stg
apikey=HIJKLMNO456

[prd]
env=prd
apikey=PQRSTUV789

The first [default] is used when SDK / CLI is run without a specified profile.

To specify a profile, use AWS_PROFILE to overrides the default profile for commands that run in that session.

export AWS_PROFILE=stg

SDK

lunar package provides functions for using all lunar microservices. For the detailed information related to each function, please refer to Docs.

Here is an example for CRUDing channels:

import lunar

# Environment for Lunar-rec is automatically set with credential file
client = lunar.client("channel")

# Get list of channels
channels = client.get_channels()

# Get a channel
channel = client.get_channel(id="test_channel")

# Create a channel
channel = client.create_channel(id="new_channel", experiment_id="new_experiment")

# Update(or partial) a channel 
updated_channel = client.update_channel(id="test_channel", experiment_id="a")
partially_updated_channel = client.update_channel_partial(id="test_channel", experiment_id="ab")

# Delete a channel
client.delete_channel(channel.id)

All functions on the SDK also supports asyncio. If necessary, use an async version of each function.

• Naming rule: Suffix with _async. (e.g. list_channels() → list_channels_async())

CLI

lunar also provides CLI (Command Line Interface) generated by click package.

poetry run lunar -h

should show something like the below:

Usage: lunar [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  channel     Channels on lunar-rec
  experiment  Experiments on lunar-rec
  recommend   Recommendation on lunar-rec

Each option also has its own usage instruction.

poetry run lunar experiments -h

Usage: lunar experiment [OPTIONS] {CREATE|LIST|READ|UPDATE|DELETE}

  Experiments on lunar-rec

  Send a request to Lunar Recommendation API (`/v1/experiemnts/`).

  Return: dict or list(dict)

Options:
  -i, --id TEXT                   Unique identifier of a channel
  -b, --buckets <TEXT INTEGER>...
                                  Bucket list
  -s, --bucketing-seed TEXT       Random seed for bucketing
  -p, --partial                   Partial update or not (default: False)
  -h, --help                      Show this message and exit.

Development

Requirements for development

• Python 3.8
• Poetry

Installing Python 3.8 with pyenv is recommended. Check this.

For zsh,

# Install Xcode command line tools (Only if you don't have it already)
xcode-select --install

# Install pyenv and its dependencies
brew update
brew install pyenv openssl readline sqlite3 xz zlib

echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
eval '"$(pyenv init -)"' >> ~/.zshrc

# Restart the terminal

# Install Python 3.8
pyenv install 3.8.10
pyenv global 3.8.10

# Restart the terminal

# Check if the version is right
python -V

# Install Poetry
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
poetry config virtualenvs.in-project true

should work.

Python environment

poetry install

If you need additional deps,

# For production
poetry add package_name

# For development only
poetry add --dev package_name

Documents generation

rm -rf docs
pdoc --html --config show_source_code=False -f -o ./docs lunar