https://github.com/courseorchestra/mellophone-valve
Python mellophone requests wrapper
https://github.com/courseorchestra/mellophone-valve
auth mellophone
Last synced: 10 days ago
JSON representation
Python mellophone requests wrapper
- Host: GitHub
- URL: https://github.com/courseorchestra/mellophone-valve
- Owner: CourseOrchestra
- License: mit
- Created: 2020-05-21T13:37:10.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-09T16:36:32.000Z (over 1 year ago)
- Last Synced: 2025-01-21T21:15:35.096Z (about 1 year ago)
- Topics: auth, mellophone
- Language: Python
- Size: 30.3 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mellophone-valve
[](https://github.com/CourseOrchestra/mellophone-valve/actions/workflows/ci-push.yml)
[](https://github.com/CourseOrchestra/mellophone-valve/actions/workflows/codeql.yml)
[](tox.ini)
Python-клиент для Mellophone (`sync` + `async`) с unit- и интеграционными тестами.
## Требования
- Runtime для пакета: Python `>= 3.13` (см. `pyproject.toml`)
- [uv](https://docs.astral.sh/uv/)
- Docker + Docker Compose (для интеграционных тестов и `tox`-прогонов)
Примечание: тесты в CI/tox гоняются на Python `3.7-3.14`.
## Установка
Из Git (рекомендуется фиксировать тег, например `v3.0.0`):
### pip
```bash
pip install "mellophone-valve[httpx] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0"
pip install "mellophone-valve[requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0"
pip install "mellophone-valve[httpx,requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0"
```
### Pipfile (Pipenv)
Для `Pipenv` надежнее указывать Git-зависимость с extras напрямую в `Pipfile`.
```toml
[packages]
mellophone-valve = {git = "https://github.com/CourseOrchestra/mellophone-valve.git", ref = "v3.0.0", extras = ["httpx"]}
# или
mellophone-valve = {git = "https://github.com/CourseOrchestra/mellophone-valve.git", ref = "v3.0.0", extras = ["requests"]}
# или
mellophone-valve = {git = "https://github.com/CourseOrchestra/mellophone-valve.git", ref = "v3.0.0", extras = ["httpx", "requests"]}
```
### poetry
Для `Poetry` надежнее фиксировать Git-зависимость с extras в `pyproject.toml`:
```toml
[tool.poetry.dependencies]
mellophone-valve = { git = "https://github.com/CourseOrchestra/mellophone-valve.git", rev = "v3.0.0", extras = ["httpx"] }
# или
mellophone-valve = { git = "https://github.com/CourseOrchestra/mellophone-valve.git", rev = "v3.0.0", extras = ["requests"] }
# или
mellophone-valve = { git = "https://github.com/CourseOrchestra/mellophone-valve.git", rev = "v3.0.0", extras = ["httpx", "requests"] }
```
CLI-вариант для `Poetry`:
```bash
poetry add "git+https://github.com/CourseOrchestra/mellophone-valve.git#v3.0.0" --extras httpx
poetry add "git+https://github.com/CourseOrchestra/mellophone-valve.git#v3.0.0" --extras requests
poetry add "git+https://github.com/CourseOrchestra/mellophone-valve.git#v3.0.0" --extras "httpx requests"
```
### uv
```bash
uv add "mellophone-valve[httpx] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0"
uv add "mellophone-valve[requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0"
uv add "mellophone-valve[httpx,requests] @ git+https://github.com/CourseOrchestra/mellophone-valve.git@v3.0.0"
```
Примечания:
- `async`-методы требуют `httpx` (`mellophone-valve[httpx]`).
- При установке только `requests` доступны только `sync`-методы.
- В качестве `ref` можно использовать `tag`, `branch` или `commit SHA`.
## Быстрый старт
```python
from mellophone import Mellophone
client = Mellophone(base_url="http://localhost:8082/mellophone")
session_id = client.login("user", "password")
print(client.is_authenticated(session_id))
client.logout(session_id)
```
## API клиента
Класс `Mellophone` поддерживает пары методов `sync/async`:
Авторизация и сессия:
- `login/login_async` - выполняет логин, сохраняет `session_id` в клиенте и возвращает `ses_id` (если не передан, генерируется автоматически).
- `logout/logout_async` - завершает сессию по `ses_id` (или по `self.session_id`).
- `is_authenticated/is_authenticated_async` - проверяет сессию; возвращает словарь `user` при успехе или `False` при `403`.
Проверки:
- `check_credentials/check_credentials_async` - проверяет логин/пароль без создания сессии, возвращает данные `user`.
- `check_name/check_name_async` - проверяет логин/имя пользователя в текущей/переданной сессии, возвращает данные `user`.
Пароли и идентификатор сессии:
- `change_pwd/change_pwd_async` - меняет пароль пользователя, связанного с переданным `ses_id` (если `ses_id` не передан, используется `self.session_id`).
- `change_user_pwd/change_user_pwd_async` - меняет пароль указанного пользователя `username`.
- `change_app_ses_id/change_app_ses_id_async` - меняет `ses_id` сессии (`oldsesid` -> `newsesid`); `self.session_id` обновляется только если `ses_id` не передан.
Провайдеры и списки пользователей:
- `import_gp/import_gp_async` - импортирует groups/providers, возвращает список строк из ответа API.
- `get_provider_list/get_provider_list_async` - возвращает список/структуру провайдеров по учетным данным.
- `get_user_list/get_user_list_async` - возвращает список пользователей по `gp` (опционально `ip`, `pid`); токен берется из `self.user_manage_token`.
Настройки и user management:
- `set_settings/set_settings_async` - обновляет настройки (`lockout_time`, `login_attempts_allowed`); токен берется из `self.set_settings_token`.
- `create_user/create_user_async` - создает пользователя (`POST /user/create`, XML payload); токен берется из `self.user_manage_token`.
- `update_user/update_user_async` - обновляет пользователя по `sid` (`POST /user/{sid}`, XML payload); токен берется из `self.user_manage_token`.
- `delete_user/delete_user_async` - удаляет пользователя по `sid` (`DELETE /user/{sid}`); токен берется из `self.user_manage_token`.
Состояние сессии:
- `set_state/set_state_async` - сохраняет произвольное состояние для `ses_id`.
- `get_state/get_state_async` - возвращает ранее сохраненное состояние для `ses_id`.
Также доступны исключения:
- `HttpError` - базовая HTTP-ошибка API (`status_code`, `response_text`).
- `BadRequestError` - ошибка `HTTP 400` (некорректный запрос).
- `UnauthorizedError` - ошибка `HTTP 401` (неавторизован).
- `ForbiddenError` - ошибка `HTTP 403` (доступ запрещен).
- `NotFoundError` - ошибка `HTTP 404` (ресурс не найден).
- `ServerError` - серверная ошибка `HTTP 5xx`.
- `TransportError` - транспортная ошибка HTTP-клиента (сеть/соединение).
- `RequestTimeoutError` - превышен таймаут запроса.
- `ResponseParseError` - не удалось распарсить XML-ответ API.
- `MissingTokenError` - в клиенте не задан обязательный токен (`set_settings_token` или `user_manage_token`).
- `AsyncClientUnavailableError` - вызваны `async`-методы без установленного `httpx`.
## Локальный стенд через Docker
```bash
docker compose up -d
```
Сервисы:
- Mellophone: `http://localhost:8082/mellophone`
- PostgreSQL: `localhost:5430`
Инициализация БД выполняется автоматически из `docker-config/init-db.sql` через mount в `db:/docker-entrypoint-initdb.d/init-db.sql`.
Важно: скрипты из `/docker-entrypoint-initdb.d` выполняются только при первичной инициализации Postgres volume.
## Линт
```bash
uv run pre-commit run --all-files
```
## Тесты
Все тесты:
```bash
uv run pytest -q
```
Только unit-тесты:
```bash
uv run pytest tests/test_mellophone.py -q
```
Интеграционные:
```bash
uv run pytest tests/test_integration_mellophone.py -q
```
Матрица `tox` (Docker, Python `3.7-3.14`):
```bash
tox -p auto
```
## Coverage
```bash
uv run --with coverage --with pytest-cov pytest --cov=. --cov-report=term-missing -q
```
## Релизы
Релиз создается автоматически при `push` в `master` workflow'ом `CI Push`.
Условия для релиза:
- `Tests` завершился успешно.
- `Version Check` завершился успешно (версия в `pyproject.toml` увеличена по правилам `vuh`).
Как формируется релиз:
- версия берется из `vuh lv -q`;
- создается тег формата `v` и GitHub Release;
- если тег уже существует, релиз пропускается.
## VS Code Tasks
В `.vscode/tasks.json` добавлены задачи:
- `docker:stop` - остановить `docker compose` и удалить volume (`docker compose down -v`).
- `docker:start` - поднять локальный стенд в фоне (`docker compose up -d`).
- `docker:restart` - последовательно выполнить `docker:stop` и `docker:start`.
- `uv:sync` - синхронизировать окружение и зависимости (`uv sync`).
- `uv:update` - обновить lock-файл зависимостей (`uv lock --upgrade`).
- `pytest:coverage` - запустить тесты с coverage в терминал.
- `pytest:coverage:html` - запустить тесты с coverage в терминал и HTML-отчет (`htmlcov/`).
- `tox:test` - запустить матрицу `tox` (`tox -p auto`).
- `lint:ruff` - проверить код через `ruff check .`.
- `lint:ruff:fix` - исправить автоисправляемые проблемы `ruff`.
- `lint:pre-commit` - прогнать `pre-commit` по всем файлам.