n-notation 1.2.0
Flake8 plugin enforcing N notation
License: MIT
Requires Python: >=3.10

<h1 align="center">Линтер N-нотации</h1>
<p align="center">
<b>Теперь следовать принципам легко!</b>

</p><p align="center">
<img src="https://img.shields.io/badge/made%20by-CSSSensei-1591EA" >
<img src="https://img.shields.io/badge/Phasalo-000FFF">
<img src="https://img.shields.io/badge/coverage-91％-000080">
<img src="https://img.shields.io/badge/version-N1n2.0-0000FF">
</p>

<p align="center">
    Русский | <a href="README-en.md">English</a>
</p>

Это **flake8-плагин**, который проверяет соответствие кода правилам **N-нотации**.
Используйте его в проектах, где вы действительно пишете в этом кодстайле (или хотите быстро прогнать отдельные файлы/каталоги).

## Принципы N-нотации (кратко)

Данный плагин проверяет следующие правила философии N-нотации:

- **Имена не несут смысла.** Смысл берётся из структуры и контекста, а не из словесных идентификаторов.
- **Регистр важен:** `N...` — структуры/типы, `n...` — данные/исполняемое.
- **Файлы:** `n<цифры>.py` (см. `NNO401`).
- **Директории:** `N<цифры>[_<цифры>]...` (см. `NNO420`).
- **Переменные / функции:** `n<10 цифр>` (для булевых — `n<10 бит>`).
- **Классы:** `N<10 цифр>`, наследники — цепочка `N<id>n<id>...` (см. `NNO105`, `NNO107`).
- **Члены класса:** `n_<...>` / `_n<...>`; получатель метода — не `self`, а `n<ClassId>` (см. `NNO210`).
- **Итераторы циклов/генераторов:** `n`, `nn`, `nnn`, ...
- **Импорты:** обязателен алиас + порядок/разделение/сортировка (см. `NNO301–NNO312`).
- **Шум запрещён:** комментарии и docstring’и запрещены (кроме `# noqa...`).

> [!IMPORTANT]
> * Полное описание правил смотрите в [документации](https://github.com/Phasalo/N_notation).

## Подсказка имени (suggest)

Если правило нейминга нарушено, линтер может предложить корректное имя прямо в тексте диагностики:

`... (suggest <имя>)`

Пример:

`NNO101 var-name invalid got count (suggest n0123456789)`

## Быстрый старт

### Установка

```bash
python -m pip install n-notation
```

### Запуск линтера

Показывать только ошибки N-нотации:

```bash
python -m flake8 --select NNO .
```

Показывать ошибки N-нотации + остальные flake8 проверки:

```bash
python -m flake8 .
```

### Тестирование

Запуск всех тестов:

```bash
python -m unittest discover -s tests -v
```


## Коды ошибок

### Уровень проекта:

* `NNO401`: имя файла должно быть в формате `n<цифры>.py`
* `NNO500`: README репозитория должен содержать **точный** блок объявления N-нотации

### Уровень AST:

* `NNO101`: недопустимое имя переменной
* `NNO104`: недопустимое имя функции
* `NNO105`: при наследовании имя класса должно быть производным (`N<id>n<id>...`)
* `NNO106`: недопустимое имя класса
* `NNO107`: имя производного класса должно соответствовать цепочке именования базового класса
* `NNO108` / `NNO109`: недопустимые имена членов (`n_...` / `_n...`)
* `NNO110`: недопустимое имя итератора цикла / генератора (должно быть `n`, `nn`, ...)
* `NNO201` / `NNO202`: недопустимые имена параметров
* `NNO210`: недопустимое имя получателя метода (замена `self` должна быть `n<ИмяКласса[1:]>`)
* `NNO602`: docstring’и запрещены
* `NNO701`: аннотации переменных запрещены

### Уровень токенов:

* `NNO601`: комментарии запрещены
  (исключение: разрешены `# noqa` / `# noqa: ...`)
* Импорты:

  * `NNO301`: требуется алиас `import X as N1`
  * `NNO302` / `NNO303`: требуется алиас `from X import Y as N0000000001` (10 цифр)
  * `NNO310`: неверный порядок групп импортов
    (stdlib → third_party → local)
  * `NNO311`: неверное разделение пустыми строками между группами
  * `NNO312`: неверная числовая сортировка внутри группы

> [!NOTE]
> * Плагин намеренно строгий и может помечать код, не использующий N-нотацию
  (включая `__init__.py`).
> * При необходимости используйте `# noqa: NNO...` для локального подавления ошибок.

<br>
<p align="center">
<b>Phasalo</b><br>
<i>Делаем красиво!</i><br><br>
2026
</p>