lyrics-fetcher/sources/README.md

Not actually markdown, haha tricked ya!

Documentation for files in this folder.

1) For a file to be treated as a source, it must be a python script (.py). Other files are ignored.
2) It must be named with the domain it serves as the filename (starting from TLD and narrowing down; dots and slashes should be converted to underscores - the fetcher won't actually try to restore it and load the URL).
3) It must expose an "enabled" global boolean that, if False, will cause the fetcher to ignore its existence entirely. This is useful for sources that are temporarily not working, or for sources that are pending proper updates to the source's changes, etc.
4) It must expose a lyrics(song,band='',album='') function that returns song lyrics as plaintext (str), or as arranged lyrics (dict\[sections (list),arrangement (list)\]). It's recommended that if neither band nor album are given, the function should automatically return a failure, or explicitly recommend a search, rather than attempting to work with it.
5) It may expose other functions, such as:
- search(song,band='',album=''), which, as above, is recommended to automatically fail if only song is given
- index(band,album=''), which should return a list of the band's tracks (on that album), for populating the local index
- massfetch(band,album=''), which should fetch lyrics to all tracks of the band (on that album) and return them in a list
- This will, at some point, become a definitive list of optional functions that the fetcher supports; it will always accept recommendations for change.
6) Input formats: All names will be passed in exactly as the user presents the information, it is the source's job to wrangle it correctly into URLs. For example, "wither." is an album name that may be given to the source. It should generally assume that words will be separated with spaces, but there's no guarantee. Also it may occasionally get bands and songs passed in as each other. It isn't expected to figure that out.
7) Output: If a function returns more, or different, data than was expected (eg. lyrics are available on an album's track list), it is welcome to raise a utils.AdditionalData, containing a nested dictionary with the actual received data. The only valid keys are "name", "contents", "metadata" and "type". "type" must be one of "band", "album", "track". "metadata" will later allow other keys (such as "url", "duration", "number", "year", "artist" - for guest tracks, etc.). "contents" may be a dictionary which obeys the same rules. It is also welcome to raise a utils.NotFound with a message of "song", "lyrics", "band" or "album", to indicate a failure. The distinction between "song" and "lyrics" is that the song appears to exist, but no lyrics are present (not provided yet, or instrumental).
initcommit, I'll add .gitignore later 2021-11-17 22:44:26 +11:00			`Not actually markdown, haha tricked ya!`

			`Documentation for files in this folder.`

Some cleanup 2022-01-03 18:02:22 +11:00			`1) For a file to be treated as a source, it must be a python script (.py). Other files are ignored.`
initcommit, I'll add .gitignore later 2021-11-17 22:44:26 +11:00			`2) It must be named with the domain it serves as the filename (starting from TLD and narrowing down; dots and slashes should be converted to underscores - the fetcher won't actually try to restore it and load the URL).`
			`3) It must expose an "enabled" global boolean that, if False, will cause the fetcher to ignore its existence entirely. This is useful for sources that are temporarily not working, or for sources that are pending proper updates to the source's changes, etc.`
			`4) It must expose a lyrics(song,band='',album='') function that returns song lyrics as plaintext (str), or as arranged lyrics (dict\[sections (list),arrangement (list)\]). It's recommended that if neither band nor album are given, the function should automatically return a failure, or explicitly recommend a search, rather than attempting to work with it.`
			`5) It may expose other functions, such as:`
			`- search(song,band='',album=''), which, as above, is recommended to automatically fail if only song is given`
			`- index(band,album=''), which should return a list of the band's tracks (on that album), for populating the local index`
			`- massfetch(band,album=''), which should fetch lyrics to all tracks of the band (on that album) and return them in a list`
			`- This will, at some point, become a definitive list of optional functions that the fetcher supports; it will always accept recommendations for change.`
			`6) Input formats: All names will be passed in exactly as the user presents the information, it is the source's job to wrangle it correctly into URLs. For example, "wither." is an album name that may be given to the source. It should generally assume that words will be separated with spaces, but there's no guarantee. Also it may occasionally get bands and songs passed in as each other. It isn't expected to figure that out.`
Fails more cleanly now, even distinguishes between wrong name and no lyrics 2022-06-06 17:48:43 +10:00			7) Output: If a function returns more, or different, data than was expected (eg. lyrics are available on an album's track list), it is welcome to raise a utils.AdditionalData, containing a nested dictionary with the actual received data. The only valid keys are "name", "contents", "metadata" and "type". "type" must be one of "band", "album", "track". "metadata" will later allow other keys (such as "url", "duration", "number", "year", "artist" - for guest tracks, etc.). "contents" may be a dictionary which obeys the same rules. It is also welcome to raise a utils.NotFound with a message of "song", "lyrics", "band" or "album", to indicate a failure. The distinction between "song" and "lyrics" is that the song appears to exist, but no lyrics are present (not provided yet, or instrumental).