The Problem
WhatsApp automation traditionally requires navigating the Whatsmeow Go library's complex protobuf definitions and event system. Developers building Python-based WhatsApp bots face a choice: use Whatsmeow directly through awkward bridging, or accept limited, often abandoned Python wrappers that lack enterprise features like media handling, group management, and real-time event support.
What This Does
Neonize bridges this gap with a dual-layer architecture. The goneonize/ directory (72 files) contains the Go implementation built on Whatsmeow, handling protobuf parsing, connection management, and WhatsApp protocol interactions across 56 proto definition files. The neonize/ Python package (83 files) provides the user-facing API, generating protobuf Python stubs from the Go definitions (goneonize/defproto/ contains 56 .proto files). Key entry points include goneonize/main.go and neonize/client.py, with Python protobuf modules located at neonize/proto/ generating from goneonize/defproto/Neonize.proto. The project uses GitHub Actions CI/CD (6 workflow files) and maintains goneonize/go.mod/go.sum for dependency management.
How To Use It
Setup: Install via pip install neonize. The Go backend requires Go 1.19+; the Python package depends on the compiled Go shared library. Configuration requires no environment variables in the basic setup, but production deployments should configure the Go client instance per docs/getting-started/installation.md.
Configuration: The neonize/client.py NewClient() constructor accepts a session name. Persistent sessions store state locally; re-running with the same name resumes an existing session. No API keys or secrets are required for basic operation—the library uses WhatsApp's web session model.
Running it: The primary entry point is goneonize/main.go, but Python users invoke the library through neonize/client.py. Example workflow from the README:
from neonize.client import NewClient from neonize.events import MessageEv, ConnectedEv, event
client = NewClient("mybot")
@client.event def onconnected(client: NewClient, event: ConnectedEv): print("Bot connected successfully")
@client.event def onmessage(client: NewClient, event: MessageEv): print(f"Received: {event.message}")
client.run()
Real-World Use
A practical scenario: a Python service needs to process incoming WhatsApp media messages, validate documents against business rules, and route them to internal systems. Neonize's event-driven architecture handles this via neonize/events.py with onmessage hooks. The library supports media attachment handling through protobuf-defined message types across goneonize/defproto/ folders (e.g., waMediaEntryData, waMediaTransport). For async operation, examples/asyncbasic.py and examples/asynconeshot.py demonstrate non-blocking message processing using aioze/client.py. Group operations leverage goneonize/chatsettingsstore.go and goneonize/contact_store.go for state management. The SQLite/PostgreSQL database support mentioned in docs enables persistent message history without external services.
Code Health & Issues
Tests: 1 test file found—limited coverage. The repository has CI configured (6 GitHub Actions workflows), but test density is low. License: Apache 2.0 present in root—compliant. Dependency hygiene: goneonize/go.mod/go.sum exist with version-pinned modules; Python dependencies are minimal (the package is installable via pip with no requirements.txt visible at root). Structural separation: Clear Go/Python boundary, but the auto-generated protobuf stubs (neonize/proto/) are committed to the repo rather than generated at build time, creating merge friction when proto definitions change. Documentation: 24 doc files cover getting started, user guides, and API references—adequate for onboarding but sparse on advanced protocol details.
High: Dual-language architecture (Go + Python) with real protobuf definitions.
Med: Sparse test coverage; generated stubs committed to repo.
Low: No apparent secrets or config in the repo; build pipeline is functional.
The Bottom Line
Neonize delivers a functional Python abstraction over Whatsmeow's Go foundation. It works for bot workflows that need media handling, group management, and real-time events without writing Go. The trade-off: teams requiring deep protocol customization or maximum performance should engage with the Go layer directly; Python users get productivity at the cost of some flexibility. Best suited for Python teams building WhatsApp bots that need enterprise features without maintaining Go expertise.