update docs

Author: Friskes

.pre-commit-config.yaml

@@ -2,13 +2,13 @@
 # https://verdantfox.com/blog/how-to-use-git-pre-commit-hooks-the-hard-way-and-the-easy-way
 # https://docs.astral.sh/ruff/integrations/
 # https://pre-commit.com/
-# Commands:
-#   pre-commit run  # Запустить pre-commit проверку для теста
-#   pre-commit install  # Создать файл в директории .git/hooks/pre-commit
-# После создания файла, при любом git commit будет запускаться pre-commit проверка.
-# Если возникли проблемы с pre-commit и нужно срочно сделать commit то можно
-# временно удалить проверку до выяснения проблемы с помощью:
-#   pre-commit uninstall
+
+# How to use it?
+#   pre-commit run  # Run the pre-commit check manually.
+#   pre-commit install  # Create a file in the directory to run automatically on commit: .git/hooks/pre-commit
+#   pre-commit uninstall  # Delete a file in the directory to disable automatic startup on commit.
+#   git commit --no-verify -m "msg"  # Disable startup for this commit (--no-verify OR -n)
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
@@ -29,15 +29,15 @@ repos:
           - tomli
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.4.1'
+    rev: 'v0.8.0'
     hooks:
       - id: ruff
-        name: Проверка кода ruff линтером.
+        name: Check the codebase using the ruff linter.
         args: [
           --fix,
           --quiet,
           # --silent,
         ]
 
       - id: ruff-format
-        name: Проверка кода ruff форматтером.
+        name: Check the codebase using the ruff formatter.

pyproject.toml

@@ -44,15 +44,15 @@ dev = [
     "pytest-django>=4.8.0",
 
     "pre-commit>=3.5.0",
-    "ruff==0.4.1",
+    "ruff==0.8.0",
     "pytest>=7.0.1",
     "mypy>=1.10.0",
     "pytest-cov>=5.0.0",
 ]
 ci = [
     "pytest-django>=4.8.0",
 
-    "ruff==0.4.1",
+    "ruff==0.8.0",
     "pytest>=7.0.1",
     "mypy>=1.10.0",
     "pytest-cov>=5.0.0",
@@ -119,19 +119,23 @@ disable_error_code = [
 
 [tool.coverage.run]
 concurrency = ["multiprocessing", "thread"]
-omit = ["*/tests/*"]
+omit = ["*/tests/*", "types.py", "_sqlite3_adapters_and_converters.py"]  # Не проверять директории и(или) файлы
 parallel = true
+branch = true  # Включать в замер результаты вхождения в условия
 source = ["src.capture_db_queries"]
 
 [tool.coverage.report]
 fail_under = 80  # Тест упадёт если покрытие составит менее 80%
+skip_covered = true  # Не включать в отчет информацию о файлах со 100% покрытием
+show_missing = true  # Включать в отчет информацию о номерах не протестированных строк кода
+sort = "-Cover"  # Сортировать отчет по уровню покрытия
 
 
 # https://docs.astral.sh/ruff/settings/
 # https://docs.astral.sh/ruff/configuration/#full-command-line-interface
 # cmd: ruff format  # Отформатирует все файлы в `.` текущем каталоге.
 [tool.ruff]
-required-version = "<=0.5.7"
+required-version = "<=0.8.0"
 target-version = "py312"  # Версия python которую будет обслуживать ruff
 line-length = 105  # Макс длина строки кода после которой будет выполнен автоперенос
 indent-width = 4
@@ -186,6 +190,7 @@ extend-select = [
     "SIM",    # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
     "TID",    # https://docs.astral.sh/ruff/rules/#flake8-tidy-imports-tid
     "TCH",    # https://docs.astral.sh/ruff/rules/#flake8-type-checking-tch
+    "TD",     # https://docs.astral.sh/ruff/rules/#flake8-todos-td
     "INT",    # https://docs.astral.sh/ruff/rules/#flake8-gettext-int
     "FLY",    # https://docs.astral.sh/ruff/rules/#flynt-fly
     "PERF",   # https://docs.astral.sh/ruff/rules/#perflint-perf
@@ -196,11 +201,10 @@ extend-select = [
 ]
 ignore = [
     # https://docs.astral.sh/ruff/rules/#pyflakes-f
-    # "F401",    # (не ругаться на неиспользуемые импорты)
-    # "F841",    # (не ругаться на неиспользуемые переменные)
     "F403",    # (не ругаться на использование from ... import *)
     # https://docs.astral.sh/ruff/rules/#pyupgrade-up
     "UP031",   # (не ругаться на форматирование с помощью %s)
+    "UP036",   # (не ругаться на использование sys.version_info если текущая версия не подпадает под условие)
     # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
     "G004",    # (не ругаться на использование f-строк для сообщения лога)
     # https://docs.astral.sh/ruff/rules/#ruff-specific-rules-ruf
@@ -212,6 +216,7 @@ ignore = [
     "PT009",   # (не ругаться на unittest ассерты)
     "PT027",   # (не ругаться на unittest ассерты)
     "PT001",   # (не ругаться на отсутствие круглых скобок у декоратора fixture)
+    "PT004",   # (не ругаться на написание фикстур которые ничего не возвращают без префикса "_")
     # https://docs.astral.sh/ruff/rules/#flake8-implicit-str-concat-isc
     "ISC001",  # (конфликт с `COM812`)
     # https://docs.astral.sh/ruff/rules/#flake8-commas-com
@@ -226,11 +231,16 @@ ignore = [
     "RET503",  # (не ругаться на отсутствие return None в конце функций)
     # https://docs.astral.sh/ruff/rules/#flake8-blind-except-ble
     "BLE001",  # (не ругаться на обработку обычного Exception)
-    # https://docs.astral.sh/ruff/rules/#flake8-django-dj  #! (ВРЕМЕННО)
+    # https://docs.astral.sh/ruff/rules/#flake8-django-dj
+    # https://docs.djangoproject.com/en/4.2/ref/models/fields/#null
+    # https://sentry.io/answers/django-difference-between-null-and-blank/
+    # https://www.django-rest-framework.org/api-guide/fields/#charfield
     "DJ001",   # (не ругаться на использование null в моделях для текстовых полей)
     # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
     # {} VS dict()  # https://switowski.com/blog/dict-function-vs-literal-syntax/
     "C408",    # (не ругаться на использование классов коллекций вместо их литералов)
+    "TD001",   # (не ругаться на использование FIXME и XXX)
+    "TD003",   # (не ругаться на отсутствие ссылки на issues)
 ]
 # Не давать исправлять эти ошибки в тултипе, и в том числе автоматически при линте через команду
 unfixable = [

src/capture_db_queries/__init__.py

@@ -1,3 +1,4 @@
+import sys
 import warnings
 
 warnings.filterwarnings(
@@ -6,6 +7,8 @@
     category=DeprecationWarning,
 )
 
-from . import _sqlite3_adapters_and_converters  # noqa: F401, E402
+if sys.version_info >= (3, 12):
+    from . import _sqlite3_adapters_and_converters  # noqa: F401
+
 from ._logging import switch_logger, switch_trace  # noqa: F401, E402
 from .decorators import CaptureQueries, ExtCaptureQueriesContext, capture_queries  # noqa: F401, E402

tests/conftest.py

@@ -50,14 +50,14 @@ def intercept_output() -> Generator[StringIO, None, None]:
 
 
 @pytest.fixture
-def _ignore_deprecation() -> Generator[None, None, None]:
+def ignore_deprecation() -> Generator[None, None, None]:
     warnings.simplefilter('ignore', DeprecationWarning)
     yield
     warnings.resetwarnings()
 
 
 @pytest.fixture
-def _debug_true() -> Generator[None, None, None]:
+def debug_true() -> Generator[None, None, None]:
     switch_logger(True)
     # switch_trace(True)
     yield

tests/test_decorators.py

@@ -49,7 +49,7 @@ def setup_method(self, method: Callable[..., Any]) -> None:
     def call_capture_queries(self, **kwargs: Any) -> CaptureQueries:
         raise NotImplementedError
 
-    # @pytest.mark.usefixtures('_debug_true')
+    # @pytest.mark.usefixtures('debug_true')
     def test_basic_logic(self) -> None:
         obj = self.call_capture_queries()
 
@@ -164,7 +164,7 @@ def call_capture_queries(self, **kwargs: Any) -> CaptureQueries:
                 _select(self.reporter.pk, self.article.pk)
         return obj
 
-    # @pytest.mark.usefixtures('_debug_true')
+    # @pytest.mark.usefixtures('debug_true')
     def test_param__number_runs(self) -> None:
         obj = self.call_capture_queries(number_runs=3)
 
@@ -338,7 +338,7 @@ def test_without_requests(self) -> None:
 class TestOutputCaptureQueries:
     """The -s argument must be passed when running py test to output output"""
 
-    # @pytest.mark.usefixtures('_debug_true')
+    # @pytest.mark.usefixtures('debug_true')
     def test_capture_queries_loop(self, intercept_output: StringIO) -> None:
         date_now = timezone.now().date()
 
@@ -352,7 +352,7 @@ def test_capture_queries_loop(self, intercept_output: StringIO) -> None:
             output,
         ), f'incorrect output = {output}'
 
-    # @pytest.mark.usefixtures('_debug_true')
+    # @pytest.mark.usefixtures('debug_true')
     def test_capture_queries_decorator(self, intercept_output: StringIO) -> None:
         date_now = timezone.now().date()
 
@@ -367,7 +367,7 @@ def _() -> None:
             output,
         ), f'incorrect output = {output}'
 
-    # @pytest.mark.usefixtures('_debug_true')
+    # @pytest.mark.usefixtures('debug_true')
     def test_capture_queries_context_manager(self, intercept_output: StringIO) -> None:
         with CaptureQueries() as ctx:  # noqa: F841
             request_to_db()
@@ -381,7 +381,7 @@ def test_capture_queries_context_manager(self, intercept_output: StringIO) -> No
 
 
 @pytest.mark.django_db(transaction=True)
-@pytest.mark.usefixtures('_ignore_deprecation')
+@pytest.mark.usefixtures('ignore_deprecation')
 def test_capture_queries(intercept_output: StringIO) -> None:
     """Обязательно должен быть передан аргумент -s при запуске pytest, для вывода output"""
 
@@ -398,7 +398,7 @@ def _() -> None:
 
 
 @pytest.mark.django_db(transaction=True)
-@pytest.mark.usefixtures('_ignore_deprecation')
+@pytest.mark.usefixtures('ignore_deprecation')
 def test_capture_queries_with_advanced_verb_and_queries(intercept_output: StringIO) -> None:
     """Обязательно должен быть передан аргумент -s при запуске pytest, для вывода output"""
 
@@ -433,7 +433,7 @@ def _() -> None:
 
 
 @pytest.mark.django_db(transaction=True)
-@pytest.mark.usefixtures('_ignore_deprecation')
+@pytest.mark.usefixtures('ignore_deprecation')
 def test_ext_capture_queries_context(intercept_output: StringIO) -> None:
     """Обязательно должен быть передан аргумент -s при запуске pytest, для вывода output"""