WindPower: Created page with "{{User:WindBOT/Header}} I am a fully automated bot, but that doesn't mean that I am not flexible. You can tweak me from the wiki itself by editing [[User:WindBOT/Filters|my filt..."

2011-04-26T21:34:24Z

Created page with "{{User:WindBOT/Header}} I am a fully automated bot, but that doesn't mean that I am not flexible. You can tweak me from the wiki itself by editing [[User:WindBOT/Filters|my filt..."

New page

{{User:WindBOT/Header}}

I am a fully automated bot, but that doesn't mean that I am not flexible. You can tweak me from the wiki itself by editing [[User:WindBOT/Filters|my filters]]!

== Technical details ==
I am written in [http://python.org/ Python] (2.6). If you want to modify my code, make sure you know enough Python stuff before continuing.

All code must be placed on [[User:WindBOT/Filters]], and indented by two spaces (for the top-level block). Whitespace determines Python's code blocks. Although this is not a necessity, try to use 4 spaces per indentation level.

== Filters ==
=== How to disable a filter ===
'''Wait!''' Before you disable a filter, consider why you want to disable it. Did it produce an expected result but on a page where such a result is not appropriate? In this case, [[User:WindBOT/Blacklist|blacklist this page]] instead of disabling the filter.
If I am malfunctioning, chances are that the problem lies in one of [[User:WindBOT/Filters|my filters]]. Thus, instead of completely shutting me down, it would be wiser to disable only the chunk of code that is misbehaving.
To make me ignore a certain line, add a "#" in front of it:
# This line will be ignored
If there are multiple lines, wrap them inside triple-quotes:
"""This line will be ignored
and this one as well
and this one is cake
and the previous one was a lie but it was still ignored"""
If all else fails, you can simply delete the block of code from the page. I can't come up with code by myself yet, so I won't do anything.
If the problem really is elsewhere, [{{fullurl:Special:Block|wpBlockAddress={{BASEPAGENAMEE}}&wpBlockExpiry=infinite&wpAnonOnly=0&wpEnableAutoblock=0&wpCreateAccount=0&wpBlockReason=Bot%20gone%20crazy:%20}} block the bot].

=== Filter types ===
I work using filters. They are simply [http://www.penzilla.net/tutorials/python/functions/ Python functions] which take a certain input as argument, and is expected to return a modified version of this input (if the filter changed something) or an identical version (if the filter didn't change anything). There are multiple types of filters:
* '''Regular filters''': These are no-frills, direct filters.
** ''When to use'': When no other filter type is adequate. This type of filter can be very destructive if the function is not careful enough.
** ''Input''/''Output'': Raw Wikitext of a page
** ''Implementation details'': Your filter is called only once, over the whole content of the page.
** ''How to use'': To register a regular filter, call the <code>addFilter</code> function: <code>addFilter(myFilter)</code>
* '''Safe filters''': These are Wikitext safe filters.
** ''When to use'': Semantics-related filters are a good fit for these. Use them to filter human-readable text.
** ''Input''/''Output'': Sanitized Wikitext of a page (readable text content), external and internal wikilinks '''labels''' (labels only), internal wikilinks URLs only when combined with its label (<nowiki>[[like this]]</nowiki>).
** ''Implementation details'': Your filter is called once over the textual body of the page, then once per link label.
** ''How to use'': To register a safe filter, call the <code>addSafeFilter</code> function: <code>addSafeFilter(myFilter)</code>
* '''Link filters''': These filters act on links within wiki pages.
** ''When to use'': When you want to apply filters on links. Note: '''Use a safe filter''' if all you want to do is to modify link labels (unless you don't want to modify the page's body as well).
** ''Input''/''Output'': A single link instance. The class definition is given at the bottom of this document.
** ''Implementation details'': Your filter is called once per link in the page.
** ''How to use'': To register a link filter, call the <code>addLinkFilter</code> function: <code>addLinkFilter(myFilter)</code>
* '''Locale filters''': These filters act on localization dictionaries.
** ''When to use'': When you want to extract only certain parts of translation files.
** ''Input''/''Output'': N/A
** ''Implementation details'': The localization dictionary is a huge dictionary with keys being the string IDs (<code>TF_SPY_BACKSTAB_ENGY_SAP_BUILDING_DESC</code>, etc.), and each key being another dictionary. This inner dictionary has language names as keys (<code>english</code>, <code>romanian</code>...) and the actual translated string as value.
** ''How to use'': Call the <code>languagesFilter</code> function: <code>languagesFilter(languages, commonto, prefix, suffix, exceptions)</code> where:
*** ('''Required''') <code>languages</code> is the localization dictionary.
*** ('''Optional''') <code>commonto</code> filters strings by their translation availability. For example, <code>commonto=['english', 'french']</code> will only keep strings which are available in both <code>french</code> and <code>english</code>.
*** ('''Optional''') <code>prefix</code> filters strings by their string ID, which must contain this string as prefix.
*** ('''Optional''') <code>suffix</code> filters strings by their string ID, which must contain this string as suffix.
*** ('''Optional''') <code>exceptions</code> is a list of keys that should be excluded no matter what.

Filters themselves may be filtered (yeah, really) so that they are only applied to certain articles:
* Use <code>addSomeTypeOfFilter(myFilter1, myFilter2, myFilter3, ..., language='de')</code> (where <code>addSomeTypeOfFilter</code> is one of the functions described above) to add <code>myFilter1</code>, <code>myFilter2</code>, <code>myFilter3</code>... as filters that will only be applied on German pages (<code>de</code>).

=== Filter generators ===
As previously mentioned, filters are Python functions. However, a lot of filters are similar in function and in purpose. Therefore, declaring a new Python function for each filter would be redundant and cumbersome.

Since functions are first-class variables in Python, you can pass around, edit, and create functions programatically. This is what filter generators are. They take a few argument about your desired filter's details, and generate a corresponding Python function, which you can then add using the method described above.

Filter generators:
* <code>dumbReplace(text, replacement)</code>: This generates a straightforward text replacement filter, which replaces all instance of <code>text</code> by <code>replacement</code>.
* <code>dumbReplaces(stuffToReplace)</code>: The bulk version of <code>dumbReplace</code>. Generates a text replacement filter with multiple things to replace. <code>stuffToReplace</code> should be a [http://docs.python.org/tutorial/datastructures.html#dictionaries Python dictionary] of the form:
<pre>{
'text1': 'replacement1',
'text2': 'replacement2',
'text3': 'replacement3'
}</pre>
* <code>regex(regularExpression, replacement)</code>: This generates a simple [http://www.regular-expressions.info/ regex] filter. To use backreferences in the replacement argument, use <code>$1</code> for group 1, <code>$2</code> for group 2, etc.
* <code>regexes(regularExpressions)</code>: The bulk version of the <code>regex</code> filter generator. To use backreferences in the replacement argument, use <code>$1</code> for group 1, <code>$2</code> for group 2, etc. <code>regularExpressions</code> should be a [http://docs.python.org/tutorial/datastructures.html#dictionaries Python dictionary] of the form:
<pre>{
'regex1': 'replacement1',
'regex2': 'replacement2',
'regex3': 'replacement3'
}</pre>
* <code>wordFilter(correctWord, alternateWord1, alternateWord2, ...)</code>: This generates a filter guaranteed to be applied only to whole words (if used as safe filter), and with wikitext aliases. The first argument, <code>correctWord</code>, is the "correct" spelling of the word. The rest of the arguments are regular expressions (that only match whole words! You do not need to check for this) which will be replaced with <code>correctWord</code>. Note that you can (and should) repeat <code>correctWord</code> as one of the alternate spellings, in order to enforce <code>correctWord</code>'s capitalization.
* <code>enforceCapitalization(word1, word2, ...)</code>: This is effectively the same as <code>wordFilter(word1, word1); wordFilter(word2, word2); ...</code>. It adds <code>word1</code> itself as a spelling of <code>word1</code>, which replaces all instances of <code>word1</code> by the correctly-capitalized version of it. Note: You '''do not need''' to call <code>addSafeFilter</code> on this one. <code>enforceCapitalization</code> automatically calls <code>addSafeFilter</code> by itself, as it is meant to be used only on textual content.
* <code>associateLocaleWordFilters(languages, fromLang, toLang, targetPageLang)</code>: This generates word filters for all strings in the localization dictionary <code>languages</code>, going from language <code>fromLang</code> to language <code>toLang</code>. This function automatically adds the generated word filters to the safe filters list. If the <code>targetPageLang</code> argument is provided, the word filters will be applied only on pages in that language (for example, <code>targetPageLang='de'</code> will make the filters only be applied on /de pages).

=== Link class definition ===
{{User:WindBOT/LinkClass}}

User:WindBOT/Documentation - Revision history

WindPower: Created page with "{{User:WindBOT/Header}} I am a fully automated bot, but that doesn't mean that I am not flexible. You can tweak me from the wiki itself by editing [[User:WindBOT/Filters|my filt..."