diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..337a2ec --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,37 @@ +name: Publish to PyPI + +on: + workflow_run: + workflows: ["CI"] + types: [completed] + branches: [master] + +jobs: + build-and-publish: + name: Build and publish to PyPI + runs-on: ubuntu-latest + permissions: + id-token: write + steps: + - name: Checkout repo + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install uv + uses: astral-sh/setup-uv@v3 + + - name: Install build and publish tools + run: uv pip install --system hatchling twine + + - name: Build package + run: uv run hatchling build + + - name: Publish package to PyPI + run: uv run twine upload dist/* --verbose + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} diff --git a/.gitignore b/.gitignore index 1a1c1e4..1c51e0c 100644 --- a/.gitignore +++ b/.gitignore @@ -174,3 +174,4 @@ poetry.toml pyrightconfig.json # End of https://www.toptal.com/developers/gitignore/api/python +*.lock diff --git a/README.md b/README.md new file mode 100644 index 0000000..3acf72e --- /dev/null +++ b/README.md @@ -0,0 +1,99 @@ +# Bridge + +[![CI](https://github.com/KN-Neuron/Bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/KN-Neuron/Bridge/actions/workflows/ci.yml) +[![PyPI version](https://badge.fury.io/py/neuron-bridge.svg)](https://badge.fury.io/py/neuron-bridge) +[![Python Version](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/) +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/) + +**Wersja: 0.1.0** + +**Bridge** to biblioteka (SDK) i aplikacja wiersza poleceń w Pythonie, która tworzy ujednolicony interfejs do zbierania danych z różnych urządzeń EEG. Działa jako "most" między sprzętem a oprogramowaniem analitycznym. + +## Główne Cechy + +- **Architektura Pluginów**: Łatwe dodawanie wsparcia dla nowych urządzeń. +- **Podwójne Zastosowanie**: Działa jako biblioteka Pythona (SDK) lub samodzielny serwer WebSocket. +- **Ujednolicone API**: Zapewnia jeden, spójny sposób komunikacji z każdym wspieranym urządzeniem. + +## Instalacja + +**Wymagania:** Python 3.11 + +1. **Instalacja biblioteki:** + ```bash + # Podstawowe użycie jako SDK + pip install neuron-bridge + + # Instalacja z funkcjonalnością serwera + pip install "neuron-bridge[server]" + ``` + +2. **Instalacja sterowników urządzenia:** + Biblioteka nie zawiera zastrzeżonych SDK producentów – należy je zainstalować manualnie. + - **BrainAccess:** [Strona producenta](https://www.brainaccess.ai/download/). + +## Szybki Start + +### Użycie jako Serwer + +Serwer WebSocket automatycznie łączy się z pierwszym dostępnym urządzeniem EEG. + +```bash +bridge-server --host localhost --port 50050 +``` +Klienty mogą łączyć się z `ws://localhost:50050` i wysyłać żądania w formacie JSON (`{"request": "get_device_info"}`). + +### Użycie jako Biblioteka (SDK) + +Klasa `EEGConnector` to główny punkt wejścia do interakcji z urządzeniem. + +```python +from bridge.eeg import EEGConnector, init, close + +# Inicjalizacja sterowników +init() + +try: + with EEGConnector() as device: + info = device.get_device_data() + print(f"Połączono z: {info.name}") + + # Akwizycja 5 sekund danych + eeg_data = device.get_output(duration=5.0) + print(f"Pobrano dane o kształcie: {eeg_data.shape}") + +except RuntimeError as e: + print(f"Błąd: {e}") + +finally: + # Zwolnienie zasobów + close() +``` + +## Rozwój Projektu + +### Konfiguracja Środowiska + +1. **Sklonuj repozytorium:** `git clone https://github.com/KN-Neuron/Bridge.git` +2. **Stwórz i aktywuj środowisko:** `python -m venv .venv && source .venv/bin/activate` +3. **Zainstaluj zależności:** `pip install -e ".[dev]"` +4. **Zainstaluj hooki pre-commit:** `pre-commit install` (jednorazowo) + +### Proces Pracy + +Projekt wykorzystuje `pre-commit` do automatyzacji sprawdzania i formatowania kodu. + +1. Wprowadź zmiany w kodzie. +2. Dodaj pliki do commita: `git add .` +3. Wykonaj commit: `git commit -m "Opis zmian"` + - Narzędzia (`ruff`, `black`, `mypy`, `pytest`) uruchomią się automatycznie. + - Jeśli kod zostanie automatycznie sformatowany, commit zostanie przerwany. To celowe – przejrzyj zmiany, dodaj je ponownie (`git add .`) i ponów commit. + +### Dodawanie Nowego Urządzenia + +1. **Stwórz nowy moduł** w `bridge/eeg/`. +2. **Zaimplementuj klasę** dziedziczącą po `EEGDevice`. +3. **Zarejestruj ją** w `bridge/eeg/config.py`. +4. **Dodaj testy** w katalogu `tests/`. diff --git a/pyproject.toml b/pyproject.toml index 1a90083..0f25212 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,13 +9,13 @@ packages = [ [project] name = "neuron-bridge" -version = "0.1.0" +version = "0.2.0" authors = [ { name = "mateusz-kow", email = "kowalski.mateusz.1lo1@gmail.com" }, ] description = "A versatile bridge application and SDK for connecting with EEG devices." readme = "README.md" -requires-python = "~=3.11" +requires-python = ">=3.11.0, <3.12" classifiers = [ "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.11", @@ -26,7 +26,7 @@ classifiers = [ "Topic :: Scientific/Engineering", ] dependencies = [ - "numpy<2.0.0", + "numpy~=1.26.4", ] [project.optional-dependencies] @@ -35,23 +35,23 @@ server = [ ] dev = [ "websockets~=12.0", - "pandas", - "mne~=1.6.0", - "matplotlib", - "black", - "ruff", - "pytest", - "pytest-asyncio", - "pytest-mock", - "mypy", - "hatch", - "twine", - "pre-commit", + "pandas~=2.3.2", + "mne~=1.6.1", + "matplotlib~=3.10.6", + "black~=25.1.0", + "ruff~=0.13.0", + "pytest~=8.4.2", + "pytest-asyncio~=1.2.0", + "pytest-mock~=3.15.0", + "mypy~=1.18.1", + "hatchling~=1.27.0", + "twine~=6.2.0", + "pre-commit~=4.2.0", ] [project.urls] -Homepage = "https://github.com/mateusz-kow/bridge" -Issues = "https://github.com/mateusz-kow/bridge/issues" +Homepage = "https://github.com/KN-Neuron/Bridge" +Issues = "https://github.com/KN-Neuron/Bridge/issues" [project.scripts] bridge-server = "server.cli:run_server_cli"