Introducing instiz, my first published library on PyPI

Jonathan Nicholas — Fri, 23 Nov 2018 09:07:01 +0000

Hello, I'd like to introduce instiz, a wrapper to the iChart chart website for Python 3+. iChart is a real-time chart website for Korean music.

Chromadream / instiz

A Python3-only library for iChart K-Pop chart scores. CURRENTLY BROKEN.

instiz

A Python3-only library for iChart K-Pop chart scores.

Installation

pip install instiz

Getting Started

Getting started is easy. The following example is to get the top 10 at the realtime chart of iChart.

from instiz import iChart

ichart = iChart()
top_10 = ichart.realtime_top_10()

Type hinting

If you're using Python 3.7+'s type hinting feature, the type used for the return type of the chart can be imported from the instiz.models module.

from instiz.models import Entry

def get_name(entry: Entry) -> str:
    return entry.title

Artist name

It's now possible to get the Korean name and the English name of an artist easily, alongside with the raw artist name provided from iChart's site. Nice title property will always return the English name, unless unavailable. If one of the names are unavailable, the property will return an empty string.

from instiz

…

View on GitHub

Background

I recently started contributing to /r/kpop as a technical moderator. A glance on the organization may show that it's quite unusual for a Reddit community to use this much code, but it really helped the moderator's job, and provide value-addition to the users of the community.

Why does instiz exist?

The subreddit has a real-time charting widget of the songs, which was scraped from iChart hourly.

However, as Reddit pushes the redesign, a port of the widget to the redesign is required, so that there is no function disparity between users of the old site and the new site. And so, I started the porting attempt. However, a glance of the source code of the currently-running widget reveals a horribly nested mess. Not only that, the scraper and parser are coupled tightly to the actual updating function.

instiz is initially created to provide separation of concern between scraping process and widget update process. It can also be used for any kind of scripts, bots, or any programs that utilizes iChart's data.

Features

Even though the main functionality of instiz is fairly straightforward, which is to scrape and process the data from iChart, there are some noteworthy additional features inside it.

Sane artist name processing.

On iChart's site, artist names are inconsistently formatted. Examples include 제니 (JENNIE), TWICE (트와이스), 아이유(IU), and Queen(퀸). instiz ensures that Korean and English names are pre-processed and can be retrieved easily by the library's user, without the need of additional processing.

Code example:


from instiz import iChart

ichart = iChart()
first_place = ichart.get_next_entry()
nice_title = first_place.nice_title # "JENNIE - SOLO"
raw_artist_name = first_place.artist.raw_name # "제니 (JENNIE)"
english_artist_name = first_place.artist.english_name # "JENNIE"
korean_artist_name = first_place.artist.korean_name # "제니"

API refresh.

A refresh function is provided, so that developer doesn't have to initialize a new instance of the class each time a new set of data is needed.