zndraw-socketio 0.1.0__tar.gz

zndraw_socketio-0.1.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__query-docs",
+      "mcp__github__search_code",
+      "mcp__github__get_file_contents",
+      "Bash(python -m pytest:*)"
+    ]
+  }
+}

zndraw_socketio-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# exclude .gitignore and similar from the generated tarball
+.git*           export-ignore
+# exclude CI configurations
+.github         export-ignore

zndraw_socketio-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish Python 🐍 distributions 📦
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_testpypi:
+        type: boolean
+        default: false
+        description: Publish to TestPyPI
+      publish_pypi:
+        type: boolean
+        default: false
+        description: Publish to PyPI
+      publish_gh_release:
+        type: boolean
+        default: true
+        description: Publish to GitHub Release
+      use_changelog:
+        type: boolean
+        default: true
+        description: Extract release notes from CHANGELOG.md
+      changelog_file:
+        type: string
+        default: CHANGELOG.md
+        description: Path to changelog file
+        required: false
+      release_tag:
+        type: string
+        description: Tag to package (empty for latest tag)
+        required: false
+
+jobs:
+  get-tag:
+    runs-on: ubuntu-latest
+    outputs:
+      release_tag: ${{ steps.set_release_tag.outputs.tag }}
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Fetch all tags
+      run: |
+        git fetch --prune --unshallow --tags
+    - name: Verify and set release tag
+      id: set_release_tag
+      run: |
+        release_tag=${{ inputs.release_tag }}
+        if [ -z "$release_tag" ]; then
+          echo "Input tag is empty. Fetching latest tag."
+          release_tag=$(git describe --tags $(git rev-list --tags --max-count=1))
+          if [ -z "$release_tag" ]; then
+            echo "No latest tag available. Exiting workflow."
+            exit 1
+          fi
+        else
+          if ! git rev-parse -q --verify "refs/tags/$release_tag" >/dev/null; then
+            echo "Invalid tag '$release_tag'. Exiting workflow."
+            exit 1
+          fi
+        fi
+        echo "tag=$release_tag" >> $GITHUB_OUTPUT
+  test:
+    needs: get-tag
+    uses: ./.github/workflows/test.yml
+    with:
+      release_tag: ${{ needs.get-tag.outputs.release_tag }}
+  build-n-publish:
+    needs: test
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing and sigstore
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+    uses: atomiechen/reusable-workflows/.github/workflows/publish-python-distributions.yml@main
+    with:
+      publish_testpypi: ${{ inputs.publish_testpypi }}
+      publish_pypi: ${{ inputs.publish_pypi }}
+      publish_gh_release: ${{ inputs.publish_gh_release }}
+      use_changelog: ${{ inputs.use_changelog }}
+      changelog_file: ${{ inputs.changelog_file }}
+      release_tag: ${{ needs.get-tag.outputs.release_tag }}
+    secrets:
+      TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}

zndraw_socketio-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,72 @@
+name: Test Python Package 🔧
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_call:
+    inputs:
+      release_tag:
+        type: string
+        required: false
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        type: string
+        description: Tag to package (empty for latest commit)
+        required: false
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+        python-version: [
+          "3.10", "3.11", "3.12", "3.13", 
+          # "3.14"
+        ]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Checkout to release tag if provided
+      if: ${{ inputs.release_tag }}
+      run: |
+        echo "Checking out to release tag ${{ inputs.release_tag }}"
+        git fetch --prune --unshallow --tags
+        git checkout ${{ inputs.release_tag }}
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+    - name: Install dependencies (with optional extras)
+      # ref: https://docs.astral.sh/uv/guides/integration/github/#syncing-and-running
+      run: |
+        uv sync --locked --all-extras
+      #   python -m pip install --upgrade pip
+      #   pip install -r requirements.txt
+    - name: Activate venv and store path (Windows)
+      # ref: https://stackoverflow.com/a/74669486/11854304
+      # ref: https://stackoverflow.com/a/72926104/11854304
+      if: runner.os == 'Windows'
+      run: |
+        .venv\Scripts\activate
+        echo PATH=$PATH >> $GITHUB_ENV
+    - name: Activate venv and store path (Linux/Mac)
+      # ref: https://stackoverflow.com/a/74669486/11854304
+      # ref: https://stackoverflow.com/a/72926104/11854304
+      if: runner.os != 'Windows'
+      run: |
+        source .venv/bin/activate
+        echo PATH=$PATH >> $GITHUB_ENV
+    - name: Lint
+      run: |
+        ./scripts/lint.sh
+    - name: Test
+      run: |
+        ./scripts/test.sh

zndraw_socketio-0.1.0/.gitignore

@@ -0,0 +1,168 @@
+# ruff
+.ruff_cache
+
+
+# == Below are commonly ignored files for Python projects == #
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

zndraw_socketio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Atomie CHEN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zndraw_socketio-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: zndraw-socketio
+Version: 0.1.0
+Summary: Typed wrapper for python-socketio with Pydantic validation and dependency injection.
+Project-URL: homepage, https://github.com/pythonFZ/zndraw-socketio
+Project-URL: issues, https://github.com/pythonFZ/zndraw-socketio/issues
+Author-email: Atomie CHEN <atomic_cwh@163.com>, Fabian Zills <fabian.zills@web.de>
+License-File: LICENSE
+Keywords: pydantic,socketio,typed,wrapper,zndraw
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-socketio>=5.12.1
+Requires-Dist: typing-extensions>=4.13.0
+Provides-Extra: asyncio-client
+Requires-Dist: python-socketio[asyncio-client]>=5.12.1; extra == 'asyncio-client'
+Provides-Extra: client
+Requires-Dist: python-socketio[client]>=5.12.1; extra == 'client'
+Description-Content-Type: text/markdown
+
+# zndraw-socketio
+
+Typed wrapper for [python-socketio](https://github.com/miguelgrinberg/python-socketio) with Pydantic validation and dependency injection.
+
+
+## Installation
+
+```sh
+pip install zndraw-socketio
+```
+
+Optional extras for client transports:
+
+```sh
+pip install zndraw-socketio[client]
+pip install zndraw-socketio[asyncio-client]
+```
+
+
+## Usage
+
+### Wrap any socketio instance
+
+```python
+import socketio
+from pydantic import BaseModel
+from zndraw_socketio import wrap
+
+class Ping(BaseModel):
+    message: str
+
+class Pong(BaseModel):
+    reply: str
+
+# Wrap any existing socketio instance
+tsio = wrap(socketio.AsyncClient())
+
+# Emit with automatic event name derivation (Ping -> "ping")
+await tsio.emit(Ping(message="Hello, World!"))
+
+# Emit with explicit event name
+await tsio.emit("my-ping", Ping(message="Hello, World!"))
+
+# Call with typed response
+response = await tsio.call(Ping(message="Hello"), response_model=Pong)
+# response is typed as Pong
+```
+
+### Handler registration with validation
+
+```python
+# Event name derived from model class (Ping -> "ping")
+@tsio.on(Ping)
+async def handle_ping(data: Ping) -> Pong:
+    return Pong(reply=data.message)
+
+# Or use function name as event name
+@tsio.event
+async def ping(data: Ping) -> Pong:
+    return Pong(reply=data.message)
+```
+
+### Union response types
+
+```python
+from typing import Annotated, Literal
+from pydantic import BaseModel, Discriminator
+
+class Success(BaseModel):
+    kind: Literal["success"] = "success"
+    data: str
+
+class Error(BaseModel):
+    kind: Literal["error"] = "error"
+    message: str
+
+# Simple union
+response = await tsio.call(request, response_model=Success | Error)
+
+# Discriminated union
+ResponseType = Annotated[Success | Error, Discriminator("kind")]
+response = await tsio.call(request, response_model=ResponseType)
+```
+
+### Custom event names
+
+```python
+from typing import ClassVar
+
+class CustomEvent(BaseModel):
+    event_name: ClassVar[str] = "my_custom_event"
+    data: str
+
+# Uses "my_custom_event" instead of "custom_event"
+await tsio.emit(CustomEvent(data="hello"))
+```
+
+### Exception handlers
+
+```python
+from zndraw_socketio import wrap, EventContext
+
+tsio = wrap(socketio.AsyncServer(async_mode="asgi"))
+
+@tsio.exception_handler(ValueError)
+async def handle_value_error(ctx: EventContext, exc: ValueError):
+    return {"error": "value_error", "message": str(exc)}
+
+# Namespace-specific
+@tsio.exception_handler(ValueError, namespace="/chat")
+async def handle_chat_error(ctx: EventContext, exc: ValueError):
+    return {"error": "chat_error", "message": str(exc)}
+```
+
+### Dependency injection
+
+```python
+from typing import Annotated
+from fastapi import Depends
+from zndraw_socketio import wrap
+
+async def get_redis():
+    return my_redis_pool
+
+RedisDep = Annotated[AsyncRedis, Depends(get_redis)]
+
+tsio = wrap(socketio.AsyncServer(async_mode="asgi"))
+
+@tsio.on(RoomLeave)
+async def room_leave(sid: str, data: RoomLeave, redis: RedisDep) -> RoomLeaveResponse:
+    await redis.delete(f"presence:{data.room_id}:{sid}")
+    return RoomLeaveResponse(status="ok")
+```
+
+When FastAPI is not installed, import `Depends` from `zndraw_socketio`:
+
+```python
+from zndraw_socketio import Depends
+```
+
+### FastAPI integration
+
+```python
+import socketio
+from typing import Annotated
+from fastapi import FastAPI, Depends
+from zndraw_socketio import wrap, AsyncServerWrapper
+
+app = FastAPI()
+tsio = wrap(socketio.AsyncServer(async_mode="asgi"))
+
+SioServer = Annotated[AsyncServerWrapper, Depends(tsio)]
+
+@app.post("/notify")
+async def notify(server: SioServer):
+    await server.emit("notification", {"msg": "hello"})
+    return {"status": "sent"}
+
+combined_app = socketio.ASGIApp(tsio, app)
+```
+
+### SimpleClient support
+
+```python
+tsio = wrap(socketio.SimpleClient())
+tsio.connect("http://localhost:5000")
+
+tsio.emit(Ping(message="Hello"))
+response = tsio.call(Ping(message="Hello"), response_model=Pong)
+event_name, data = tsio.receive(response_model=Pong)
+tsio.disconnect()
+```
+
+## Supported socketio types
+
+`wrap()` auto-detects the socketio instance type:
+
+| socketio type | Wrapper class |
+|---|---|
+| `AsyncClient` | `AsyncClientWrapper` |
+| `AsyncServer` | `AsyncServerWrapper` |
+| `Client` | `SyncClientWrapper` |
+| `Server` | `SyncServerWrapper` |
+| `SimpleClient` | `SimpleClientWrapper` |
+| `AsyncSimpleClient` | `AsyncSimpleClientWrapper` |
+
+
+## License
+
+MIT License