johnwmillr · allerter · Dec 4, 2018 · Dec 4, 2018 · Dec 7, 2018 · Dec 7, 2018
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Describe a bug associated with LyricsGenius
+
+---
+
+**Describe the bug**
+Write a clear and concise description of what the bug is.
+
+**Expected behavior**
+Write a clear and concise description of what you expected to happen.
+
+**To Reproduce**
+Describe the steps required to reproduce the behavior.
+1. Step one...
+2. Step two...
+
+Include the error message associated with the bug.
+
+**Version info**
+ - Package version [`import lyricsgenius; print(lyricsgenius.__version__)`]
+ - OS: [e.g. macOS, Windows, etc.]
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for improving LyricsGenius
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+Write a clear and concise description of what the problem is -- e.g. "I'm always frustrated when [...]"
+
+**Describe the solution you'd like**
+Write a clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+Write a clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.gitignore b/.gitignore
@@ -1,18 +1,30 @@
-# OSX
+# macOS
 *.DS_Store
 
 # API credentials
 *.ini
 
 # May not want to commit lyrics text files
 *.txt
+*.json
 
 # Jupyter
 /Notebooks
 .ipynb_checkpoints/
+*.ipynb
 
 # Test files
 .cache/
+.tox
+lyricsgenius.egg-info
+fixtures
 
 # Python module things
-*.pyc
+*.pyc
+
+# Python cache stuff
+*.egg-info
+__pycache__
+dist
+build
+.idea
diff --git a/.travis.yml b/.travis.yml
@@ -1,14 +1,5 @@
 language: python
-python:
- - "2.7"
-before_install:
-- openssl aes-256-cbc -K $encrypted_e334385ab253_key -iv $encrypted_e334385ab253_iv
-  -in credentials.ini.enc -out credentials.ini -d
 
-install: pip install -r requirements.txt
+install: pip install .[dev]
 
-script: python -m unittest discover
-
-notifications:
-  email:
-    - [email protected]
+script: tox
diff --git a/LICENSE → LICENSE.txt b/LICENSE → LICENSE.txt
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 John W. Miller
+Copyright (c) 2020 John W. Miller
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,82 +1,127 @@
-# Scraping song lyrics from Genius.com
+# LyricsGenius: a Python client for the Genius.com API
+[![Build Status](https://travis-ci.org/johnwmillr/LyricsGenius.svg?branch=master)](https://travis-ci.org/johnwmillr/LyricsGenius)
+[![Documentation Status](https://readthedocs.org/projects/lyricsgenius/badge/?version=master)](https://lyricsgenius.readthedocs.io/en/latest/?badge=master)
+[![PyPI version](https://badge.fury.io/py/lyricsgenius.svg)](https://pypi.org/project/lyricsgenius/)
+[![Python version](https://img.shields.io/badge/python-3.x-brightgreen.svg)](https://pypi.org/project/lyricsgenius/)
 
-[![Build Status](https://travis-ci.org/johnwmillr/GeniusAPI.svg?branch=master)](https://travis-ci.org/johnwmillr/GeniusAPI)
+`lyricsgenius` provides a simple interface to the song, artist, and lyrics data stored on [Genius.com](https://www.genius.com).
+
+The full documentation for `lyricsgenius` is available online at [Read the Docs](https://lyricsgenius.readthedocs.io/en/master/).
 
 ## Setup
-This repository is intended to provide an easy interface for programatically accessing the song information stored on [Genius.com](https://www.genius.com). Check out [my blog post](http://www.johnwmillr.com/blog/2017/scraping-genius-lyrics) for a more thorough description of the package and its usage.
+Before using this package you'll need to sign up for a (free) account that authorizes access to [the Genius API](http://genius.com/api-clients). The Genius account provides a `access_token` that is required by the package. See the [Usage section](https://github.com/johnwmillr/LyricsGenius#usage) below for examples.
+
+## Installation
+`lyricsgenius` requires Python 3.
 
-Start by cloning this repo:
+Use `pip` to install the package from PyPI:
 
 ```bash
-git clone https://github.com/johnwmillr/GeniusAPI.git
+pip install lyricsgenius
 ```
 
-To use the Genius API you'll need to sign up for a (free) client that authorizes you to [access their API](http://genius.com/api-clients). Fill out the ```credentials.ini``` file using the API client info you were assigned.
+Or, install the latest version of the package from GitHub:
+
+```bash
+pip install git+https://github.com/johnwmillr/LyricsGenius.git
+```
 
+## Usage
+Import the package and initiate Genius:
 
-You can read through the [Genius API docs](https://docs.genius.com/), but I've found it more helpful to start by looking at code folks have already written for the API. I found [this post](https://bigishdata.com/2016/09/27/getting-song-lyrics-from-geniuss-api-scraping) from @jackschultz and [this repository](https://github.com/jasonqng/genius-lyrics-search) from @JasonQNg real helpful while getting started, check their work out.
+```python
+import lyricsgenius
+genius = lyricsgenius.Genius(token)
+```
 
+If you don't pass a token to the `Genius` class, `lyricsgenus` will look for an environment variable called `GENIUS_ACCESS_TOKEN` and attempt to use that for authentication.
 
-## Scraping lyrics
-I'm most interested in a simple interface for pulling song lyrics from the website. It'd be nice to be able to enter a song and artist name and have the lyrics saved to a text file. Maybe we'd be interested in getting all lyrics associated with a single artist.
+```python
+genius = Genius()
+```
 
-Genius doesn't actually provide a way to access the lyrics using their API directly ([they have to pay royalties on the lyrics](https://www.nytimes.com/2014/05/07/business/media/rap-genius-website-agrees-to-license-with-music-publishers.html?ref=oembed&_r=0)), but it doesn't take much more work to scrape the HTML after finding the song URLs we're interested in. The python functions below both start by using the Genius API to search for a song's URL and then scraping that URL for lyrics using [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/).
+Search for songs by a given artist:
 
-## Usage
-### Python module
 ```python
->>> import genius
->>> api = genius.Genius()
->>> artist = api.search_artist('Andy Shauf',max_songs=5)
-Searching for Andy Shauf...
-
-Song 1: "Alexander All Alone"
-Song 2: "Begin Again"
-Song 3: "Comfortable With Silence"
-
-Reached user-specified song limit (3).
-Found 3 songs.
-
-Done.
->>> print(artist)
-Andy Shauf, 3 songs
->>> song = api.search_song('To You',artist.name)
-Searching for "To You" by Andy Shauf...
-Done.
->>> print(song)
-"To You" by Andy Shauf:
-    Jeremy can we talk a minute?
-    I've got some things that I need to
-    Get off of my chestI know that we h...
->>> artist.add_song(song)
->>> print(artist)
-Andy Shauf, 4 songs
+artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title")
+print(artist.songs)
 ```
+By default, the `search_artist()` only returns songs where the given artist is the primary artist.
+However, there may be instances where it is desirable to get all of the songs that the artist appears on.
+You can do this by setting the `include_features` argument to `True`.
 
-### Command line
+```python
+artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title", include_features=True)
+print(artist.songs)
 ```
-$ python genius/api.py --search_song 'Begin Again' 'Andy Shauf'
-Searching for "Begin Again" by Andy Shauf...
-Done.
-"Begin Again" by Andy Shauf:
-    Begin again
-    This time you should take a bow at the very end
-    Its quite an act you put on
-    Wait til the cameras roll...
-
-$ python genius/api.py --search_artist 'Lupe Fiasco'
-Searching for Lupe Fiasco...
-
-Song 1: "1st & 15th"
-Song 2: "4 Real"
-Song 3: "A Bathing Harry"
-Song 4: "Absolute Freestyle"
-Song 5: "Accept the Troubles"
-
-Reached user-specified song limit (5).
-Found 5 songs.
-
-Done.
-Lupe Fiasco, 5 songs
+
+Search for a single song by the same artist:
+
+```python
+song = artist.song("To You")
+# or:
+# song = genius.search_song("To You", artist.name)
+print(song.lyrics)
+```
+
+Add the song to the artist object:
+
+```python
+artist.add_song(song)
+# the Artist object also accepts song names:
+# artist.add_song("To You")
+```
+
+Save the artist's songs to a JSON file:
+
+```python
+artist.save_lyrics()
 ```
 
+Searching for an album and saving it:
+
+```python
+album = genius.search_album("The Party", "Andy Shauf")
+album.save_lyrics()
+```
+
+There are various options configurable as parameters within the `Genius` class:
+
+```python
+genius.verbose = False # Turn off status messages
+genius.remove_section_headers = True # Remove section headers (e.g. [Chorus]) from lyrics when searching
+genius.skip_non_songs = False # Include hits thought to be non-songs (e.g. track lists)
+genius.excluded_terms = ["(Remix)", "(Live)"] # Exclude songs with these words in their title
+```
+
+You can also call the package from the command line:
+
+```bash
+export GENIUS_ACCESS_TOKEN="my_access_token_here"
+python3 -m lyricsgenius --help
+```
+
+Search for and save lyrics to a given song and album:
+
+```bash
+python3 -m lyricsgenius song "Begin Again" "Andy Shauf" --save
+python3 -m lyricsgenius album "The Party" "Andy Shauf" --save
+```
+
+Search for five songs by 'The Beatles' and save the lyrics:
+
+```bash
+python3 -m lyricsgenius artist "The Beatles" --max-songs 5 --save
+```
+
+## Example projects
+
+  - [Trucks and Beer: A textual analysis of popular country music](http://www.johnwmillr.com/trucks-and-beer/)
+  - [Neural machine translation: Explaining the Meaning Behind Lyrics](https://github.com/tsandefer/dsi_capstone_3)
+  - [What makes some blink-182 songs more popular than others?](http://jdaytn.com/posts/download-blink-182-data/)
+  - [Sentiment analysis on hip-hop lyrics](https://github.com/Hugo-Nattagh/2017-Hip-Hop)
+  - [Does Country Music Drink More Than Other Genres?](https://towardsdatascience.com/does-country-music-drink-more-than-other-genres-a21db901940b)
+  - [49 Years of Lyrics: Why So Angry?](https://towardsdatascience.com/49-years-of-lyrics-why-so-angry-1adf0a3fa2b4)
+
+## Contributing
+Please contribute! If you want to fix a bug, suggest improvements, or add new features to the project, just [open an issue](https://github.com/johnwmillr/LyricsGenius/issues) or send me a pull request.
diff --git a/credentials.ini.enc b/credentials.ini.enc
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = src
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=src
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx==3.3.0
+sphinx-rtd-theme==0.5.0
diff --git a/docs/src/404.png b/docs/src/404.png
diff --git a/docs/src/404.rst b/docs/src/404.rst
@@ -0,0 +1,27 @@
+.. image:: 404.png
+
+
+Whoops!
+========
+The page you're looking for doesn't exist. Let's go
+:ref:`home <index>`.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Library
+
+   reference
+   release_notes
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Guide
+
+   setup
+   usage
+   contributing
+
+
+.. _Genius.com: https://www.genius.com