Add system settings path and document offline test runs (#2974)

* Add /etc/maigret/settings.json to the settings search path

* Register the slow marker and document offline test runs

docs/source/development.rst

@@ -65,6 +65,24 @@ Use the following commands to check Maigret:
   # open html report
   open htmlcov/index.html
 
+Running the tests offline
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some tests reach real sites, which is why CI runs pytest with
+``--reruns 3 --reruns-delay 5``. They all carry the ``slow`` marker, so
+deselecting it leaves a suite that passes with no network at all:
+
+.. code-block:: console
+
+  pytest tests -m "not slow"
+
+This is the invocation to use when building a distribution package, since
+distribution builders run without network access. Measured on 0.6.4: the full
+suite fails 9 tests offline, ``-m "not slow"`` passes 403 and deselects 24.
+
+If you add a test that talks to the network, mark it ``slow`` — otherwise you
+silently break offline builds for every downstream packager.
+
   # get flamechart of imports to estimate startup time
   make speed
 
@@ -269,6 +287,8 @@ Here's how the activation process works when a JWT token becomes invalid:
 4. The activation function obtains a new JWT token and updates it in the site check record
 5. On the next site check (either through retry or a new Maigret run), the valid token is used and the check succeeds
 
+Step 5 works across runs because minted tokens are written to a per-user cache rather than back into the site database — see :ref:`activation-token-cache`.
+
 Examples of activation mechanism implementation are available in `activation.py <https://github.com/soxoj/maigret/blob/main/maigret/activation.py>`_ file.
 
 How to publish new version of Maigret

docs/source/locale/zh_CN/LC_MESSAGES/development.po

@@ -1078,3 +1078,42 @@ msgstr "该路线图需要更新,以反映项目当前状态以及未来计划
 #~ "—— 反斜杠加一个空格(在 ``.po`` 源里写作 ``\\\\ "
 #~ "``,渲染后的 RST 里写作 ``\\ ``)。示例:"
 
+
+#: ../../source/development.rst:68
+msgid "Running the tests offline"
+msgstr "离线运行测试"
+
+#: ../../source/development.rst:70
+msgid ""
+"Some tests reach real sites, which is why CI runs pytest with ``--reruns 3 "
+"--reruns-delay 5``. They all carry the ``slow`` marker, so deselecting it "
+"leaves a suite that passes with no network at all:"
+msgstr ""
+"部分测试会访问真实站点,这也是 CI 使用 ``--reruns 3 --reruns-delay 5`` 运行 pytest "
+"的原因。它们都带有 ``slow`` 标记,取消选择该标记后,剩下的测试在完全没有网络的情况下也能通过:"
+
+#: ../../source/development.rst:78
+msgid ""
+"This is the invocation to use when building a distribution package, since "
+"distribution builders run without network access. Measured on 0.6.4: the "
+"full suite fails 9 tests offline, ``-m \"not slow\"`` passes 403 and "
+"deselects 24."
+msgstr ""
+"构建发行版软件包时应使用这条命令,因为发行版的构建环境没有网络访问权限。基于 0.6.4 的实测:离线运行完整测试集会有 9 "
+"个测试失败,而 ``-m \"not slow\"`` 通过 403 个、取消选择 24 个。"
+
+#: ../../source/development.rst:82
+msgid ""
+"If you add a test that talks to the network, mark it ``slow`` — otherwise "
+"you silently break offline builds for every downstream packager."
+msgstr ""
+"如果你新增了访问网络的测试,请为它加上 ``slow`` 标记——否则你会在无声无息之间,破坏所有下游打包者的离线构建。"
+
+#: ../../source/development.rst:290
+msgid ""
+"Step 5 works across runs because minted tokens are written to a per-user "
+"cache rather than back into the site database — see :ref:`activation-token-"
+"cache`."
+msgstr ""
+"第 5 步之所以能跨多次运行生效,是因为获取到的令牌被写入每个用户各自的缓存,而不是写回站点数据库——参见 "
+":ref:`activation-token-cache`。"

docs/source/settings.rst

@@ -17,6 +17,9 @@ After start Maigret tries to load configuration from the following sources in ex
   # relative path, based on installed package path
   resources/settings.json
 
+  # absolute path, system-wide policy set by an administrator
+  /etc/maigret/settings.json
+
   # absolute path, configuration file in home directory
   ~/.maigret/settings.json
 

maigret/settings.py

@@ -5,6 +5,10 @@ from typing import List
 
 SETTINGS_FILES_PATHS = [
     path.join(path.dirname(path.realpath(__file__)), "resources/settings.json"),
+    # System-wide policy. Lets an administrator or a distribution package
+    # configure Maigret without editing inside the installed package, whose
+    # directory is read-only on a system-wide install anyway.
+    '/etc/maigret/settings.json',
     path.expanduser('~/.maigret/settings.json'),
     path.join(os.getcwd(), 'settings.json'),
 ]

pytest.ini

@@ -5,3 +5,5 @@ filterwarnings =
     ignore::UserWarning
     ignore:codecs.open\(\) is deprecated:DeprecationWarning:xmind.core.saver
 asyncio_mode=auto
+markers =
+    slow: hits the network or takes a long time; deselect with -m "not slow" to get an offline suite