pycmc Python Chartmetric Client

A Python client for the Chartmetric API. Query artists, their music, and where their fans listen, by Musicfox.

And do it all in Python.

Installation

We highly recommend you install pycmc into some type of virtual environment.

Then you should use pip or the like:

pip install pycmc

or

pipenv install pycmc # latest release

Using Pipenv you may need to pin the version, unless you allow for pre-releases. We don't have a beta or alpha qualifier but view this software as such.

And don't forget you need an API subscription and subsequently, auth keys for Chartmetric -- see below.

⚠ Remember: You're not done yet; you'll need to set an authentication environment variable for queries.

Quick start

If you're already setup with your environment variable, you can query Rihanna's metadata with a quick call to the artist module:

>>> import pycmc
>>> rihanna_metadata = pycmc.artist.metadata(cmid=2316)

Yep, it's that simple.

"You should remember that it's peace of mind you're after and not just a fixed machine." -- Robert Pirsig, via Phaedrus

Authentication

Chartmetric requires an authorization process to query their API. You can see their docs here.

Add the CMCREDENTIALS environment variable

For pycmc you need to set a single environment variable, CMCREDENTIALS, to equal your JSON authentication string of the following:

{
    "token":"",
    "scope":"",
    "expires_in":"",
    "refreshtoken":"your-chartmetric-token-here",
}

🔎 Be sure the above is a string when you set your environment variable.

How to set up pycmc authentication

1. Save the JSON file above to disk and note the absolute directory.
2. Using your absolute directory below,

   # REQUIRED - Set your environment variable
   export CMCREDENTIALS=$(cat path/to/credentials/file.json)
   # OPTIONAL - Remove the .json file you created
   rm -rf path/to/credentials/file.json

Design

To somewhat follow the API design of chartmetric and make our lives easier here, we'll roughly adhere to the following module design where the pycmc package contains the following modules:

• album
• artist
• charts
• curator
• playlist
• track
• credentials
• credentials_manager
• utilities

Each module above provides (most) methods for a specific endpoint to the chartmetric.com API, (mostly) labelled as their GET endpoints.

For example,

>>> 'API ALBUM META URL' = 'https://api.charmetric.io/api/album/:id'

Album Metadata

To get an album's metadata just call the metadata function:

>>> import pycmc
>>> pycmc.album.metadata('chartmetricID') # return dict of album metatdata

Spotify top charts

Obviously we'll start with the elephant in the room and get the top charts from Spotify.

What was the US jamming to on the first day of the new year?

>>> cstracks = pycmc.charts.spotify.tracks(date='2019-01-01', ) 

Apple Music videos charts

What videos are charting in Apple Music on the same day as above?

>>> applemusic_vcharts = pycmc.charts.itunes.videos(date='2019-01-01')

Track metatdata

Let's get some metadata on the track Believe It by PARTYNEXTDOOR and Rihanna:

>>> believe_it = pycmc.track.metadata(cmid='28856569', )

Reference Documentation

We have hosted documentation over at our docs site pycmc.docs.musicfox.io, which review the many endpoints offered by the Chartmetric API.

Problems? Ideas?

We'd love to hear your feedback. Please use the Github for communication about pycmc.

🐛 Bug Reports 🐞

Please report bugs or problems in our issues in the Github repository.

🍨 Feature Requests

If you have an idea for a feature or suggestion, please open an issue the Github repository. Please describe what you're trying to accomplish and your idea to fix it with pycmc. We'll work through next steps on our end, or together if you'd like to contribute.

Contibutions to pycmc

Contributions are quite welcome and it's very easy to get started.

We ❤ community contributions!

Do note, we do require a contributor license agreement such that contributors' contributions are protected property, outside of the "open-source" MIT license covering code here.

Please see our CONTRIBUTING.md to get started.

pycmc development

Environment setup

• Create an .env file in the application directory: touch pycmc/.env and populate with:

  export CMCREDENTIALS="your-key"

• Jump into your dev shell:

  pipenv shell

• And populate your environment:

  source pycmc/.env

🎉 🎸 You're ready to rock! 🎸 🎉

Running the test suite

You'll obviously need to have an API key for Chartmetric to run tests.

ℹ️ The test suite is slowed to ~6s per request to the Chartmetric API to protect production usage of the same keys, likely an issue (which we've handled herein) since the API is rate limited.️

Run tests

pytest --cov=pycmc tests

Upload to the coverage tracker manually

First, DM @thinkjrs for the codecov token, which you'll need to set below.

Coverage is typically updated automagically but if you need to manually generate the coverage on https://codecov.io/gh/musicfox/pycmc, run:

export CODECOV_TOKEN="token-from-@thinkjrs"
./upload_coverage.bash

from your bash shell after running tests.

CI/CD on GCP

pycmc has a runner that builds a Python container, runs tests, and builds the documentation site when new commits are pushed. As of December 2020 this is private within the Musicfox Google Cloud Platform account.

Currently, you can track these builds in the action platform after you've been given access to the repo.

Coming soon! We are planning to migrate to another solution in the near future along with full tox-support (multiple python package build tests).