Globals

Constants

Regexes

INVALID_CHARS

fpclib.INVALID_CHARS

A compiled pattern that matches invalid charaters to be in a folder name.

re.compile(r'(?<!^\w)[/<>:\"\\\|\?\*\x00-\x1F]')

INVALID_CHARS_NO_SLASH

fpclib.INVALID_CHARS_NO_SLASH

A compiled pattern that matches invalid charaters to be in a folder name except forward and back-slashes.

re.compile(r'(?<!^\w)[<>:\"\|\?\*\x00-\x1F]')

DATE

fpclib.DATE

A compiled pattern that matches properly formatted dates.

re.compile(r'^\d{4}(\-\d{2}){0,2}$')

PORT

fpclib.PORT

A compiled pattern that matches port numbers of urls with the prefixed colon.

re.compile(r':\d+')

PROTOCOL

fpclib.PROTOCOL

A compiled pattern that matches the protocol (e.g., “http://”, “//”, or even “/”) part of a url.

re.compile(r'^[^/\\\.]*(:|/+)')

PROPER_PROTOCOL

fpclib.PROPER_PROTOCOL

A compiled pattern that matches properly formatted protocols.

re.compile(r'^[a-zA-Z]+://[^/]')

EXTENSION

fpclib.EXTENSION

A compiled pattern that matches file extensions.

re.compile(r'\.[^/\]+$')

UUID

fpclib.UUID

A compiled pattern that matches uuids.

re.compile(r'[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}')

STARTING_PARENTHESES

fpclib.STARTING_PARENTHESES

A compiled pattern that matches parentheses and surrounding spaces at the beginning of a string (e.g., ” (This) ” in ” (This) Some text with a ‘)’”).

re.compile(r'^\s*\(.*?\)\s*')

Since 1.3

Application Paths

SECURE_PLAYER

fpclib.SECURE_PLAYER = 'FPSoftware\\FlashpointSecurePlayer.exe'

Application path for Flashpoint Secure Player.

JAVA

fpclib.JAVA = 'FPSoftware\\startJava.bat'

Application path for Java.

JAVA_IN_BROWSER

fpclib.JAVA_IN_BROWSER = 'FPSoftware\\startJavaInBrowser.bat'

Application path for Java in browser.

Since 1.3

BASILISK

fpclib.BASILISK = 'FPSoftware\\Basilisk-Portable\\Basilisk-Portable.exe'

Application path for Basilisk.

FLASH_PLAYERS

fpclib.FLASH_PLAYERS

A table of all application paths for all flash players, mapped to version numbers. Allowed values are listed in the table below. Notice that negative values indicate that the specific player is in a folder, and 0 indicates the default version.

Version

Application Path

0

FPSoftware\Flash\flashplayer_32_sa.exe

32

FPSoftware\Flash\flashplayer_32_sa.exe

29

FPSoftware\Flash\flashplayer29_0r0_171_win_sa.exe

28

FPSoftware\Flash\flashplayer28_0r0_161_win_sa.exe

27

FPSoftware\Flash\flashplayer27_0r0_187_win_sa.exe

19

FPSoftware\Flash\flashplayer19_0r0_245_sa.exe

14

FPSoftware\Flash\flashplayer14_0r0_179_win_sa.exe

11

FPSoftware\Flash\flashplayer11_9r900_152_win_sa_debug.exe

10

FPSoftware\Flash\flashplayer_10_3r183_90_win_sa.exe

9

FPSoftware\Flash\flashplayer9r277_win_sa.exe

-9

FPSoftware\Flash\9r16\SAFlashPlayer.exe

-8

FPSoftware\Flash\8r22\SAFlashPlayer.exe

7

FPSoftware\Flash\flashplayer_7_sa.exe

-7

FPSoftware\Flash\7r14\SAFlashPlayer.exe

-6.21

FPSoftware\Flash\6r21\SAFlashPlayer.exe

-6.4

FPSoftware\Flash\6r4\SAFlashPlayer.exe

-5

FPSoftware\Flash\5r30\FlashPla.exe

-4.7

FPSoftware\Flash\4r7\FlashPla.exe

-4.4

FPSoftware\Flash\4r4\FlashPla.exe

-3

FPSoftware\Flash\3r8\SwFlsh32.exe

-2

FPSoftware\Flash\2r11\SwFlsh32.exe

FLASH

fpclib.FLASH = 'FPSoftware\\Flash\\flashplayer_32_sa.exe'

A shorthand for FLASH_PLAYERS[0]

SHOCKWAVE_PLAYERS

fpclib.SHOCKWAVE_PLAYERS

A table of all application paths for all shockwave players, mapped to version numbers and strings. Allowed values are listed in the table below. Notice that SPRS and Projector should not typically be used for curations, and though you can use SPRD for debugging, you shouldn’t submit your final curation with it. ‘0’ or 0 indicates the default version.

Version

Application Path

0 or ‘0’

FPSoftware\Shockwave\PJ101\SPR.exe

9 or ‘9’

FPSoftware\Shockwave\PJ9\SPR.exe

‘9D’

FPSoftware\Shockwave\PJ9\SPRD.exe

‘9S’

FPSoftware\Shockwave\PJ9\SPRS.exe

‘9P’

FPSoftware\Shockwave\PJ9\Projector.exe

12 or ‘12’

FPSoftware\Shockwave\PJ12\SPR.exe

‘12D’

FPSoftware\Shockwave\PJ12\SPRD.exe

‘12S’

FPSoftware\Shockwave\PJ12\SPRS.exe

‘12P’

FPSoftware\Shockwave\PJ12\Projector.exe

101 or ‘101’

FPSoftware\Shockwave\PJ101\SPR.exe

‘101D’

FPSoftware\Shockwave\PJ101\SPRD.exe

‘101S’

FPSoftware\Shockwave\PJ101\SPRS.exe

‘101P’

FPSoftware\Shockwave\PJ101\Projector.exe

851 or ‘851’

FPSoftware\Shockwave\PJ851\SPR.exe

‘851D’

FPSoftware\Shockwave\PJ851\SPRD.exe

‘851S’

FPSoftware\Shockwave\PJ851\SPRS.exe

‘851P’

FPSoftware\Shockwave\PJ851\Projector.exe

1103 or ‘1103’

FPSoftware\Shockwave\PJ1103\SPR.exe

‘1103D’

FPSoftware\Shockwave\PJ1103\SPRD.exe

‘1103S’

FPSoftware\Shockwave\PJ1103\SPRS.exe

‘1103P’

FPSoftware\Shockwave\PJ1103\Projector.exe

1159 or ‘1159’

FPSoftware\Shockwave\PJ1159\SPR.exe

‘1159D’

FPSoftware\Shockwave\PJ1159\SPRD.exe

‘1159S’

FPSoftware\Shockwave\PJ1159\SPRS.exe

‘1159P’

FPSoftware\Shockwave\PJ1159\Projector.exe

SHOCKWAVE

fpclib.SHOCKWAVE = 'FPSoftware\\Shockwave\\PJ101\\SPR.exe'

A shorthand for SHOCKWAVE_PLAYERS[0]

UNITY

fpclib.UNITY = 'FPSoftware\\startUnity.bat'

Application path for Unity. Normally you should use SECURE_PLAYER instead.

ACTIVE_X

fpclib.ACTIVE_X = 'FPSoftware\\startActiveX.bat'

Application path for ActiveX. Normally you should use SECURE_PLAYER instead.

Since 1.3

GROOVE

fpclib.GROOVE = 'FPSoftware\\startGroove.bat'

Application path for 3D Groove GX. Normally you should use SECURE_PLAYER instead.

Since 1.3

SVR

fpclib.SVR = 'FPSoftware\\startSVR.bat'

Application path for Viscape. Normally you should use SECURE_PLAYER instead.

Since 1.3

APPLICATIONS

fpclib.APPLICATIONS = {'FPSoftware\\Basilisk-Portable\\Basilisk-Portable.exe', 'FPSoftware\\Flash\\2r11\\SwFlsh32.exe', 'FPSoftware\\Flash\\3r8\\SwFlsh32.exe', 'FPSoftware\\Flash\\4r4\\FlashPla.exe', 'FPSoftware\\Flash\\4r7\\FlashPla.exe', 'FPSoftware\\Flash\\5r30\\FlashPla.exe', 'FPSoftware\\Flash\\6r21\\SAFlashPlayer.exe', 'FPSoftware\\Flash\\6r4\\SAFlashPlayer.exe', 'FPSoftware\\Flash\\7r14\\SAFlashPlayer.exe', 'FPSoftware\\Flash\\8r22\\SAFlashPlayer.exe', 'FPSoftware\\Flash\\9r16\\SAFlashPlayer.exe', 'FPSoftware\\Flash\\flashplayer11_9r900_152_win_sa_debug.exe', 'FPSoftware\\Flash\\flashplayer14_0r0_179_win_sa.exe', 'FPSoftware\\Flash\\flashplayer19_0r0_245_sa.exe', 'FPSoftware\\Flash\\flashplayer27_0r0_187_win_sa.exe', 'FPSoftware\\Flash\\flashplayer28_0r0_161_win_sa.exe', 'FPSoftware\\Flash\\flashplayer29_0r0_171_win_sa.exe', 'FPSoftware\\Flash\\flashplayer9r277_win_sa.exe', 'FPSoftware\\Flash\\flashplayer_10_3r183_90_win_sa.exe', 'FPSoftware\\Flash\\flashplayer_32_sa.exe', 'FPSoftware\\Flash\\flashplayer_7_sa.exe', 'FPSoftware\\FlashpointSecurePlayer.exe', 'FPSoftware\\Shockwave\\PJ101\\Projector.exe', 'FPSoftware\\Shockwave\\PJ101\\SPR.exe', 'FPSoftware\\Shockwave\\PJ101\\SPRD.exe', 'FPSoftware\\Shockwave\\PJ101\\SPRS.exe', 'FPSoftware\\Shockwave\\PJ1103\\Projector.exe', 'FPSoftware\\Shockwave\\PJ1103\\SPR.exe', 'FPSoftware\\Shockwave\\PJ1103\\SPRD.exe', 'FPSoftware\\Shockwave\\PJ1103\\SPRS.exe', 'FPSoftware\\Shockwave\\PJ1159\\Projector.exe', 'FPSoftware\\Shockwave\\PJ1159\\SPR.exe', 'FPSoftware\\Shockwave\\PJ1159\\SPRD.exe', 'FPSoftware\\Shockwave\\PJ1159\\SPRS.exe', 'FPSoftware\\Shockwave\\PJ12\\Projector.exe', 'FPSoftware\\Shockwave\\PJ12\\SPR.exe', 'FPSoftware\\Shockwave\\PJ12\\SPRD.exe', 'FPSoftware\\Shockwave\\PJ12\\SPRS.exe', 'FPSoftware\\Shockwave\\PJ851\\Projector.exe', 'FPSoftware\\Shockwave\\PJ851\\SPR.exe', 'FPSoftware\\Shockwave\\PJ851\\SPRD.exe', 'FPSoftware\\Shockwave\\PJ851\\SPRS.exe', 'FPSoftware\\Shockwave\\PJ9\\Projector.exe', 'FPSoftware\\Shockwave\\PJ9\\SPR.exe', 'FPSoftware\\Shockwave\\PJ9\\SPRD.exe', 'FPSoftware\\Shockwave\\PJ9\\SPRS.exe', 'FPSoftware\\startActiveX.bat', 'FPSoftware\\startGroove.bat', 'FPSoftware\\startJava.bat', 'FPSoftware\\startJavaInBrowser.bat', 'FPSoftware\\startSVR.bat', 'FPSoftware\\startUnity.bat'}

A set of all valid application paths.

Since 1.3

Flags

EVERYTHING

fpclib.EVERYTHING = int('1111', 2)

A flag for Curation.save() that says to save everything. This is equivalent to META|LOGO|SS|CONTENT.

META

fpclib.META = int('1000', 2)

A flag for Curation.save() that says to save meta.

IMAGES

fpclib.IMAGES = int('0110', 2)

A flag for Curation.save() that says to save images. This is equivalent to LOGO|SS.

SS

fpclib.SS = int('0010', 2)

A flag for Curation.save() that says to save the screenshot.

CONTENT

fpclib.CONTENT = int('0001', 2)

A flag for Curation.save() that says to save the content of the curation downloaded with Curation.get_files().

Other

LANGUAGES

fpclib.LANGUAGES = {'aa', 'ab', 'ae', 'af', 'ak', 'am', 'an', 'ar', 'as', 'av', 'ay', 'az', 'ba', 'be', 'bg', 'bh', 'bi', 'bm', 'bn', 'bo', 'br', 'bs', 'ca', 'ce', 'ch', 'co', 'cr', 'cs', 'cu', 'cv', 'cy', 'da', 'de', 'dv', 'dz', 'ee', 'el', 'en', 'eo', 'es', 'et', 'eu', 'fa', 'ff', 'fi', 'fj', 'fo', 'fr', 'fy', 'ga', 'gd', 'gl', 'gn', 'gu', 'gv', 'ha', 'he', 'hi', 'ho', 'hr', 'ht', 'hu', 'hy', 'hz', 'ia', 'id', 'ie', 'ig', 'ii', 'ik', 'io', 'is', 'it', 'iu', 'ja', 'jv', 'ka', 'kg', 'ki', 'kj', 'kk', 'kl', 'km', 'kn', 'ko', 'kr', 'ks', 'ku', 'kv', 'kw', 'ky', 'la', 'lb', 'lg', 'li', 'ln', 'lo', 'lt', 'lu', 'lv', 'mg', 'mh', 'mi', 'mk', 'ml', 'mn', 'mr', 'ms', 'mt', 'my', 'na', 'nb', 'nd', 'ne', 'ng', 'nl', 'nn', 'no', 'nr', 'nv', 'ny', 'oc', 'oj', 'om', 'or', 'os', 'pa', 'pi', 'pl', 'ps', 'pt', 'qu', 'rm', 'rn', 'ro', 'ru', 'rw', 'sa', 'sc', 'sd', 'se', 'sg', 'si', 'sk', 'sl', 'sm', 'sn', 'so', 'sq', 'sr', 'ss', 'st', 'su', 'sv', 'sw', 'ta', 'te', 'tg', 'th', 'ti', 'tk', 'tl', 'tn', 'to', 'tr', 'ts', 'tt', 'tw', 'ty', 'ug', 'uk', 'ur', 'uz', 've', 'vi', 'vo', 'wa', 'wo', 'xh', 'yi', 'yo', 'za', 'zh', 'zu'}

A set of all ISO 639-1 language codes copy and pasted from Wikipedia.

Since 1.3

LIBRARIES

fpclib.LIBRARIES = {'arcade', 'theatre'}

Set of all Flashpoint libraries.

Since 1.3

PLAY_MODES

fpclib.PLAY_MODES = {'Cooperative', 'Multiplayer', 'Single Player'}

Set of all Flashpoint play modes. :code:`; ` can be used to combine them.

STATUSES

fpclib.STATUSES = {'Hacked', 'Hacked; Partial', 'Not Working', 'Partial', 'Partial; Hacked', 'Playable'}

Set of all valid Flashpoint statuses.

Since 1.3

MONTHS

fpclib.MONTHS = {'APR': '04', 'APRIL': '04', 'AUG': '08', 'AUGUST': '08', 'Apr': '04', 'Aug': '08', 'DEC': '12', 'DECEMBER': '12', 'Dec': '12', 'FEB': '02', 'FEBRUARY': '02', 'Feb': '02', 'JAN': '01', 'JANUARY': '01', 'JUL': '07', 'JULY': '07', 'JUN': '06', 'JUNE': '06', 'Jan': '01', 'Jul': '07', 'Jun': '06', 'MAR': '03', 'MARCH': '03', 'MAY': '05', 'Mar': '03', 'May': '05', 'NOV': '11', 'NOVEMBER': '11', 'Nov': '11', 'OCT': '10', 'OCTOBER': '10', 'Oct': '10', 'SEP': '09', 'SEPTEMBER': '09', 'Sep': '09'}

A dictionary mapping uppercase month names to 2 number month codes.

DP_US

fpclib.DP_US = <fpclib.DateParser object>

A DateParser that parses dates in the american format of “March 5th, 2016”, “3/5/2016”, “March 2016” or similar.

DP_UK

fpclib.DP_UK = <fpclib.DateParser object>

A DateParser that parses dates in the european format of “5th of March, 2016”, “5/3/2016”, “March 2016” or similar.

DP_ISO

fpclib.DP_ISO = <fpclib.DateParser object>

A DateParser that parses dates in the format of “2016 March 5th” or similar.

Other

DEBUG_LEVEL

fpclib.DEBUG_LEVEL = 1

A global value that determines what debug information gets printed. This applies to the whole module, and you can modify it when you want to. Possible values:

  • 0: Don’t print any debug information.

  • 1: Default; prints only basic information along with errors and warnings for curations. Does not care about TABULATION.

  • 2+: Print extra information about function and method calls. The extra information that will be printed is determined by the level of TABULATION when the information is printed; i.e., mode 2 will print only the first level of tabulation, mode 3 will print up to the second level of tabulation, etc.

  • -1: Print all debug information.

Seealso

debug()

Since 1.3

TABULATION

fpclib.TABULATION = 0

Determines the current level of tabulation for the debug() command. Each integer level adds 2 spaces. Several functions will use this to print nested debugging information.

Since 1.3

PLATFORMS

fpclib.PLATFORMS

A set of all valid platforms for Flashpoint to be generated with update() through get_fpdata('Platforms', True)(). This list is empty until update() is called.

Since 1.3

TAGS

fpclib.TAGS

A set of all valid tags for Flashpoint to be generated with update() through get_fpdata('Tags', True)(). This list is empty until update() is called.

Since 1.3

Exceptions

InvalidCharacterError

class fpclib.InvalidCharacterError

An error caused when attempting to read from or write to file name that has invalid characters in it.

InvalidFileError

class fpclib.InvalidFileError

An error caused when attempting to read or write to a file that isn’t a file (e.g., a directory).

EmptyLocationError

class fpclib.EmptyLocationError

An error caused when attempting to read or write to a file or create a folder with no name.

InvalidMetadataError

class fpclib.InvalidMetadataError

An error caused when a curation has invalid metadata.

Since 1.3

Functions

Internet

download()

fpclib.download(url, loc='', name=None, **kwargs)

Downloads the webpage or file at url to the location loc.

Parameters
  • url (str) – A url pointing to a file to be downloaded.

  • loc (str) – A folder to download to; leave blank for the current working directory. If the folder doesn’t exist, it will be created automatically.

  • name (str) – If specified, the file will be saved with this name instead of an automatically generated one.

  • kwargs (**) – Added in 1.2: A collection of arguments to request with. Same format as requests.get(), but without the url parameter.

download_all()

fpclib.download_all(urls, loc='', preserve=False, keep_vars=False, ignore_errs=False)

Downloads a list of files with their website folder structure to the location loc.

For those that are familiar with cURLsDownloader, this function acts in a similar way. Invalid characters for a file/folder name will be replaced with “_”, but “://” will be replaced with “.”.

Parameters
  • urls ([str|(str,dict),...]) – A list of urls pointing to files to be downloaded. Since 1.2, if a url is a tuple instead of a string, the first item in the tuple will be read as the url and the second will be read a dictionary of arguments to request with. The dictionary of arguments is in a similar format to the arguments requests.get() uses, but without the url parameter.

  • loc (str) – A folder to download to; leave blank for the current working directory. If the folder doesn’t exist, it will be created automatically.

  • preserve (bool) – If True, any files from “web.archive.org” will stay in the “web.archive.org” folder. By default, files are moved to their original domains with any port numbers removed.

  • keep_vars (bool) – If True, files will be saved with all urlvars intact in their file name. This prevents files such as “http://www.example.com/game.php?id=123” and “http://www.example.com/game.php?id=321” from overwriting each other. Question marks are replaced with “_”.

  • ignore_errs (bool) – If True, any errors will be ignored and returned as part of a tuple including the urls that failed alongside each error.

Returns

None or a list of tuples including failed urls and errors.

download_image()

fpclib.download_image(url, loc='', name=None, **kwargs)

Downloads the image from url to the location loc as a PNG file.

Parameters
  • url (str) – A url pointing to the image to be downloaded.

  • loc (str) – A folder to download to; leave blank for the current working directory. If the folder doesn’t exist, it will be created automatically.

  • name (str) – If specified, the file will be saved with this name instead of an automatically generated one.

  • kwargs (**) – Added in 1.2: A collection of arguments to request with. Same format as requests.get(), but without the url parameter.

normalize()

fpclib.normalize(url, preserve=True, keep_vars=False, keep_prot=False)

Formats url to a normalized format.

This involves making it use the http protocol, fixing escaped slashes (\/), removing url vars, and stripping it. Accepts strings starting with any protocol, no protocol, “//”, or “/”.

Parameters
  • url (str) – A string url to format.

  • preserve (bool) – If False and the url is from “web.archive.org”, the url will be formatted to it’s original domain without the “web.archive.org” prefix.

  • keep_vars (bool) – If True, url vars at the end of the string will stay on the string.

  • keep_prot (bool) – If True, the url protocol will not be made to use the http protocol unless there is no protocol given or the protocol is formatted incorrectly.

Returns

url in a normalized format, or None if url is None.

read_url()

fpclib.read_url(url, ignore_errs=True, content=False, **kwargs)

Reads the webpage or file at url and returns its contents as a text string.

Parameters
  • url (str) – A string url of a webpage or file.

  • ignore_errs (bool) – Added in 1.3: If False, instead of returning None on any errors, those errors will be raised.

  • content (bool) – Added in 1.3 If True, this function will return the contents of the webpage or file as a byte string instead of reading it as text (response.content instead of response.text).

  • kwargs (**) – Added in 1.2: A collection of arguments to request with. Same format as requests.get(), but without the url parameter.

Returns

The contents of the webpage at url as a string or None if the url is blank.

get_soup()

fpclib.get_soup(url, parser='html.parser', ignore_errs=True, **kwargs)

Reads the webpage at url and creates a BeautifulSoup object with it.

Parameters
  • url (str) – A string url of a webpage.

  • parser (str) – The BeautifulSoup parser to use.

  • ignore_errs (bool) – Added in 1.3: If False, instead of returning None on any errors, those errors will be raised.

  • kwargs (**) – Added in 1.2: A collection of arguments to request with. Same format as requests.get(), but without the url parameter.

Returns

A BeautifulSoup object created from url or None if the url is blank or there was an error and ignore_errs is True.

get_fpdata()

fpclib.get_fpdata(page, ignore_errs=True)

Reads the Flashpoint online datahub at //bluemaxima.org/flashpoint/datahub/{page} and returns a list of possible values; you can use this to get the most up-to-date tags, platforms, games, or animations.

Parameters
  • page (str) – Can be “Platforms”, “Tags”, “Game_Master_List”, “Animation_Master_List”, or any other page on the datahub with tables in it.

  • ignore_errs (bool) – If False, instead of returning None on any errors, those errors will be raised.

Returns

A list of all Platforms, Tags, Games, Animations, etc. depending on each page.

Since 1.3

File IO

read()

fpclib.read(file_name)

Reads the contents of the file file_name into a string.

The returned string is in utf-8.

Parameters

file_name (str) – The location/name of a file in the local file system.

Returns

The contents of the file file_name as a string.

Raises

read_lines()

fpclib.read_lines(file_name, ignore_lines=True)

Reads the lines of the file file_name into a list of strings split by any new line character (\r\n, \r, or \n).

The returned strings are in utf-8.

Parameters
  • file_name (str) – The location/name of a file in the local file system.

  • ignore_lines (bool) – By default this function disregards empty lines at the end of the file. Set this to False to disable that.

Returns

A list of strings containing all of the lines in the file file_name.

Raises

read_table()

fpclib.read_table(file_name, delimiter=',', ignore_lines=True)

Reads the contents of the file file_name into a two dimensional list of strings with rows split by any new line character (\r\n, \r, or \n) and columns split by delimiter.

The returned strings are in utf-8.

Note

This function disregards empty lines at the end of the file.

Parameters
  • file_name (str) – The location/name of a file in the local file system.

  • delimiter (str) – A string to split columns in the table by.

  • ignore_lines (bool) – By default this function disregards empty lines at the end of the file. Set this to False to disable that.

Returns

A two-dimensional list of strings of the content in the file file_name.

Raises

make_dir()

fpclib.make_dir(folder, change=False, overwrite=False)

Makes a folder at folder, along will all parent folders.

It will not raise a FileExistsError if the folder already exists, but will instead return False.

Parameters
  • folder (str) – A string location to create a folder.

  • change (bool) – If True, this function will set the new folder as the working directory.

  • overwrite (bool) – If True, if there is a non-folder file in the same location as the folder being created, the folder will overwrite this file.

Raises
  • EmptyLocationError – If folder is an empty string.

  • InvalidCharacterError – If folder contains invalid characters.

  • FileExistsError – If a non-folder file exists in the location given by folder and overwrite is not set.

Returns

True on successful folder creation, False on failure.

Note

Even if folder creation fails, if change is True, the working directory will still be changed to that folder.

delete()

fpclib.delete(file_name)

Deletes the file or folder file_name recursively.

It will not raise a FileNotFoundError if the file or folder doesn’t exist, but will instead return False.

Parameters

file_name (str) – A string location of a file or folder to delete.

Returns

True on successful deletion, False on failure.

Raises

write()

fpclib.write(file_name, contents='', force=False)

Writes contents to the file file_name in utf-8.

If the parent directory of this file doesn’t exist, it will be automatically created.

Parameters
  • file_name (str) – The location/name of a file in the local file system.

  • contents (str|[str,...]) – Contents to write to the file file_name. If this is an Iterable (and not a string), each item in this will be written to the file file_name as a separate line split by line feed (\n) characters.

  • force (bool) – If True, if there is a non-writable file (like a directory) in the same location as the file being written to, the function will overwrite this file.

Raises

write_line()

fpclib.write_line(file_name, line='', force=False)

Append line to the file file_name.

If the parent directory of this file doesn’t exist, it will be automatically created.

A line feed (\n) character is written after line.

Parameters
  • file_name (str) – The location/name of a file in the local file system.

  • line (str) – A line to write to the file file_name.

  • force (bool) – If True, if there is a non-writable file (like a directory) in the same location as the file being written to, the function will overwrite this file.

Raises

write_table()

fpclib.write_table(file_name, table, delimiter=',', force=False)

Writes the two-dimensional list table to the file file_name.

If the parent directory of this file doesn’t exist, it will be automatically created.

Rows are joined by a line feed (\n) character, and columns are joined by delimiter.

Parameters
  • file_name (str) – The location/name of a file in the local file system.

  • table ([[str,...],...]) – A two-dimensional list of strings to format and write to the file file_name.

  • delimiter (str) – A string to join columns in the table by.

  • force (bool) – If True, if there is a non-writable file (like a directory) in the same location as the file being written to, the function will overwrite this file.

Raises

scan_dir()

fpclib.scan_dir(folder=None, regex=None, recursive=True)

Scans the directory folder recursively and returns all files and sub-folders as two lists.

Parameters
  • folder (str) – A directory to scan. Defaults to the current working directory.

  • regex (str|re) – If given, this function will only return files whose full paths match this regex. This has no effect on sub-folders.

  • recursive (bool) – If False, this function will not scan sub-folders recursively. You might be better off using os.walk() if you set this to False.

Returns

files and subfolders as two lists in that order. return files, subfolders

Raises
  • InvalidCharacterError – If folder contains invalid characters.

  • FileExistsError – If folder is not a folder.

  • FileNotFoundError – If folder does not exist.

Note

Any slashes (/) in file paths will be replaced with backslashes (:code:``) in the output, and this is what regexes match with.

Since 1.4

replace()

fpclib.replace(files, old, new, regex=None, ignore_errs=True)

Replaces all instances of old with new in files.

Parameters
  • files ([str,...]|str) – A string or list of strings pointing to files to have their contents changed.

  • old (str|re) – A regex or string to replace. If this is a string, it will not be treated as a regex. Use re.compile() to pass in a regex object.

  • new (str) – A string of text to replace with.

  • regex (str|re) – If given, this function will only replace in files whose full paths match this regex. It must be a real regex (i.e., you can’t use “*” in place of “.*”)!

  • ignore_errs (bool) – If False, this function will throw an error at the end if files had invalid files.

Raises

A bulk ValueError if files has any invalid files and ignore_errs is False. Errors will be thrown at the end of the function after everything that could be replaced was replaced.

Since 1.4

hash256()

fpclib.hash256(obj)

Serializes obj and then returns a sha256 HASH object of it.

Two objects that yield the same bytes representation will yield the same hash.

Parameters

obj – An object to hash.

Returns

A sha256 HASH object of obj.

Seealso

Python’s hashlib library. The object returned is the same object created by hashlib.sha256().

hash()

fpclib.hash(obj)

Serializes obj and then gets a four-byte integer representation of those bytes with the first four bytes of it’s sha256.

This function is meant to replace the default python hash() function because it does not rely on the object’s id.

Parameters

obj – An object to hash.

Returns

A four-byte integer representation of obj.

Seealso

hash256()

Curating

test()

fpclib.test()

Tests the library to make sure it works.

This test will curate “Interactive Buddy” and download the swf file linked in the launch command into the proper place in a folder in the working directory, while also testing basic validation.

Raises

AssertionError – If the test gives back any errors.

update()

fpclib.update()

Initializes or updates variables that are generated from online. The only ones are PLATFORMS and TAGS.

This method is only automatically called by Curation.validate() if rigid is True and either PLATFORMS or TAGS are not set. You must call this function manually if you want to access PLATFORMS or TAGS before then.

Since 1.3

debug()

fpclib.debug(text, mode, *items, pre='[INFO] ')

Prints text depending on mode and DEBUG_LEVEL.

Parameters
  • text (str) – A string of text to print.

  • mode (int) – text will only be printed in two cases: if this is 1 and DEBUG_LEVEL > 0 - or if this is 2, DEBUG_LEVEL is 2 or higher, and DEBUG_LEVEL - 1 > TABULATION.

  • items (*) – Any number of items to format text with. Uses str.format().

  • pre (str) – This is a prefix of text to print to the left of text. This must be a key argument.

Since 1.3

clear_save()

fpclib.clear_save(loc='')

Deletes the “c-info.tmp” file generated by curate() and curate_regex() in the current working directory or loc.

Parameters

loc (str) – Added in 1.3: An optional location to clear the save file in. If not set, the directory will be the current working directory.

It will not raise a FileNotFoundError if it doesn’t exist. Returns True on success, and False on failure.

curate()

fpclib.curate(items, curation_class, use_title=False, save=False, ignore_errs=False, overwrite=False, validate=1)

Curates form a list of urls given by items with a sub-class of Curation specified by curation_class.

Parameters
  • [str|(str,dict),...] (items) – normally a list of string urls of webpages to curate from, but if you put a tuple with 2 items in the place of any string, the first item in the tuple will be treated as the url, and the second item will be treated as a dictionary of arguments passed to an instance of curation_class along with the url. You can mix tuples and strings.

  • curation_class (class) – A sub-class of Curation to create curations from. Note that this must be the class and not an object created from the class.

  • use_title (bool) – If True, each curation folder will be generated with the title of the curation instead of its id.

  • save (bool) – If True, progress will be constantly saved to “c-info.tmp” so that if the function errors and is ever called with the same items variable in the same working directory again, it will resume where it left off. Note that calling this function again with a different list of items will restart the process and the save file from any other processes.

  • ignore_errs (bool) – If True, any error that a curation raises will be ignored and the curation will be skipped. Any failed items will be returned as a list of 3-length tuples at the end of the function with the item, the error, and a dictionary of additional arguments that were passed in.

  • overwrite (bool) – If True, this method will mix and overwrite files in existing curation folders instead of making the folder “Curation (2)”, “Curation (3)”, etc.

  • validate (int) – Added in 1.3: Mode to validate each curation to make sure it has proper metadata. 0 means do not validate, 1 (default) means flexibly validate, and 2 means rigidly validate. See Curation.get_errors(). Invalid curations will not raise any errors and will be skipped; however, if ignore_errs is True, the curation will be returned with an InvalidMetadataError in the list at the end of the function.

Returns

None or a list of tuples including failed urls, errors, and data passed in. The format for this is [(str,Exception,dict),…]

Raises
  • ValueError – If items is empty.

  • TypeErrorAdded in 1.3: If curation_class is not a subclass of Curation.

curate_regex()

fpclib.curate_regex(items, links, use_title=False, save=False, ignore_errs=False, overwrite=False, validate=1)

Curates from a list of urls given by items with a list of links.

See

curate()

Parameters
  • items ([str|(str,dict),...]) – A list of urls of webpages with games/animations to curate.

  • links ([(str|re,class),...]) – A list of tuples containing a regex and a sub-class of Curation. The function will search the url of each item for each of the regexes using re.search(), and the first match will decide which sub-class gets used. If there are no matches, the curation would be skipped. A good example of the links variable is something like [('newgrounds\.com', NewgroundsCuration), ('kongregate\.com', KongregateCuration)]. Regexes can be strings or a re object.

  • use_title (bool) – Specifies whether or not to use the title or id of a curation for its folder.

  • save (bool) – Specifies whether or not to save progress and continue where left off if the function is called with the same arguments.

  • ignore_errs (bool) – Specifies whether or not to ignore errors and return them at the end of the function.

  • overwrite (bool) – Whether or not to mix new curations with older folders with the same name.

  • validate (int) – Added in 1.3: Mode to validate each curation to make sure it has proper metadata.

Returns

None or a list of tuples including failed urls, errors, and data passed in. The format for this is [(str,Exception,dict),…]

Raises

ValueError – If items or links is empty.

load()

fpclib.load(curation)

Loads the curation in the folder curation into Curation object using ruamel.yaml.

Parameters

curation (str) – A string pointing to the location of a folder where a curation is stored.

Returns

A Curation object created with the metadata of the curation in the folder curation.

Note

The curation at curation curation must be using the yaml curation format.

Raises
  • InvalidCharacterError – If curation has invalid characters.

  • FileNotFoundError – If the folder given is not a valid curation.