### Install LyricsGenius

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/index.md

Use pip to install the lyricsgenius library. An access token is required before using the library.

```bash
pip install lyricsgenius
```

--------------------------------

### Install LyricsGenius from GitHub

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/setup.md

Install the latest version of the lyricsgenius package directly from its GitHub repository using pip.

```bash
pip install git+https://github.com/johnwmillr/LyricsGenius.git
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/contributing.md

Install the package in developer mode with necessary dependencies for running tests. This command should be run from the LyricsGenius directory.

```bash
cd LyricsGenius
pip install -e .[dev]
```

--------------------------------

### Run Unit Tests

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/contributing.md

Execute the unit tests for your changes using tox. Ensure you have installed the development dependencies first.

```bash
tox -e test
```

--------------------------------

### Create Annotation Example

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Demonstrates how to create a new annotation for a given URL using the `update_annotation` method. Requires an authenticated Genius instance.

```python
genius = Genius(token)
new = genius.update_annotation('The annotation',
'https://example.com', 'illustrative examples', title='test')
print(new['id'])
```

--------------------------------

### Get All Songs of an Artist

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Retrieves all songs by a specified artist and saves their lyrics. Ensure you have authenticated with a valid token.

```python
genius = Genius(token)
artist = genius.search_artist('Andy Shauf')
artist.save_lyrics()
```

--------------------------------

### GET /users/{user_id}/questions_and_answers

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves a list of questions and answers (Q&As) created by a specific user. Supports pagination.

```APIDOC
## GET /users/{user_id}/questions_and_answers

### Description
Gets user’s Q&As. This method is an alias for `user_contributions()`.

### Method
GET

### Endpoint
`/users/{user_id}/questions_and_answers`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Maximum 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **text_format** (str) - Optional - Text format of the results. Options: 'dom', 'html', 'markdown', or 'plain'.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the user's Q&As.
```

--------------------------------

### Get Artist Songs (Specific Page)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves a specific page of songs for a given artist, with a defined number of results per page.

```python
# getting songs 11-15
songs = genius.artist_songs(380491, per_page=5, page=3)
```

--------------------------------

### GET /users/{user_id}/pyongs

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves a list of Pyongs created by a specific user. Supports pagination.

```APIDOC
## GET /users/{user_id}/pyongs

### Description
Gets user’s Pyongs. This method is an alias for `user_contributions()`.

### Method
GET

### Endpoint
`/users/{user_id}/pyongs`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Maximum 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **text_format** (str) - Optional - Text format of the results. Options: 'dom', 'html', 'markdown', or 'plain'.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the user's Pyongs.
```

--------------------------------

### GET /album/{album_id}

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves data for a specific album using its Genius album ID.

```APIDOC
## GET /album/{album_id}

### Description
Gets data for a specific album.

### Method
GET

### Endpoint
/album/{album_id}

### Parameters
#### Path Parameters
- **album_id** (int) - Required - Genius album ID

#### Query Parameters
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Returns
- **dict** - A dictionary containing the album data.

### Example
```python
genius = Genius(token)
song = genius.search_song(378195)
album_id = song['album']['id']
album = genius.album(album_id)
print(album['name'])
```
```

--------------------------------

### Initiate Full Code Exchange Authentication

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Use this to start the OAuth2 full code exchange flow. Provide your client ID, redirect URI, client secret, desired scope, and a state parameter for security.

```python
auth = OAuth2.full_code_exchange(
    'my_client_id',
    'my_redirect_uri',
    'my_client_secret',
    scope='all',
    state='some_unique_value'
)
```

--------------------------------

### Get User Token with Authorization Code

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

After the user authorizes your application, retrieve the authorization code and state from the request parameters. Then, exchange these for a user token using the previously initialized authentication object.

```python
code = request.args.get('code')
state = request.args.get('state')
token = auth.get_user_token(code, state)
```

--------------------------------

### Get Artist Data

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves data for a specific artist using their Genius artist ID. The text format of the results can be specified.

```python
genius = Genius(token)
artist = genius.artist(380491)
print(artist['name'])
```

--------------------------------

### GET /web_page

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves data for a specific web page. Requires at least one URL parameter and the page must have existing annotations.

```APIDOC
## GET /web_page

### Description
Gets data for a specific web page. Data is only available for pages that already have at least one annotation. You must pass at least one argument to the method.

### Method
GET

### Endpoint
/web_page

### Parameters
#### Query Parameters
- **raw_annotatable_url** (str) - Optional - The URL as it would appear in a browser.
- **canonical_url** (str) - Optional - The URL as specified by an appropriate <link> tag in a page’s <head>.
- **og_url** (str) - Optional - The URL as specified by an og:url <meta> tag in a page’s <head>.

### Returns
- **dict** - A dictionary containing the web page data.

### Example
```python
genius = Genius(token)
webpage = genius.web_page('docs.genius.com')
print(webpage['full_title'])
```
```

--------------------------------

### Get Artist Songs (Paginated)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves all songs by a specific artist, handling pagination to fetch all results. Songs can be sorted by popularity.

```python
# getting all artist songs based on popularity
genius = Genius(token)
page = 1
songs = []
while page:
    request = genius.artist_songs(380491,
                                  sort='popularity',
                                  per_page=50,
                                  page=page)
songs.extend(request['songs'])
page = request['next_page']
least_popular_song = songs[-1]['title']
```

--------------------------------

### Authenticate Another User (Client-Only)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Initializes the OAuth2 authentication flow for a client-only application. This setup is typically followed by prompting the user for authorization to access their data.

```python
from lyricsgenius import OAuth2, Genius

# client-only app
auth = OAuth2.client_only_app(
    'my_client_id',
    'my_redirect_uri',
    scope='all'
)
```

--------------------------------

### Get Album Data by Album ID with LyricsGenius

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Fetches data for a specific album using its Genius ID. This method can optionally format the returned text.

```python
genius = Genius(token)
song = genius.search_song(378195)
album_id = song['album']['id']
album = genius.album(album_id)
print(album['name'])
```

--------------------------------

### Get Lyrics for All Songs of a Search

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Fetches lyrics for all songs resulting from a search query. It iterates through the search hits, extracts the song URL, and then retrieves the lyrics for each song.

```python
genius = Genius(token)
lyrics = []

songs = genius.search_songs('Begin Again Andy Shauf')
for song in songs['hits']:
    url = song['result']['url']
    song_lyrics = genius.lyrics(song_url=url)
    # id = song['result']['id']
    # song_lyrics = genius.lyrics(id)
    lyrics.append(song_lyrics)
```

--------------------------------

### Get Songs by Tag (Genre)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Retrieves lyrics for songs associated with a specific tag (genre), such as 'pop'. The code paginates through results and collects lyrics. Note that results might be limited past the 50th page for popular tags.

```python
# this gets the lyrics of all the songs that have the pop tag.
genius = Genius(token)
page = 1
lyrics = []
while page:
    res = genius.tag('pop', page=page)
    for hit in res['hits']:
        song_lyrics = genius.lyrics(song_url=hit['url'])
        lyrics.append(song_lyrics)
    page = res['next_page']
```

--------------------------------

### Get Song Lyrics by URL or ID

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Fetches song lyrics using either the song's URL or its ID. Using a URL is direct, while using an ID requires an additional request to obtain the song URL.

```python
genius = Genius(token)

# Using Song URL
url = "https://genius.com/Andy-shauf-begin-again-lyrics"
genius.lyrics(song_url=url)

# Using Song ID
# Requires an extra request to get song URL
id = 2885745
genius.lyrics(id)
```

--------------------------------

### Initialize Genius with Access Token

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Import the package and create a Genius instance, passing your Genius API access token.

```python
import lyricsgenius
genius = lyricsgenius.Genius(token)
```

--------------------------------

### Command Line Usage: Help

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/usage.md

Set the GENIUS_ACCESS_TOKEN environment variable and then use the command line interface to view help information.

```bash
export GENIUS_ACCESS_TOKEN="my_access_token_here"
python3 -m lyricsgenius --help
```

--------------------------------

### GET /album/{album_id}/comments

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves the comments on a specific album page.

```APIDOC
## GET /album/{album_id}/comments

### Description
Gets the comments on an album page.

### Method
GET

### Endpoint
/album/{album_id}/comments

### Parameters
#### Path Parameters
- **album_id** (int) - Required - Genius album ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Cannot be more than 50.
- **page** (int) - Optional - Paginated offset (number of the page).
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Returns
- **dict** - A dictionary containing the album comments.
```

--------------------------------

### GET /albums/charts

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves the album charts based on specified time period and genre.

```APIDOC
## GET /albums/charts

### Description
Gets the album charts. This is an alias for the `charts()` method.

### Method
GET

### Endpoint
/albums/charts

### Parameters
#### Query Parameters
- **time_period** (str) - Optional - Time period of the results ('day', 'week', 'month' or 'all_time'). Defaults to 'day'.
- **chart_genre** (str) - Optional - The genre of the results. Defaults to 'all'.
- **per_page** (int) - Optional - Number of results to return per request. Cannot be more than 50.
- **page** (int) - Optional - Paginated offset (number of the page).
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Returns
- **dict** - A dictionary containing the album chart data.
```

--------------------------------

### Initialize Genius Client with User Token

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Once you have obtained the user's token, initialize the Genius client with this token to make authenticated API requests on behalf of the user.

```python
genius = Genius(token)
```

--------------------------------

### Get Authorization URL

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Obtain the URL to redirect the user to for authorization. This URL is generated by the authentication object.

```python
url_for_user = auth.url
print('Redirecting you to ' + url_for_user)
```

--------------------------------

### Genius Client Initialization

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Initialize the Genius client with your access token and configure various options for API requests.

```APIDOC
## Genius Client Initialization

### Description
Initializes the Genius client with an access token and various configuration options.

### Parameters
- **access_token** (str) - Optional - API key provided by Genius.
- **response_format** (str) - Optional - API response format ('dom', 'plain', 'html'). Defaults to 'plain'.
- **timeout** (int) - Optional - Time in seconds before quitting on response. Defaults to 5.
- **sleep_time** (float) - Optional - Time to wait between requests. Defaults to 0.2.
- **remove_section_headers** (bool) - Optional - If True, removes section headers like [Chorus] from lyrics. Defaults to False.
- **skip_non_songs** (bool) - Optional - If True, attempts to skip non-songs. Defaults to True.
- **excluded_terms** (list[str]) - Optional - Extra terms for flagging song titles as non-lyrics. These are matched case-insensitively as exact substrings.
- **replace_default_terms** (bool) - Optional - If True, replaces default excluded terms with user’s. Defaults to False.
- **retries** (int) - Optional - Number of retries in case of timeouts and errors. Defaults to 0.
- **user_agent** (str) - Optional - User agent for the request header.
- **proxy** (dict[str, str]) - Optional - Proxy settings.

### Returns
- **Genius** - An instance of the Genius client.
```

--------------------------------

### GET /users/{user_id}/transcriptions

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves a list of transcriptions created by a specific user. Supports pagination and sorting.

```APIDOC
## GET /users/{user_id}/transcriptions

### Description
Gets user’s transcriptions. This method is an alias for `user_contributions()`.

### Method
GET

### Endpoint
`/users/{user_id}/transcriptions`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Maximum 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **sort** (str) - Optional - Sorting preference. Options: 'title' or 'popularity'. Defaults to 'popularity'.
- **text_format** (str) - Optional - Text format of the results. Options: 'dom', 'html', 'markdown', or 'plain'.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the user's transcriptions.
```

--------------------------------

### GET /users/{user_id}/suggestions

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves a list of suggestions (comments) made by a specific user. Supports pagination.

```APIDOC
## GET /users/{user_id}/suggestions

### Description
Gets user’s suggestions (comments). This method is an alias for `user_contributions()`.

### Method
GET

### Endpoint
`/users/{user_id}/suggestions`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Maximum 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **text_format** (str) - Optional - Text format of the results. Options: 'dom', 'html', 'markdown', or 'plain'.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the user's suggestions.
```

--------------------------------

### Initialize Genius using Environment Variable

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

If no token is provided, the Genius class attempts to use the GENIUS_ACCESS_TOKEN environment variable.

```python
genius = Genius()
```

--------------------------------

### GET /users/{user_id}/articles

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves a list of articles created by a specific user. Supports pagination and sorting.

```APIDOC
## GET /users/{user_id}/articles

### Description
Gets user’s articles. This method is an alias for `user_contributions()`.

### Method
GET

### Endpoint
`/users/{user_id}/articles`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Maximum 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **sort** (str) - Optional - Sorting preference. Options: 'title' or 'popularity'. Defaults to 'popularity'.
- **text_format** (str) - Optional - Text format of the results. Options: 'dom', 'html', 'markdown', or 'plain'.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the user's articles.
```

--------------------------------

### Run Linting and Documentation Tests

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/contributing.md

Perform code linting with flake8 and documentation checks with doc8 using tox. This command also tests documentation creation.

```bash
tox -e lint
```

--------------------------------

### Command Line Usage: Song and Album

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/usage.md

Use the command line interface to search for and save lyrics for a given song and album.

```bash
python3 -m lyricsgenius song "Begin Again" "Andy Shauf" --save
python3 -m lyricsgenius album "The Party" "Andy Shauf" --save
```

--------------------------------

### Command Line: Print Song Lyrics (Text)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Use the command-line interface to print a song's lyrics to standard output in plain text format.

```bash
python -m lyricsgenius song "Check the Rhyme" "A Tribe Called Quest" --format txt
```

--------------------------------

### GET /users/{user_id}/unreviewed_annotations

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves a list of unreviewed annotations made by a specific user. Supports pagination and sorting.

```APIDOC
## GET /users/{user_id}/unreviewed_annotations

### Description
Gets user’s unreviewed annotations. This method is an alias for `user_contributions()`.
This method gets user annotations that have the “This annotations is unreviewed” sign above them.

### Method
GET

### Endpoint
`/users/{user_id}/unreviewed_annotations`

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Maximum 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **sort** (str) - Optional - Sorting preference. Options: 'title' or 'popularity'. Defaults to 'popularity'.
- **text_format** (str) - Optional - Text format of the results. Options: 'dom', 'html', 'markdown', or 'plain'.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the user's unreviewed annotations.
```

--------------------------------

### Run All Tests

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/contributing.md

Execute all available tests, including unit tests and linting checks, using tox. This provides a comprehensive test run before submitting changes.

```bash
tox
```

--------------------------------

### Command Line: Save Song Lyrics (JSON and Text)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Use the command-line interface to save a song's lyrics in both JSON and plain text formats.

```bash
python -m lyricsgenius song "Begin Again" "Andy Shauf" --format json txt --save
```

--------------------------------

### Search Artist Songs

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/usage.md

Import the package and search for songs by a given artist. Specify the maximum number of songs and sorting preference.

```python
from lyricsgenius import Genius

genius = Genius(token)
artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title")
print(artist.songs)
```

--------------------------------

### Get Referents for a Song

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves referents (annotations) for a specific song, allowing for pagination and filtering. Only one of `song_id` or `web_page_id` can be provided.

```python
# getting all verified annotations of a song (artist annotations)
genius = Genius(token)
request = genius.referents(song_id=235729,
                           per_page=50)
verified = [y for x in request['referents']
            for y in x['annotations'] if y['verified']]
```

--------------------------------

### Enable Logging

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Enable progress logging for the lyricsgenius package. Defaults to DEBUG level; can be set to logging.INFO for less output.

```python
import lyricsgenius
lyricsgenius.enable_logging()  # defaults to DEBUG; pass logging.INFO for less output
```

--------------------------------

### Authenticate Client-Only App

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Sets up authentication for a client-only application using OAuth2. Requires your client ID and redirect URI. The `prompt_user()` method initiates the authorization flow.

```python
from lyricsgenius import OAuth2, Genius

auth = OAuth2.client_only_app(
    'my_client_id',
    'my_redirect_uri',
    scope='all'
)

token = auth.prompt_user()

genius = Genius(token)
```

--------------------------------

### Authenticate using Environment Variables

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Loads Genius API credentials (client ID, redirect URI, client secret) from environment variables for authentication. This is a convenient way to manage sensitive information.

```python
import lyricsgenius as lg

client_id, redirect_uri, client_secret = lg.auth_from_environment()
```

--------------------------------

### Get Song Data

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves detailed data for a specific song using its Genius song ID. The text format of the results can be specified.

```python
genius = Genius(token)
song = genius.song(2857381)
print(song['full_title'])
```

--------------------------------

### OAuth2 Class Initialization

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/auth.md

Initialize the OAuth2 class with your client credentials and redirect URI. You can optionally provide a client secret, scope, state, and specify if it's a client-only app.

```APIDOC
## Initialize OAuth2

### Description
Instantiates the OAuth2 class for handling Genius API authentication.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
OAuth2(client_id: str, redirect_uri: str, client_secret: str | None = None, scope: tuple[Literal['me', 'create_annotation', 'manage_annotation', 'vote'], ...] | Literal['all'] | None = None, state: str | None = None, app_is_client_only: bool = False)
```

### Constructor Parameters
- **client_id** (str) - Required - Client ID for your Genius application.
- **redirect_uri** (str) - Required - Whitelisted redirect URI for your Genius application.
- **client_secret** (str) - Optional - Client secret for your Genius application.
- **scope** (tuple | str) - Optional - Defines the privileges for the access token. Can be a tuple of specific scopes or the string 'all'.
- **state** (str) - Optional - A value to maintain state between the request and callback.
- **app_is_client_only** (bool) - Optional - Defaults to False. Set to True for client-only authorization flow.

### Raises
- **AssertionError** - If neither `client_secret` nor `app_is_client_only` is supplied.

### Request Example
```python
from lyricsgenius.auth import OAuth2

# Example for a full-code exchange app
oauth = OAuth2(client_id='YOUR_CLIENT_ID', redirect_uri='YOUR_REDIRECT_URI', client_secret='YOUR_CLIENT_SECRET')

# Example for a client-only app
oauth_client_only = OAuth2.client_only_app(client_id='YOUR_CLIENT_ID', redirect_uri='YOUR_REDIRECT_URI')
```
```

--------------------------------

### Command Line: Save Artist Lyrics (Text)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Use the command-line interface to save an artist's lyrics to text files, with an option to limit the number of songs processed.

```bash
python -m lyricsgenius artist "The Beatles" --max-songs 2 --format txt --save
```

--------------------------------

### Command Line: Save Song Lyrics (JSON)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Use the command-line interface to search for a song and save its lyrics in JSON format.

```bash
python -m lyricsgenius song "Begin Again" "Andy Shauf" --format json --save
```

--------------------------------

### Configure Genius Client Options

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Set various options for the Genius client, such as removing section headers, including non-songs, or excluding specific terms from titles.

```python
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
```

--------------------------------

### Command Line Usage: Artist

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/usage.md

Use the command line interface to search for a specified number of songs by an artist and save their lyrics.

```bash
python3 -m lyricsgenius artist "The Beatles" --max-songs 5 --save
```

--------------------------------

### Get Tag Songs with Pagination

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieves lyrics for all songs within a specified tag, handling pagination. This method parses HTML and is slower than direct API calls.

```python
# getting the lyrics of all the songs in the pop tag.
genius = Genius(token)
page = 1
lyrics = []
while page:
    res = genius.tag('pop', page=page)
    for hit in res['hits']:
        song_lyrics = genius.lyrics(song_url=hit['url'])
        lyrics.append(song_lyrics)
    page = res['next_page']
```

--------------------------------

### Authentication Utilities

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/utils.md

Functions related to retrieving authentication credentials from environment variables.

```APIDOC
## auth_from_environment()

### Description
Gets credentials from environment variables.
Uses the following env vars: `GENIUS_CLIENT_ID`, `GENIUS_REDIRECT_URI` and `GENIUS_CLIENT_SECRET`.

### Method
GET (Conceptual - this is a utility function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
#### Success Response
- **client ID** (str | None) - The Genius client ID.
- **redirect URI** (str | None) - The redirect URI.
- **client secret** (str | None) - The Genius client secret.

### Response Example
```json
{
  "client_id": "your_client_id",
  "redirect_uri": "your_redirect_uri",
  "client_secret": "your_client_secret"
}
```
```

--------------------------------

### Command Line: Set Access Token

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Set the Genius API access token as an environment variable before running the command-line interface.

```bash
export GENIUS_ACCESS_TOKEN="my_access_token_here"
python -m lyricsgenius --help
```

--------------------------------

### Get Web Page Data with LyricsGenius

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Retrieves data for a specific web page using its URL. Ensure the page has at least one annotation. You must provide at least one URL argument.

```python
genius = Genius(token)
webpage = genius.web_page('docs.genius.com')
print(webpage['full_title'])
```

--------------------------------

### User Methods

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

This section covers methods related to retrieving user data.

```APIDOC
## GET /users/{user_id}

### Description
Gets data for a specific user.

### Method
GET

### Endpoint
/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Response
#### Success Response (200)
- **user_data** (dict) - Data for the specified user.

#### Response Example
{
  "user_data": {
    "id": 12345,
    "name": "ExampleUser",
    "url": "https://genius.com/users/12345"
  }
}
```

```APIDOC
## GET /users/{user_id}/accomplishments

### Description
Gets a user's accomplishments. This method retrieves the section titled "TOP ACCOMPLISHMENTS" from the user's profile.

### Method
GET

### Endpoint
/users/{user_id}/accomplishments

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Cannot exceed 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).

### Response
#### Success Response (200)
- **accomplishments** (dict) - A dictionary containing the user's accomplishments.

#### Response Example
{
  "accomplishments": {
    "sections": [
      {
        "title": "TOP ACCOMPLISHMENTS",
        "items": [
          "Verified Annotator",
          "Top Scholar"
        ]
      }
    ]
  }
}
```

```APIDOC
## GET /users/{user_id}/following

### Description
Gets the accounts a user follows.

### Method
GET

### Endpoint
/users/{user_id}/following

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Cannot exceed 50.
- **page** (int) - Optional - Paginated offset (page number).

### Response
#### Success Response (200)
- **following** (dict) - A dictionary containing the list of users the specified user follows.

#### Response Example
{
  "following": {
    "users": [
      {
        "id": 67890,
        "name": "AnotherUser",
        "url": "https://genius.com/users/67890"
      }
    ]
  }
}
```

```APIDOC
## GET /users/{user_id}/followers

### Description
Gets a user's followers.

### Method
GET

### Endpoint
/users/{user_id}/followers

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Cannot exceed 50.
- **page** (int) - Optional - Paginated offset (page number).

### Response
#### Success Response (200)
- **followers** (dict) - A dictionary containing the list of users who follow the specified user.

#### Response Example
{
  "followers": {
    "users": [
      {
        "id": 11223,
        "name": "FollowerOne",
        "url": "https://genius.com/users/11223"
      }
    ]
  }
}
```

```APIDOC
## GET /users/{user_id}/contributions

### Description
Gets a user's contributions. By default, contributions are returned in chronological order.

### Method
GET

### Endpoint
/users/{user_id}/contributions

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Cannot exceed 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **sort** (str) - Optional - Sorting preference ('title' or 'popularity'). Not all contribution types support sorting.
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').
- **type** (str) - Optional - Type of contribution ('annotations', 'articles', 'pyongs', 'questions_and_answers', 'comments', 'transcriptions' or 'unreviewed annotations').

### Response
#### Success Response (200)
- **contributions** (dict) - A dictionary containing the user's contributions.

#### Response Example
{
  "contributions": {
    "songs": [
      {
        "title": "Example Song",
        "artist": "Example Artist"
      }
    ]
  }
}
```

```APIDOC
## GET /users/{user_id}/annotations

### Description
Gets a user's annotations. This is an alias for the `user_contributions` method when the type is 'annotations'.

### Method
GET

### Endpoint
/users/{user_id}/annotations

### Parameters
#### Path Parameters
- **user_id** (int) - Required - Genius user ID

#### Query Parameters
- **per_page** (int) - Optional - Number of results to return per request. Cannot exceed 50.
- **next_cursor** (str) - Optional - Paginated offset (address of the next cursor).
- **sort** (str) - Optional - Sorting preference ('title' or 'popularity').
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Response
#### Success Response (200)
- **annotations** (dict) - A dictionary containing the user's annotations.

#### Response Example
{
  "annotations": {
    "songs": [
      {
        "title": "Annotated Song",
        "artist": "Some Artist"
      }
    ]
  }
}
```

--------------------------------

### Get Verified Annotations of a Song

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Use the `referents` method to retrieve annotations for a specific song ID. Filter for verified annotations by iterating through the results. Ensure `per_page` is set to 50 for maximum results per page.

```python
# getting all verified annotations of a song (artist annotations)
generator = Genius(token)
request = generator.referents(song_id=235729,
                           per_page=50)
verified = [y for x in request['referents']
            for y in x['annotations'] if y['verified']]
```

--------------------------------

### Public API Initialization

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

The PublicAPI class handles requests to the Genius.com public API. It can be initialized with optional parameters for response format, timeout, sleep time between requests, and retries. Calls to this API do not require an access token.

```APIDOC
## PublicAPI Initialization

### Description
Initializes the PublicAPI class for interacting with the Genius.com public API.

### Parameters
- **response_format** (str) - Optional - API response format ('dom', 'plain', 'html'). Defaults to 'plain'.
- **timeout** (int) - Optional - Time before quitting on response (seconds). Defaults to 5.
- **sleep_time** (float) - Optional - Time to wait between requests. Defaults to 0.2.
- **retries** (int) - Optional - Number of retries in case of timeouts and errors with a >= 500 response code. Defaults to 0.

### Returns
An object of the PublicAPI class.
```

--------------------------------

### Album Methods

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/genius.md

Retrieve information about specific albums and album charts.

```APIDOC
## GET /album/{album_id}

### Description
Gets data for a specific album.

### Method
GET

### Endpoint
/album/{album_id}

### Parameters
#### Path Parameters
- **album_id** (int) - Required - Genius album ID

#### Query Parameters
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Returns
#### Success Response (200)
- **dict** - A dictionary containing album data.

### Request Example
```python
genius = Genius(token)
song = genius.search_song(378195)
album_id = song['album']['id']
album = genius.album(album_id)
print(album['name'])
```
```

```APIDOC
## GET /albums/charts

### Description
Gets the album charts.

### Method
GET

### Endpoint
/albums/charts

### Parameters
#### Query Parameters
- **time_period** (str) - Optional - Time period of the results ('day', 'week', 'month' or 'all_time'). Defaults to 'day'.
- **chart_genre** (str) - Optional - The genre of the results. Defaults to 'all'.
- **per_page** (int) - Optional - Number of results to return per request. It can’t be more than 50.
- **page** (int) - Optional - Paginated offset (number of the page).
- **text_format** (str) - Optional - Text format of the results ('dom', 'html', 'markdown' or 'plain').

### Returns
#### Success Response (200)
- **dict** - A dictionary containing album chart data.
```

--------------------------------

### Get Artist's Least Popular Song

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/examples/snippets.md

Finds and prints the lyrics of an artist's least popular song. This involves searching for the artist, retrieving songs sorted by popularity, and then fetching the lyrics of the least popular one.

```python
genius = Genius(token)

artist = genius.search_artist('Andy Shauf', max_songs=1)
page = 1
songs = []
while page:
    request = genius.artist_songs(
                                  artist._id,
                                  sort='popularity',
                                  per_page=50,
                                  page=page,
                                  )
    songs.extend(request['songs'])
    page = request['next_page']
least_popular_song = genius.search_song(songs[-1]['title'], artist.name)
print(least_popular_song.lyrics)
```

--------------------------------

### Search and Save Album Lyrics

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Search for an album by its title and artist, then save all its lyrics to a file.

```python
album = genius.search_album("The Party", "Andy Shauf")
album.save_lyrics()
```

--------------------------------

### Download Album Cover Art

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/api.md

Use this method to retrieve the cover art URLs for a specific album. The returned dictionary contains a list of cover arts, from which you can access the image URL.

```python
import requests

genius = Genius(token)
res = genius.album_cover_arts(104614)
cover_art = requests.get(res['cover_arts'][0]['image_url'])
```

--------------------------------

### Date and URL Utilities

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/utils.md

Functions for converting data to datetime objects and parsing URLs.

```APIDOC
## convert_to_datetime(f: str | dict[str, int] | None) -> datetime | None

### Description
Converts argument to a datetime object.

### Method
N/A (Utility function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Datetime object** (datetime) - The converted datetime object.

### Response Example
```json
{
  "datetime_object": "2023-10-27T10:00:00"
}
```
```

```APIDOC
## parse_redirected_url(url: str, flow: str) -> str

### Description
Parse a URL for parameter ‘code’/’token’.

### Method
N/A (Utility function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Value of ‘code’/’token’** (str) - The extracted code or token from the URL.

#### Error Handling
- **KeyError**: if ‘code’/’token’ is not available or has multiple values.

### Response Example
```json
{
  "extracted_value": "authorization_code_or_token"
}
```
```

--------------------------------

### Add Song to Artist Object

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Add a retrieved song object or a song title string to an existing artist object.

```python
artist.add_song(song)
# the Artist object also accepts song names:
# artist.add_song("To You")
```

--------------------------------

### _make_request Method

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/reference/sender.md

Internal method to make a request to the Genius API.

```APIDOC
## POST /api/sender/_make_request

### Description
Makes a request to Genius.

### Method
POST

### Endpoint
/api/sender/_make_request

### Parameters
#### Query Parameters
- **path** (str) - Required - The API path to request.
- **method** (str) - Optional - The HTTP method to use. Defaults to 'GET'.
- **params_** (dict[str, Any] | list[tuple[Any, Any]] | None) - Optional - Parameters to send with the request.
- **public_api** (bool) - Optional - Whether to use the public API.
- **web** (bool) - Optional - Whether to make a web request.
- **kwargs** (Any) - Optional - Additional keyword arguments.
```

--------------------------------

### Download Artist Lyrics

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/docs/src/index.md

Download all lyrics for a given artist and save them to a JSON file. Ensure you have obtained an access token before initializing the Genius object.

```python
from lyricsgenius import Genius

genius = Genius(token)
artist = genius.search_artist('Andy Shauf')
artist.save_lyrics()
```

--------------------------------

### Search Artist Songs (Include Features)

Source: https://github.com/johnwmillr/lyricsgenius/blob/master/README.md

Search for all songs an artist appears on, including featured appearances, by setting `include_features` to True.

```python
artist = genius.search_artist("Andy Shauf", max_songs=3, sort="title", include_features=True)
print(artist.songs)
```