Merge pull request #28 from S3-Platform-Inc/bugfix/27-modify-docs-and…

…-tests

Bugfix/27 modify docs and tests

.github/workflows/plugin_test.yml

@@ -7,6 +7,9 @@ on:
       - "patch*"
       - "dev"
 
+env:
+  PYTHON_VERSION: '3.11.5'
+
 jobs:
   structure-tests:
     runs-on: ubuntu-latest
@@ -15,9 +18,9 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python 3.11
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v3
         with:
-          python-version: '3.11'  # Specify Python version
+          python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Install Poetry
         run: |

.github/workflows/sync-release.yml

@@ -5,10 +5,6 @@ on:
      types: [published]
 
 env:
-  PYTHON_VERSION: '3.11.5'
-  PATH_TO_CONFIG: 'src.s3_platform_plugin_template'
-  CONFIG_FILE: 'config.json'
-  PLUGIN_NAME: 's3_platform_plugin_template'
   REPO_NAME: ${{ github.event.repository.name }}
   REPO_OWNER: ${{ github.event.repository.owner.login }}
 
@@ -33,7 +29,7 @@ jobs:
       env:
         ACCESS_KEY_ID: ${{ secrets.S3_ACCESS_KEY_ID }}
         SECRET_ACCESS_KEY: ${{ secrets.S3_SECRET_ACCESS_KEY }}
-        MIRROR_TARGET: '${{ secrets.S3_BACKET_NAME }}${{ secrets.S3_MIRROR_PATH }}${{ env.REPO_OWNER }}/${{ env.REPO_NAME }}'
+        MIRROR_TARGET: '${{ secrets.S3_BACKET_NAME }}/plugins/${{ env.REPO_OWNER }}/${{ env.REPO_NAME }}'
         STORAGE_SERVICE_URL: ${{ secrets.S3_SERVICE_URL }}
         AWS_REGION: ${{ secrets.S3_REGION }}
         MIRROR_SOURCE: './_temp_upload_files'

readme.md

@@ -1,7 +1,7 @@
 # S3 Platform Plugin Template
 
 
-> [!INFO]
+> [!NOTE]
 > Нажми на <kbd>Use this template</kbd> кнопку и клонируй его в IDE.
 
 S3 Platform Plugin Template - это репозиторий предоставляет чистый шаблон для простого и быстрого создания проекта плагина (Посмотри статью [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)).
@@ -35,3 +35,73 @@ my-plugin/                      # Репозиторий
 │
 └── plugin.xml                  # Основной декларативный файл плагина
 ```
+
+### Plugin.xml
+Стандартный вид `plugin.xml`:
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<project name="[ uniq plugin name ]">
+    <version>[ version ]</version>
+</project>
+```
+- уникальное имя плагина [`uniq plugin name`]. Используется как имя каталога с файлами плагина и в тестах.
+- версия плагина [`version`]. Имеет формат `[N > 0].[N >= 0]`. Последняя стабильная версия по умолчанию - `3.0`.
+
+### src
+В каталоге `src` должен обязательно находиться каталог, названный [`uniq plugin name`] (Такое же название, как и в [plugin.xml](#pluginxml)). 
+
+### uniq plugin name
+- Каталог плагина должен обязательно содержать файл `repo/src/[uniq plugin name]/config.py`.
+- Все дополнительные файлы плагина (парсер, вспомогательные файлы) должны быть расположены в этом разделе `repo/src/[uniq plugin name]/`.
+
+#### config.py
+Файл config.py - это обязательный файл плагина. 
+
+> [!WARNING]
+> Нужно просмотреть файл `config.py` и поля, связанные с уникальными названиями и файлами.
+
+> [!TIP]
+> Читайте комментарии в файле `config.py`
+
+
+## GitHub Actions
+В репозитории настроен CI/CD на GitHub Actions.
+Для его полноценной работы необходимо добавить секреты в репозиторий на стороне GitHub (см. [раздел](https://github.com/S3-Platform-Inc/s3-platform-plugin-template/settings/secrets/actions)).
+
+Если репозиторий с плагином создан в аккаунте организации [S3 Platform](https://github.com/S3-Platform-Inc), то можно воспользоваться секретами организации. В противном случае нужно создавать секреты репозитория.
+
+### Секреты
+
+**CI/СD:**
+- `RELEASE_TOKEN`: создается в GitHub для работы с релизами репозиториев (см. [здесь](https://github.com/settings/personal-access-tokens)).
+
+S3 Platform использует Amazon S3 в качестве [объектного хранилища](https://ru.wikipedia.org/wiki/Amazon_S3).
+Следующие секреты требуются для подключения к нему (_Все 5 значений можно получить в панели администратора хранилища_):
+- `S3_ACCESS_KEY_ID`
+- `S3_SECRET_ACCESS_KEY`
+- `S3_BACKET_NAME`
+- `S3_REGION`
+- `S3_SERVICE_URL`
+
+### Обновление CI/CD 
+
+> [!IMPORTANT]
+> После написание плагина от разработчика потребуется обновить некоторые поля в github actions yml файлах.
+
+#### [Файл сборка](.github/workflows/build-release.yml)
+Требуется обновить переменную `PATH_TO_CONFIG` в `env` на `src.[uniq plugin name].config`.
+
+
+## Тесты
+
+> [!WARNING]
+> Требуется дополнить некоторые тесты, которые помечены отметкой `!WARNING`
+
+В [тестах нагрузки](tests/payload/test_plugin_run.py) в функции `run_payload()` нужно обновить сигнатуру вызова (соответствие главному классу парсера).
+
+> [!TIP]
+> Последующие тесты с отметкой нужно просмотреть и обновить при необходимости. 
+
+> [!TIP]
+> Рекомендуется дополнять тесты для парсеров с необычной логикой.
+

src/s3_platform_plugin_template/config.py

@@ -16,15 +16,15 @@
 
 config = PluginConfig(
     plugin=CoreConfig(
-        reference='my-template-source',
-        type=SOURCE,
-        files=['template_payload.py', ],
+        reference='my-template-source',         # уникальное имя источника
+        type=SOURCE,                            # Тип источника (SOURCE, ML, PIPELINE)
+        files=['template_payload.py', ],        # Список файлов, которые будут использоваться в плагине (эти файлы будут сохраняться в платформе)
         is_localstorage=False
     ),
     task=TaskConfig(
         trigger=trigger.TriggerConfig(
             type=trigger.SCHEDULE,
-            interval=datetime.timedelta(days=1),
+            interval=datetime.timedelta(days=1),    # Интервал перезапуска плагина
         )
     ),
     middleware=MiddlewareConfig(
@@ -38,8 +38,8 @@
         bus=None,
     ),
     payload=payload.PayloadConfig(
-        file='template_payload.py',
-        classname='MyTemplateParser',
+        file='template_payload.py',                 # python файл плагина (точка входа). Этот файл должен быть указан в `plugin.files[*]`
+        classname='MyTemplateParser',               # имя python класса в указанном файле
         entry=payload.entry.EntryConfig(
             method='content',
             params=[

tests/config/test_config.py

@@ -76,6 +76,7 @@ def test_config_payload_entry_structure(self, fix_plugin_config, project_config)
         _pentry = fix_plugin_config.__dict__.get(PluginStructure.PAYLOAD).__dict__.get('entry')
 
         assert isinstance(_pentry.__dict__.get('method'), str)
+        assert _pentry.__dict__.get('method') == 'content', f"Метод запуска плагина {_pentry.__dict__.get('method')} не соответствуе значению по умолчанию `content`"
         assert isinstance(_pentry.__dict__.get('params'), list) and all([isinstance(it, AbcParamConfig) for it in _pentry.__dict__.get('params')])
 
     def test_config_plugin_files(self, fix_plugin_config, project_config):

tests/payload/test_plugin_run.py

@@ -58,6 +58,7 @@ def fix_payload(self, project_config, fix_plugin_config) -> Type[S3PParserBase]:
 
     def run_payload(self, payload: Type[S3PParserBase], driver: WebDriver, refer: S3PRefer, max_document: int,
                     timeout: int = 2):
+        # !WARNING Требуется изменить путь до актуального парсера плагина
         from src.s3_platform_plugin_template.template_payload import MyTemplateParser
         if isinstance(payload, type(MyTemplateParser)):
             _payload = payload(refer=refer, web_driver=driver, max_count_documents=max_document, last_document=None)
@@ -71,16 +72,19 @@ def execute() -> tuple[S3PDocument, ...]:
             assert False, "Тест проверяет payload плагина"
 
     def test_run_with_0_docs_restriction(self, chrome_driver, fix_s3pRefer, fix_payload):
+        # !WARNING Обновить тест для актуального парсера
         max_docs = 10
         docs = self.run_payload(fix_payload, chrome_driver, fix_s3pRefer, max_docs)
         assert len(docs) <= max_docs
 
     def test_return_types(self, chrome_driver, fix_s3pRefer, fix_payload):
+        # !WARNING Обновить тест для актуального парсера
         max_docs = 10
         docs = self.run_payload(fix_payload, chrome_driver, fix_s3pRefer, max_docs)
         assert isinstance(docs, tuple) and all([isinstance(el, S3PDocument) for el in docs])
 
     def test_returned_parameters_are_sufficient(self, chrome_driver, fix_s3pRefer, fix_payload):
+        # !WARNING Обновить тест для актуального парсера
         max_docs = 10
         docs = self.run_payload(fix_payload, chrome_driver, fix_s3pRefer, max_docs)
         for el in docs: