{"id":21253924,"url":"https://github.com/courseorchestra/mellophone-valve","last_synced_at":"2026-02-15T13:10:53.000Z","repository":{"id":90896584,"uuid":"265857638","full_name":"CourseOrchestra/mellophone-valve","owner":"CourseOrchestra","description":"Python mellophone requests wrapper","archived":false,"fork":false,"pushed_at":"2024-10-09T16:36:32.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-21T21:15:35.096Z","etag":null,"topics":["auth","mellophone"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CourseOrchestra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-21T13:37:10.000Z","updated_at":"2024-10-09T16:35:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"98e784aa-6f43-4522-a981-e13300a34ddf","html_url":"https://github.com/CourseOrchestra/mellophone-valve","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CourseOrchestra%2Fmellophone-valve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CourseOrchestra%2Fmellophone-valve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CourseOrchestra%2Fmellophone-valve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CourseOrchestra%2Fmellophone-valve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CourseOrchestra","download_url":"https://codeload.github.com/CourseOrchestra/mellophone-valve/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243690149,"owners_count":20331729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth","mellophone"],"created_at":"2024-11-21T03:53:29.223Z","updated_at":"2026-02-15T13:10:52.994Z","avatar_url":"https://github.com/CourseOrchestra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mellophone-valve\n\n[![CI Push](https://github.com/CourseOrchestra/mellophone-valve/actions/workflows/ci-push.yml/badge.svg)](https://github.com/CourseOrchestra/mellophone-valve/actions/workflows/ci-push.yml)\n[![CodeQL](https://github.com/CourseOrchestra/mellophone-valve/actions/workflows/codeql.yml/badge.svg)](https://github.com/CourseOrchestra/mellophone-valve/actions/workflows/codeql.yml)\n[![Python](https://img.shields.io/badge/python-tested%203.7%E2%80%933.14%20%7C%20runtime%20%3E%3D3.13-blue)](tox.ini)\n\nPython-клиент для Mellophone (`sync` + `async`) с unit- и интеграционными тестами.\n\n## Требования\n\n- Runtime для пакета: Python `\u003e= 3.13` (см. `pyproject.toml`)\n- [uv](https://docs.astral.sh/uv/)\n- Docker + Docker Compose (для интеграционных тестов и `tox`-прогонов)\n\nПримечание: тесты в CI/tox гоняются на Python `3.7-3.14`.\n\n## Установка\n\nИз Git (рекомендуется фиксировать тег, например `v3.0.0`):\n\n### pip\n\n```bash\npip install \"mellophone-valve[httpx] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0\"\npip install \"mellophone-valve[requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0\"\npip install \"mellophone-valve[httpx,requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0\"\n```\n\n### Pipfile (Pipenv)\n\nДля `Pipenv` надежнее указывать Git-зависимость с extras напрямую в `Pipfile`.\n\n```toml\n[packages]\nmellophone-valve = {git = \"https://github.com/CourseOrchestra/mellophone-valve.git\", ref = \"v3.0.0\", extras = [\"httpx\"]}\n# или\nmellophone-valve = {git = \"https://github.com/CourseOrchestra/mellophone-valve.git\", ref = \"v3.0.0\", extras = [\"requests\"]}\n# или\nmellophone-valve = {git = \"https://github.com/CourseOrchestra/mellophone-valve.git\", ref = \"v3.0.0\", extras = [\"httpx\", \"requests\"]}\n```\n\n### poetry\n\nДля `Poetry` надежнее фиксировать Git-зависимость с extras в `pyproject.toml`:\n\n```toml\n[tool.poetry.dependencies]\nmellophone-valve = { git = \"https://github.com/CourseOrchestra/mellophone-valve.git\", rev = \"v3.0.0\", extras = [\"httpx\"] }\n# или\nmellophone-valve = { git = \"https://github.com/CourseOrchestra/mellophone-valve.git\", rev = \"v3.0.0\", extras = [\"requests\"] }\n# или\nmellophone-valve = { git = \"https://github.com/CourseOrchestra/mellophone-valve.git\", rev = \"v3.0.0\", extras = [\"httpx\", \"requests\"] }\n```\n\nCLI-вариант для `Poetry`:\n\n```bash\npoetry add \"git+https://github.com/CourseOrchestra/mellophone-valve.git#v3.0.0\" --extras httpx\npoetry add \"git+https://github.com/CourseOrchestra/mellophone-valve.git#v3.0.0\" --extras requests\npoetry add \"git+https://github.com/CourseOrchestra/mellophone-valve.git#v3.0.0\" --extras \"httpx requests\"\n```\n\n### uv\n\n```bash\nuv add \"mellophone-valve[httpx] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0\"\nuv add \"mellophone-valve[requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0\"\nuv add \"mellophone-valve[httpx,requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0\"\n```\n\nПримечания:\n\n- `async`-методы требуют `httpx` (`mellophone-valve[httpx]`).\n- При установке только `requests` доступны только `sync`-методы.\n- В качестве `ref` можно использовать `tag`, `branch` или `commit SHA`.\n\n## Быстрый старт\n\n```python\nfrom mellophone import Mellophone\n\nclient = Mellophone(base_url=\"http://localhost:8082/mellophone\")\nsession_id = client.login(\"user\", \"password\")\nprint(client.is_authenticated(session_id))\nclient.logout(session_id)\n```\n\n## API клиента\n\nКласс `Mellophone` поддерживает пары методов `sync/async`:\n\nАвторизация и сессия:\n\n- `login/login_async` - выполняет логин, сохраняет `session_id` в клиенте и возвращает `ses_id` (если не передан, генерируется автоматически).\n- `logout/logout_async` - завершает сессию по `ses_id` (или по `self.session_id`).\n- `is_authenticated/is_authenticated_async` - проверяет сессию; возвращает словарь `user` при успехе или `False` при `403`.\n\nПроверки:\n\n- `check_credentials/check_credentials_async` - проверяет логин/пароль без создания сессии, возвращает данные `user`.\n- `check_name/check_name_async` - проверяет логин/имя пользователя в текущей/переданной сессии, возвращает данные `user`.\n\nПароли и идентификатор сессии:\n\n- `change_pwd/change_pwd_async` - меняет пароль пользователя, связанного с переданным `ses_id` (если `ses_id` не передан, используется `self.session_id`).\n- `change_user_pwd/change_user_pwd_async` - меняет пароль указанного пользователя `username`.\n- `change_app_ses_id/change_app_ses_id_async` - меняет `ses_id` сессии (`oldsesid` -\u003e `newsesid`); `self.session_id` обновляется только если `ses_id` не передан.\n\nПровайдеры и списки пользователей:\n\n- `import_gp/import_gp_async` - импортирует groups/providers, возвращает список строк из ответа API.\n- `get_provider_list/get_provider_list_async` - возвращает список/структуру провайдеров по учетным данным.\n- `get_user_list/get_user_list_async` - возвращает список пользователей по `gp` (опционально `ip`, `pid`); токен берется из `self.user_manage_token`.\n\nНастройки и user management:\n\n- `set_settings/set_settings_async` - обновляет настройки (`lockout_time`, `login_attempts_allowed`); токен берется из `self.set_settings_token`.\n- `create_user/create_user_async` - создает пользователя (`POST /user/create`, XML payload); токен берется из `self.user_manage_token`.\n- `update_user/update_user_async` - обновляет пользователя по `sid` (`POST /user/{sid}`, XML payload); токен берется из `self.user_manage_token`.\n- `delete_user/delete_user_async` - удаляет пользователя по `sid` (`DELETE /user/{sid}`); токен берется из `self.user_manage_token`.\n\nСостояние сессии:\n\n- `set_state/set_state_async` - сохраняет произвольное состояние для `ses_id`.\n- `get_state/get_state_async` - возвращает ранее сохраненное состояние для `ses_id`.\n\nТакже доступны исключения:\n\n- `HttpError` - базовая HTTP-ошибка API (`status_code`, `response_text`).\n- `BadRequestError` - ошибка `HTTP 400` (некорректный запрос).\n- `UnauthorizedError` - ошибка `HTTP 401` (неавторизован).\n- `ForbiddenError` - ошибка `HTTP 403` (доступ запрещен).\n- `NotFoundError` - ошибка `HTTP 404` (ресурс не найден).\n- `ServerError` - серверная ошибка `HTTP 5xx`.\n- `TransportError` - транспортная ошибка HTTP-клиента (сеть/соединение).\n- `RequestTimeoutError` - превышен таймаут запроса.\n- `ResponseParseError` - не удалось распарсить XML-ответ API.\n- `MissingTokenError` - в клиенте не задан обязательный токен (`set_settings_token` или `user_manage_token`).\n- `AsyncClientUnavailableError` - вызваны `async`-методы без установленного `httpx`.\n\n## Локальный стенд через Docker\n\n```bash\ndocker compose up -d\n```\n\nСервисы:\n\n- Mellophone: `http://localhost:8082/mellophone`\n- PostgreSQL: `localhost:5430`\n\nИнициализация БД выполняется автоматически из `docker-config/init-db.sql` через mount в `db:/docker-entrypoint-initdb.d/init-db.sql`.\n\nВажно: скрипты из `/docker-entrypoint-initdb.d` выполняются только при первичной инициализации Postgres volume.\n\n## Линт\n\n```bash\nuv run pre-commit run --all-files\n```\n\n## Тесты\n\nВсе тесты:\n\n```bash\nuv run pytest -q\n```\n\nТолько unit-тесты:\n\n```bash\nuv run pytest tests/test_mellophone.py -q\n```\n\nИнтеграционные:\n\n```bash\nuv run pytest tests/test_integration_mellophone.py -q\n```\n\nМатрица `tox` (Docker, Python `3.7-3.14`):\n\n```bash\ntox -p auto\n```\n\n## Coverage\n\n```bash\nuv run --with coverage --with pytest-cov pytest --cov=. --cov-report=term-missing -q\n```\n\n## Релизы\n\nРелиз создается автоматически при `push` в `master` workflow'ом `CI Push`.\n\nУсловия для релиза:\n\n- `Tests` завершился успешно.\n- `Version Check` завершился успешно (версия в `pyproject.toml` увеличена по правилам `vuh`).\n\nКак формируется релиз:\n\n- версия берется из `vuh lv -q`;\n- создается тег формата `v\u003cversion\u003e` и GitHub Release;\n- если тег уже существует, релиз пропускается.\n\n## VS Code Tasks\n\nВ `.vscode/tasks.json` добавлены задачи:\n\n- `docker:stop` - остановить `docker compose` и удалить volume (`docker compose down -v`).\n- `docker:start` - поднять локальный стенд в фоне (`docker compose up -d`).\n- `docker:restart` - последовательно выполнить `docker:stop` и `docker:start`.\n- `uv:sync` - синхронизировать окружение и зависимости (`uv sync`).\n- `uv:update` - обновить lock-файл зависимостей (`uv lock --upgrade`).\n- `pytest:coverage` - запустить тесты с coverage в терминал.\n- `pytest:coverage:html` - запустить тесты с coverage в терминал и HTML-отчет (`htmlcov/`).\n- `tox:test` - запустить матрицу `tox` (`tox -p auto`).\n- `lint:ruff` - проверить код через `ruff check .`.\n- `lint:ruff:fix` - исправить автоисправляемые проблемы `ruff`.\n- `lint:pre-commit` - прогнать `pre-commit` по всем файлам.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcourseorchestra%2Fmellophone-valve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcourseorchestra%2Fmellophone-valve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcourseorchestra%2Fmellophone-valve/lists"}