Babel's message_extractors configuration in setup.py: Third parameter in tuple

Question

I want to start using Babel with my Python project. I have a setup.py that has something along the following as per documentation:

setup(
    ...
    message_extractors = {'my_project': [('**.py', 'lingua_python', None),
    ]},
    ...

And everything works fine. Now I was wondering what the third parameter (set to None) means and what I could pass in (just for the sake of knowing it). I looked at the Babel documentation but couldn't find anything, but I saw this on the Mako documentation for Babel:

# Extraction from Python source files

[python: myproj/**.py]

# Extraction from Mako templates

[mako: myproj/templates/**.html]
input_encoding = utf-8

And I was wondering: This input_encoding option seems like something you could pass there. Since I use Unicode and UTF-8 in all of Python, my templates, etc. I figured may this is a valid option to be specified (maybe it's an implicity assumption, I don't know).

So now I am searching for something that documents this behaviour but even the part of the Babel docs I found wasn't saying anything about what the third parameter is.

Please enlighten me by sharing some helpful links that explain this in detail. Thank you in advance.

Update: I have found out that the last argument seems to be a dict of options, possibly passed to the extension (e.g. mako). When I set the last parameter from None to {'input_encoding': 'utf-8'} the mako.exceptions.CompileException complaining about Unicode decode operation of encoding 'ascii' failed vanished. So while this seems to be the answer, I am still looking for a documentation about this.

Answer 1

The third parameter is an options mapping.

This can contain arbitrary keyword parameters that will be passed to the extractor method. It depends entirely on the extractor method what keyword parameters it'll accept.

The extractor is passed these options as the last parameter when called, usually called options in the method signature. The Mako Babel plugin supports encoding and input_encoding for example. The former seems to be a legacy spelling of the latter parameter, it's only used if input_encoding is not specified.

As such, each and every Babel plugin needs to document the supported options separately, the Babel project does not set limitations nor will it know the specifics that each plugin supports.

The specifics for the Mako extractor are documented in the Common Framework Integrations section:

The Mako extractor supports an optional input_encoding parameter specifying the encoding of the templates (identical to Template/TemplateLookup‘s input_encoding parameter).