Sphinx throws KeyError exception

Question

I have a python flask script inside a docker. This script get some environment variable from the docker-compose in this way:

app = Flask(__name__)
DEFAULT_PSW = os.environ['DEFAULT_PSW']

@app.route("/")
def manager():
    ...

I wanted to document it using Sphinx. I was able to configure it but when I run "make html" I get this exception:

WARNING: autodoc: failed to import module 'main'; the following exception was raised:
Traceback (most recent call last):
  File "/home/lorenzo/.local/lib/python3.7/site-packages/sphinx/ext/autodoc/importer.py", line 32, in import_module
    return importlib.import_module(modname)
  File "/usr/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/lorenzo/Desktop/Dev/project/script/manager_flask/manager/manager/main.py", line 20, in <module>
    DEFAULT_PSW = os.environ['DEFAULT_PSW']
  File "/usr/lib/python3.7/os.py", line 679, in __getitem__
    raise KeyError(key) from None
KeyError: 'DEFAULT_PSW'

If I've understood well how sphinx works the problem is that sphinx will try to "compile" my script and, of course, during this process it won't find the environment variable. What can I do?

EDIT: Steps that I did to get this error:

Create folder called docs
Inside the docs folder started sphinx-quickstart leaving everything by default except for Author and Project name.
Edited the conf.py (this file can be found in the repository in the comment)
Generate the rst file with sphinx-apidoc
Create folder modules and added the file scp_handler.rst and main.rst
Updated the index.rst adding the path to the new generated file
Ran "make html".

I don't use flask, but in general using Sphinx on a script you should prevent __main__ from executing. Sphinx imports your declarations and docstring, therefore your modules are executed once on import. In these cases you can declare some default values to replace those system values that aren't available. This thread shows the general approach to the somewhat similar problem of documenting argparse. — bad_coder
this looks like an error in your code? your app apparently needs the DEFAULT_PSW variable set and it is trying to tell you that it is not — gold_cy
"This script is designed to run in docker so will take as enviroment variable the defualt password used for all the ssh conenction." (sic the typos). Retry after setting an environment variable DEFAULT_PSW to (I guess?) any value at all, for your OS. (You can look up elsewhere how to do that.) — Jongware
And I did it, in the docker-compose the variable is defined indeed if I start the docker-compose the application will run as supposed. My problem is when I run the sphinx command "make html". When I do that I get the exception, I think that the "make html" try to compile the script in order to get the docstring and this is why I get the error. I'm searching a way to prevent that or, a way to run the "make html" specifying the parameters. Another solution could be deleting that line, create the documentation and than rewrite the line but it doesn't look like an elegant solution :-) — Lorenzo Cavada
Do you care about the password in this context? You probably could just use DEFAULT_PSW = os.environ.get('DEFAULT_PSW', '') which will not throw a key error if the environment variable is not set but instead use a fallback. — Michael H.

grs grs · Accepted Answer · 2021-04-17T19:03:59

For documentation purposes set and export the key in the conf.py file:

os.environ("DEFAULT_PSW", "default_psw")

Sphinx throws KeyError exception

1 Answers