neonize - Moses Yebei

The Problem

Automating WhatsApp interactions from Python requires bridging a high‑performance Go backend (Whatsmeow) with a Python‑friendly API. Existing solutions either expose raw Go bindings, which are cumbersome for Python developers, or provide thin wrappers that lack async support and robust media handling. Teams need a single library that hides the Go complexity while offering a clean, async‑first interface for sending, receiving, and managing messages, groups, and media.

What This Does

neonize/ implements the public Python API. Core client logic lives in neonize/aioze/client.py (132 functions, 5 classes) and neonize/client.py (126 functions, 4 classes). Media utilities such as neonize/utils/ffmpeg.py and neonize/utils/sticker.py wrap external tools for conversion. The Go side (goneonize/) contains the compiled protobuf definitions and a thin wrapper (goneonize/main.go) that builds the Go binary used by the Python extension. Helper scripts in tools/ (e.g., tools/goneonize.py, tools/version.py) automate proto generation and version bumps.

How It Is Wired

Execution starts from the Python examples (e.g., examples/async_basic.py). The script imports neonize.client.NewClient, which instantiates neonize/aioze/client.Client. During initialization the client loads the compiled Go library (built from goneonize/Neonize.proto via goneonize/build_python_proto.py).

Key call chain for sending a message:

handler (examples/async_basic.py:56) → neonize/aioze/client.send_message (called 13 times).
send_message → neonize/aioze/client.get_bytes / free_bytes (both invoked from 51 places, the widest blast radius).
get_bytes reads a file or URL via neonize/utils/iofile.get_bytes_from_name_or_url (network I/O).
The byte payload is passed to the Go layer (neonize/aioze/client.call) which ultimately invokes the Whatsmeow‑backed RPC to deliver the message.

Media paths add a filesystem hop: handler → build_sticker_message → neonize/utils/sticker.convert_to_sticker → external ffmpeg command (neonize/utils/ffmpeg.py).

The most connected modules are neonize/aioze/client (21 outgoing imports, part of a circular dependency) and neonize/client (19 outgoing imports, also in a cycle). These cycles inflate the cognitive load when refactoring because changes ripple through both modules.

File‑level responsibilities (selected):

File	Primary Role	External Effect
`neonize/aioze/client.py`	Async client core, request routing	Calls external commands, reads/writes files
`neonize/utils/ffmpeg.py`	Media conversion wrapper	Executes `ffmpeg`, writes temporary files
`neonize/utils/iofile.py`	Unified byte‑source loader	Performs network fetches
`tools/goneonize.py`	Proto generation & Go build orchestration	Runs `protoc`, writes compiled Go files
`goneonize/main.go`	Go entry point (binary)	Provides low‑level WhatsApp RPCs

Because the import graph shows 4 modules in circular dependencies, any change to shared types (e.g., neonize/types) must consider both sides of the cycle to avoid import errors.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/neonize
cd neonize

# Install Python dependencies (uses the pyproject.toml)
pip install -e .        # editable install pulls in all required packages

# Build the Go protobuf layer (requires Go 1.19+)
cd goneonize
go run build_python_proto.py   # generates the Go bindings used by the Python package

Run an example to verify the stack:

python ../examples/async_basic.py

The example creates a NewClient, registers event callbacks, and calls handler which ultimately invokes send_message as described above.

Real‑World Use

A support desk could embed the library in a Flask service that receives HTTP tickets, creates a NewClient, and forwards the ticket text as a WhatsApp message:

from neonize.client import NewClient

client = NewClient("my_bot")
client.send_message(to_jid="12345@s.whatsapp.net", text=ticket.body)

The call traverses the same async client → byte loader → Go RPC path, guaranteeing that media handling and encryption are performed by the underlying Whatsmeow backend.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to commit SHA (.github/workflows/*).
HIGH – No test suite present (109 source files, 0 test files).
HIGH – Missing Python lockfile beside pyproject.toml.
HIGH – continue-on-error on correctness step in release.yml.
MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions (autobump.yml).
MEDIUM – Enable Dependabot or Renovate for automated updates.
MEDIUM – Add a dependency‑vulnerability scan step in CI.
MEDIUM – Set persist-credentials: false on checkout (autobump.yml).
LOW – Add timeout-minutes to workflow jobs.
LOW – Add repository convention files (.editorconfig, formatter config, etc.).

Additional static findings: oversized files (neonize/aioze/client.py, neonize/client.py, neonize/utils/ffmpeg.py), broad exception handling, deep nesting, an import cycle involving neonize/aioze/client.py and neonize/events.py, and duplicated example code blocks.

The Bottom Line

Neonize delivers a functional Python wrapper around a performant Go WhatsApp core, with clear async APIs and media utilities. However, the codebase suffers from high cognitive load, circular imports, and a lack of automated testing and dependency lockfiles. It is suitable for teams comfortable navigating a mixed Python/Go stack and willing to invest in refactoring and test coverage before production use.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

278 files

Python105
Protocol Buffers56
Markdown23
Go9
YAML8
C/C++ Header2

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["neonize<br/>88 modules"] g1["tools<br/>10 modules"] g2["examples<br/>6 modules"] g2 -->|32| g0

Module dependencies

The 10 most depended-upon modules of 105, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0__waE2E_WAWebProtobufsE2E_pb2["WAWebProtobufsE2E_pb2"] n1_neonize_utils___init__["__init__"] n2_neonize_utils_enum["enum"] n3_neonize_types["types"] n4_neonize_utils_iofile["iofile"] n5_neonize_proto_Neonize_pb2["Neonize_pb2"] n6_neonize_aioze_client["client"] n7_neonize_events["events"] n8_neonize_utils_ffmpeg["ffmpeg"] n9_neonize_client["client"] n6_neonize_aioze_client --> n5_neonize_proto_Neonize_pb2 n6_neonize_aioze_client --> n0__waE2E_WAWebProtobufsE2E_pb2 n6_neonize_aioze_client --> n3_neonize_types n6_neonize_aioze_client --> n1_neonize_utils___init__ n6_neonize_aioze_client --> n2_neonize_utils_enum n6_neonize_aioze_client --> n8_neonize_utils_ffmpeg n6_neonize_aioze_client --> n4_neonize_utils_iofile n9_neonize_client --> n7_neonize_events n9_neonize_client --> n5_neonize_proto_Neonize_pb2 n9_neonize_client --> n0__waE2E_WAWebProtobufsE2E_pb2 n9_neonize_client --> n3_neonize_types n9_neonize_client --> n1_neonize_utils___init__ n9_neonize_client --> n2_neonize_utils_enum n9_neonize_client --> n8_neonize_utils_ffmpeg n9_neonize_client --> n4_neonize_utils_iofile n7_neonize_events --> n5_neonize_proto_Neonize_pb2 n7_neonize_events --> n9_neonize_client n3_neonize_types --> n0__waE2E_WAWebProtobufsE2E_pb2 classDef cyc stroke:#ef4444,stroke-width:2px; class n6_neonize_aioze_client,n7_neonize_events,n9_neonize_client cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium4

low2

Pin third-party GitHub Actions to a commit SHAhigh9 occurrences

.github/workflows

arduino/setup-protoc@v3, astral-sh/setup-uv@v5, astral-sh/ruff-action@v3, golangci/golangci-lint-action@v8

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a test suite; this repository has nonehigh109 occurrences

109 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/release.yml

line 94 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/autobump.yml

2 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/autobump.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/autobump.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.