Announcing... the IFDB Tag Manipulator!

General IF Community Resources
1

To help with TagFest, I’m releasing a beta version of the IFDB Tag Manipulator®* - a small Python script I wrote that interfaces with the IFDB APIs to allow you to quickly assign tags to large classes of games. The most likely use case is adding implied tags to all games that feature a given tag. For instance, I used it to add “nonhuman protagonist” and “animal protagonist” to games featuring “bird protagonist”.

The program has a simple command line interface. Furthermore, users with some knowledge of Python may be able to sort through my messy code and build new procedures of their own.

Warning!

Do not operate machinery, including the IFDB Tag Manipulator®*, while intoxicated or under the influence of any substances. Read the “How to Operate” instructions below before using the IFDB Tag Manipulator®*. FLACRabbit is not liable in whole or in part for damages caused or accrued as a direct or indirect result of the use of the IFDB Tag Manipulator®*.

(More seriously, the use of heavy automation comes with a certain level of responsibility and awareness. If you use the Manipulator through your main IFDB account and something goes horribly wrong, you may be left with only bad options. For example, the admins might have to delete your account and with it all previous tags you had assigned. If you don’t want to take the risk, you can suggest tag implications to me via PMs or on this thread and I’ll handle it.)

Instructions

Setup

You’ll need a working Python 3 installation, urllib (which should already be included), and an IFDB account.

Download the included tm.zip file and extract it into a directory. Open tm.py in a text editor or code editor and enter your user details in the first two lines, inside the quotes. Note: Your “username” is your email address, not your screen name.

You’ll have to run tm.py from the command line, supplying arguments in a typical fashion. If you’re not familiar with command line conventions, you may wish to look it up online.


How to Operate

The Manipulator first selects a number of games, which you supply via the -sg (select game) and -st (select tag) arguments, followed by a tag or game name. Multiple games and/or tags can be selected at once. It then applies one or more actions to each selected game. For instance, the -at action (add tag) adds the specified tag to each selected game, and the -rt action removes it (only if you’ve previously assigned it). As an example, the command

python3 tm.py -st "Le Grand Guignol" -st "La Petite Mort" -at "Ectocomp game"

selects all games tagged with either Ectocomp category and adds the Ectocomp game tag to them all. This change could be undone via the command

python3 tm.py -st "Le Grand Guignol" -st "La Petite Mort" -rt "Ectocomp game"

It’s worth mentioning that this will erase the Ectocomp game tag regardless of whether you had manually applied it or whether the Manipulator did. The program can’t distinguish between manually and automatically assigned tags.

You can specify -u - or unsafe mode - to get rid of the confirmation prompt for each game.

If you don’t specify any actions the Manipulator will print a table of selected games.

It may be advisable to create a new folder to hold the Python files, as tm.py creates large numbers of tag backup files in its working directory. These can be safely deleted if you like, as the program in its current state can’t process them.


Download link:
(This version is no longer up to date. See the latest download link further down in this thread.)

What will you do with this tool? Tell everyone about the sweeping changes you’ve effected right here on this thread! Questions about how to set it up or use it are also welcome. If you find any bugs or errors, please alert me via PM and I’ll update it as soon as possible.

*The use of the terms ‘IFDB’ and ‘Tag’ is not sanctioned or endorsed by IFDB or the Interactive Fiction Technology Foundation. FLACRabbit is not affiliated or associated with IFDB or the Interactive Fiction Technology Foundation.

8 Likes
2

I just used it to add the “LGBTQ+” tag to games tagged with various more-specific related tags (like “transgender” or “bisexuality”).

4 Likes
3

I’m releasing version 0.2, a major update. I HIGHLY recommend that you switch to the new version as it fixes a number of serious bugs. Check the README.txt for a description of the new functionality.

Note: Setup works differently now; the username and password are stored in a separate file. However, this will hopefully be the last time that users will have to re-enter account details. (That’s the whole point of making this change.)

tm_0.2.zip (7.5 KB)

Changelog:

v0.2 (Oct 21 2024)
  • Fixed a critical bug where tags were treated as case sensitive, causing tags to be doubled and making it impossible to remove tags using the Manipulator in some cases.
  • Fixed a bug where games could be processed twice if included in separate selection arguments.
  • The program now loads username and password data from a separate config.txt file, making it more resilient to future updates.
  • The printed list of games is now sorted in alphabetical order.
  • Added a larger variety of selection criteria.
  • Added support for filter arguments.
  • Added a check for missing username and/or password.
3 Likes
4

This script works, and maybe it’s a good thing, but it creeps me out, because if someone does use it in a way they regret, it could be hard for us to clean up.

As of a couple weeks ago, IFDB moderators now have a tool that can do what this tool does. The new tools are:

  • Bulk Add: Add tag X to all games that have tag Y
  • Bulk Delete: Delete all instances of a tag
  • Block Tag: Prevent users from using a tag X, instead recommending a different tag Y (e.g. “sci-fi” versus “science fiction”)

When we want to consolidate tags, we normally use all three of these tools, first adding “science fiction” to all games tagged “sci-fi,” then deleting all instances of “sci-fi”, and finally blocking “sci-fi” in favor of “science fiction.”

My intuition is that if you feel like you want to use this Tag Manipulator, then maybe you want to use it to consolidate tags, and so you might want to post about it on the Tagfest 2024: Suggested tag consolidations thread.

Someday, I hope to allow anyone to delete tags, but, in order to make that possible, I think we’ll need to track tags in game history. (That’s going to be very tricky work, and I’ll probably need to do it myself, someday.)

3 Likes
5

The Manipulator is now capable of reversing large numbers of tag assignments with no more work than it took to add them; an individual user can correct mistakes within seconds.

Anyway, you were the one who first suggested the idea:

This tool is not intended or able to replace the administrators’ duties - it’s simply designed as a time saver to spare ordinary users hours of manual, error-prone work. And as an extra benefit, it reduces the workload on the IFDB moderators too.

1 Like
6

I think the main use case for this is not as a stand-in for tag consolidations, but rather adding certain “umbrella” tags to any game tagged with a more specific tag that could be considered a subset of it—both FLACRabbit’s initial example and mine are of that nature. We don’t actually want to consolidate “bird protagonist” and “animal protagonist” or “LGBTQ+” and “bisexual”, we just want to make sure works with specific tags also get included in the general tags that apply to them.

But if you would prefer for people to ask mathbrush to mass-add tags like that, then I’ll do that instead. I don’t want to break anything.

1 Like
7

I missed that! That puts my mind at ease.

I’ll still want to work on adding tags to history (which will allow me to allow anyone to delete any tag), but I think we can work with this.

3 Likes
8

@FLACRabbit as this is an “official” thing that you’re sharing with other users, it might be helpful to include a user agent header with all requests made to IFDB that identifies the name of the tool and its version.

Python tip: You can replace generate_url and URLArgument with the built-in urllib.parse.urlencode.

BTW, I’m working on replacing/adding JSON support, so hopefully you won’t be needing that XML library.

9

Thanks for the tips - adding a User-Agent header is a good idea.

Do you mean that you’re adding JSON support to the Tag Manipulator or to the IFDB server?

10

Just curious. If “Horror” was added to a bunch of games and “Horror” previously existed on others, does it track which IDs it affected and only reverses those? It functions like a real undo with a proper history log?

11

In the IFDB tag system, users cannot affect tags that they didn’t previously add themselves. So, it’s incapable of removing the horror tag if a different user previously added it.

Well… not exactly. The program cannot distinguish between tags you added manually and tags that it added automatically using your account. But this capability may be added in a future update, since it’s already generating an XML history log. In the meantime, you can achieve the same effect by selecting only the games to which you added the tag in the first place.

There’s an example of undoing an assignment in “How to Operate” in the topic post if you are looking for more details.

1 Like
12

I converted most of the IFDB API to use JSON.

The documented APIs still support XML, so there’s backwards compatibility.