diff --git a/docs/source/development.rst b/docs/source/development.rst index fa80db8..738b862 100644 --- a/docs/source/development.rst +++ b/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 `_ file. How to publish new version of Maigret diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/development.po b/docs/source/locale/zh_CN/LC_MESSAGES/development.po index a2b6811..e897cf9 100644 --- a/docs/source/locale/zh_CN/LC_MESSAGES/development.po +++ b/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`。" diff --git a/docs/source/settings.rst b/docs/source/settings.rst index 08ba0dc..eae7431 100644 --- a/docs/source/settings.rst +++ b/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 diff --git a/maigret/settings.py b/maigret/settings.py index e8eedf4..fb022ef 100644 --- a/maigret/settings.py +++ b/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'), ] diff --git a/pytest.ini b/pytest.ini index 5014b80..6484bb6 100644 --- a/pytest.ini +++ b/pytest.ini @@ -4,4 +4,6 @@ filterwarnings = error ignore::UserWarning ignore:codecs.open\(\) is deprecated:DeprecationWarning:xmind.core.saver -asyncio_mode=auto \ No newline at end of file +asyncio_mode=auto +markers = + slow: hits the network or takes a long time; deselect with -m "not slow" to get an offline suite \ No newline at end of file