kallithea Files · docs/usage/debugging.rst

Files @ 11cae16e5a5d

Branch filter:

Location: kallithea/docs/usage/debugging.rst

11cae16e5a5d 1.2 KiB text/prs.fallenstein.rst Show Annotation Show as Raw Download as Raw

mads

setup: use old importlib_metadata version to fix kombu failing on python < 3.8

Many libraries use the importlib_metadata library as fallback when running on
Python versions older than 3.8 . For example setuptools when easy_install is
used for install the Kallithea console_scripts entrypoints in the bin folder.
The dependencies on importlib_metadata were indirect and without constrains on
version number.

The problem is that Celery uses Kombu, which (on Python < 3.8) uses
importlib_metadata in a way that is incompatible with importlib_metadata > 5.

Most obvious, building docs failed as:
Running Sphinx v5.1.1

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
File ".../kallithea/venv/lib64/python3.7/site-packages/sphinx/config.py", line 347, in eval_config_file
exec(code, namespace)
File ".../kallithea/docs/conf.py", line 17, in <module>
import kallithea
File ".../kallithea/kallithea/__init__.py", line 45, in <module>
CELERY_APP = celery.Celery() # needed at import time but is lazy and can be configured later
File ".../kallithea/venv/lib64/python3.7/site-packages/celery/local.py", line 492, in __getattr__
[name])
File ".../kallithea/venv/lib64/python3.7/site-packages/celery/app/__init__.py", line 2, in <module>
from celery import _state
File ".../kallithea/venv/lib64/python3.7/site-packages/celery/_state.py", line 15, in <module>
from celery.utils.threads import LocalStack
File ".../kallithea/venv/lib64/python3.7/site-packages/celery/utils/__init__.py", line 16, in <module>
from .nodenames import nodename, nodesplit, worker_direct
File ".../kallithea/venv/lib64/python3.7/site-packages/celery/utils/nodenames.py", line 6, in <module>
from kombu.entity import Exchange, Queue
File ".../kallithea/venv/lib64/python3.7/site-packages/kombu/entity.py", line 7, in <module>
from .serialization import prepare_accept_content
File ".../kallithea/venv/lib64/python3.7/site-packages/kombu/serialization.py", line 440, in <module>
for ep, args in entrypoints('kombu.serializers'): # pragma: no cover
File ".../kallithea/venv/lib64/python3.7/site-packages/kombu/utils/compat.py", line 82, in entrypoints
for ep in importlib_metadata.entry_points().get(namespace, [])
AttributeError: 'EntryPoints' object has no attribute 'get'

That made readthedocs builds fail, when it in the default web configuration
used Python 3.7 .

Fixed by introducing an explicit dependency on importlib_metadata < 5.

.. _debugging:

===================
Debugging Kallithea
===================

If you encounter problems with Kallithea, here are some instructions
on how to debug them.

.. note:: First make sure you're using the latest version available.


Enable detailed debug
---------------------

Kallithea uses the standard Python ``logging`` module to log its output.
By default only loggers with ``INFO`` level are displayed. To enable full output
change ``level = DEBUG`` for all logging handlers in the currently used .ini file.
This change will allow you to see much more detailed output in the log file or
console. This generally helps a lot to track issues.


Enable interactive debug mode
-----------------------------

To enable interactive debug mode simply comment out ``set debug = false`` in
the .ini file. This will trigger an interactive debugger each time
there is an error in the browser, or send a http link if an error occurred in the backend. This
is a great tool for fast debugging as you get a handy Python console right
in the web view.

.. warning:: NEVER ENABLE THIS ON PRODUCTION! The interactive console
             can be a serious security threat to your system.