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.
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.titleArtist 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…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.
Code example:
from instiz import iChart
ichart = iChart()
top_10 = ichart.realtime_top_10()
ichart.refresh()
top_10 = ichart.realtime_top_10()
- It's fully open-sourced.
instiz is published under MIT, and there are some "good first issue" for people wanting to start working on open-source culture. However, I realized that there are some items that usually is on open-source project missing from instiz. Please help me fulfil that by making a pull request.
Thank you.
Thank you for reading this post all the way to the bottom. I really appreciate it. Have a good day.
Top comments (0)