### Development Setup Commands

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Common shell commands for cloning, installing dependencies, and running tests or examples.

```bash
# Clone the repository
git clone https://github.com/krypton-byte/neonize.git
cd neonize

# Install dependencies with Poetry
poetry install --with dev

# Or install with pip in development mode
pip install -e .

# Run the basic example
python examples/basic.py

# Run tests
python -m pytest

# Build documentation
cd docs && make html
```

--------------------------------

### Basic Neonize Bot Setup

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Initialize a Neonize client, define event handlers for connection and messages, and start the bot. This example shows how to connect and reply to a 'hi' message.

```python
from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event

# Initialize client
client = NewClient("your_bot_name")

@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("🎉 Bot connected successfully!")

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    if event.message.conversation == "hi":
        client.reply_message("Hello! 👋", event.message)

# Start the bot
client.connect()
event.wait()  # Keep running
```

--------------------------------

### Initialize and Run a Basic WhatsApp Bot

Source: https://github.com/krypton-byte/neonize/blob/master/docs/index.md

This example demonstrates how to initialize the Neonize client, set up event handlers for connection and messages, and start the bot. It requires importing necessary classes from neonize.client and neonize.events.

```python
from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event

# Initialize client
client = NewClient("my_bot")

@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("🎉 Bot connected successfully!")

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    if event.message.conversation == "hi":
        client.reply_message("Hello! 👋", event.message)

# Start the bot
client.connect()
event.wait()
```

--------------------------------

### Basic Client Setup (Python)

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/index.md

This is the basic synchronous client setup. Ensure you have connected the client and are waiting for events.

```python
from neonize.client import NewClient
from neonize.events import event

client = NewClient("my_bot")
client.connect()
event.wait()
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Install the necessary dependencies for building documentation using pip or uv.

```bash
pip install -e ".[docs]"
```

```bash
uv sync --group docs
```

--------------------------------

### Async Client Setup (Python)

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/index.md

This is the asynchronous client setup. It's recommended for high-throughput applications. Register event handlers before connecting.

```python
import asyncio
from neonize.aioze.client import NewAClient

client = NewAClient("async_bot")

# register event handlers on client.event here...

async def main():
    await client.connect()  # captures the running event loop
    await client.idle()     # keeps the bot alive

asyncio.run(main())  # ✅ standard entry point
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Start a local development server to preview documentation changes.

```bash
task docs-serve
```

```bash
mkdocs serve
```

--------------------------------

### Install Neonize from Local Wheel

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install the Neonize package from a locally built wheel file.

```bash
pip install dist/neonize-*.whl
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/index.md

Starts a local server to preview documentation changes.

```bash
task docs-serve
```

--------------------------------

### Development Install with Extras

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install Neonize in editable mode with both development and documentation extras.

```bash
pip install -e ".[dev,docs]"
```

--------------------------------

### Initialize and use the Async Client

Source: https://github.com/krypton-byte/neonize/blob/master/docs/async/index.md

Demonstrates basic client setup, event registration for connections and messages, and the standard asyncio entry point.

```python
import asyncio
from neonize.aioze.client import NewAClient
from neonize.aioze.events import MessageEv, ConnectedEv

client = NewAClient("async_bot")

@client.event(ConnectedEv)
async def on_connected(client: NewAClient, event: ConnectedEv):
    print("✅ Connected!")

@client.event(MessageEv)
async def on_message(client: NewAClient, event: MessageEv):
    text = event.Message.conversation
    if text == "ping":
        await client.reply_message("pong!", event)

async def main():
    await client.connect()   # captures the running event loop internally
    await client.idle()       # keeps the client alive

asyncio.run(main())          # ← standard entry point
```

--------------------------------

### Install Neonize using uv

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install Neonize using the uv package manager.

```bash
uv add neonize
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/index.md

Sets up the project environment using either uv or pip.

```bash
uv sync --all-extras
```

```bash
pip install -e ".[dev,docs]"
```

--------------------------------

### Install PostgreSQL Driver (Binary)

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install the psycopg2-binary package for PostgreSQL support.

```bash
pip install psycopg2-binary
```

--------------------------------

### Development Installation

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install Neonize with development dependencies by cloning the repository and using pip.

```bash
git clone https://github.com/krypton-byte/neonize.git
cd neonize
pip install -e ".[dev]"
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/krypton-byte/neonize/blob/master/DOCUMENTATION_SETUP.md

Install the project and its documentation-specific dependencies using pip. This command ensures all necessary packages for development and documentation are available.

```bash
pip install -e ".[docs]"
```

--------------------------------

### Verify Neonize Installation

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Confirm that Neonize has been installed correctly by importing it and printing its version.

```python
import neonize
print(neonize.__version__)
```

--------------------------------

### Install Neonize using pip

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

The recommended method for installing Neonize is using pip.

```bash
pip install neonize
```

--------------------------------

### Verify Neonize Installation

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/index.md

Checks that the package is correctly installed by printing the version.

```bash
python -c "import neonize; print(neonize.__version__)"
```

--------------------------------

### Install FFmpeg on macOS

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install FFmpeg on macOS using Homebrew.

```bash
brew install ffmpeg
```

--------------------------------

### Check FFmpeg Installation

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Verify that FFmpeg is installed and accessible in your system's PATH.

```bash
ffmpeg -version
```

--------------------------------

### Use asyncio.run as the entry point

Source: https://github.com/krypton-byte/neonize/blob/master/docs/async/index.md

The recommended pattern for starting the event loop in Python 3.7+.

```python
# ✅ Always use asyncio.run() as the entry point
asyncio.run(main())
```

--------------------------------

### Clone the Repository

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/contributing.md

Initial setup steps for local development after forking the project on GitHub.

```bash
# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/neonize.git
cd neonize
```

--------------------------------

### Install FFmpeg on Ubuntu/Debian

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install FFmpeg on Ubuntu or Debian-based systems for media processing.

```bash
sudo apt update
sudo apt install ffmpeg
```

--------------------------------

### Initialize WhatsApp Client in Python

Source: https://context7.com/krypton-byte/neonize/llms.txt

Basic setup for connecting a new client instance to the WhatsApp network.

```python
from neonize.client import NewClient
from neonize.utils import build_jid

client = NewClient("my_bot")
client.connect()
```

--------------------------------

### Install PostgreSQL Driver (Production)

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install the psycopg2 package for PostgreSQL support in production environments.

```bash
pip install psycopg2
```

--------------------------------

### Verify Neonize Installation and Basic Functionality

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Verify the Neonize installation by importing the library, printing its version, and creating a client instance. This confirms the build was successful.

```python
import neonize
print(neonize.__version__)

# Test basic functionality
from neonize.client import NewClient
client = NewClient("test")
print("✅ Build successful!")
```

--------------------------------

### Install Neonize with User Flag

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install Neonize using the `--user` flag to avoid permission denied errors.

```bash
pip install --user neonize
```

--------------------------------

### Install libmagic on macOS

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install libmagic on macOS using Homebrew.

```bash
brew install libmagic
```

--------------------------------

### Follow testing best practices

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/testing.md

Examples of naming conventions, scope management, and resource cleanup.

```python
# Good
def test_send_message_returns_message_id():
    pass

# Bad
def test_1():
    pass
```

```python
# Good - tests one behavior
def test_client_connects_successfully():
    client = NewClient("test")
    assert client.is_connected is False

# Bad - tests multiple behaviors
def test_everything():
    client = NewClient("test")
    assert client.is_connected
    client.send_message(...)
    client.disconnect()
    # Too much in one test
```

```python
@pytest.fixture
def authenticated_client():
    """Provide an authenticated client for tests."""
    client = NewClient("test", database=":memory:")
    # Setup authentication
    yield client
    # Cleanup
    client.logout()
```

```python
def test_with_cleanup():
    client = NewClient("test")
    try:
        # Test code
        assert client is not None
    finally:
        # Always cleanup
        client.disconnect()
```

--------------------------------

### Start and Maintain Connection

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

Establishes the connection and keeps the process alive.

```python
client.connect()
event.wait()
```

--------------------------------

### Install Neonize via Package Managers

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/index.md

Commands to install the Neonize library using common Python package managers.

```bash
pip install neonize
```

```bash
uv add neonize
```

```bash
poetry add neonize
```

--------------------------------

### Install Python Dependencies with uv

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install all project dependencies, including development and extra features, using the uv package manager.

```bash
uv sync --all-extras
```

--------------------------------

### Development Install (Editable)

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install Neonize in editable mode for active development. Changes to the source code will be reflected immediately without reinstallation.

```bash
pip install -e .
```

--------------------------------

### Basic Synchronous Client Setup

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Initializes a synchronous WhatsApp client with basic logging and connection event handling. Stores client data in a specified database file.

```python
from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event
import logging

# Enable logging for debugging
logging.basicConfig(level=logging.INFO)

# Initialize the WhatsApp client
client = NewClient(
    name="my-whatsapp-bot",
    database="./neonize.db"
)

# Handle successful connection
@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("🎉 Successfully connected to WhatsApp!")
    print(f"📱 Device: {event.device}")

# Start the client
client.connect()
event.wait()
```

--------------------------------

### Install libmagic on Linux

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Install the libmagic1 library on Ubuntu/Debian or file-libs on Fedora/RHEL for Linux systems.

```bash
# Ubuntu/Debian
sudo apt install libmagic1

# Fedora/RHEL
sudo dnf install file-libs
```

--------------------------------

### Install C Compiler on macOS

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install the Xcode command-line tools, which include a C compiler (like Clang), on macOS.

```bash
xcode-select --install
```

--------------------------------

### Install C Compiler on Ubuntu/Debian

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install the necessary build-essential package, which includes GCC and other C development tools, on Ubuntu or Debian-based systems.

```bash
sudo apt install build-essential
```

--------------------------------

### Install Python Dependencies with pip

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install project dependencies in editable mode with development extras using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Async Client Setup and Event Handling

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Sets up an asynchronous WhatsApp client using NewAClient and defines an event handler for incoming messages. Requires Python 3.10+ for the asyncio event loop.

```python
import asyncio
from neonize.aioze.client import NewAClient
from neonize.aioze.events import MessageEv, ConnectedEv

client = NewAClient("async_bot")

@client.event(MessageEv)
async def on_message(client: NewAClient, event: MessageEv):
    if event.Message.conversation == "ping":
        await client.reply_message("pong! 🏓", event)

async def main():
    await client.connect()
    await client.idle()  # Keep receiving events

asyncio.run(main())
```

--------------------------------

### Install Neonize using Poetry

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Add Neonize to your project if you are using Poetry for dependency management.

```bash
poetry add neonize
```

--------------------------------

### Create an Asynchronous WhatsApp Bot

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

An example using async/await syntax for non-blocking operations.

```python
import asyncio
from neonize.aioze.client import NewAClient
from neonize.aioze.events import MessageEv, ConnectedEv

client = NewAClient("async_bot")

@client.event(ConnectedEv)
async def on_connected(client: NewAClient, event: ConnectedEv):
    print("✅ Async bot connected!")

@client.event(MessageEv)
async def on_message(client: NewAClient, event: MessageEv):
    text = event.Message.conversation
    if text == "ping":
        await client.reply_message("pong! 🏓", event)

async def main():
    await client.connect()
    await client.idle()  # Keep receiving events

asyncio.run(main())
```

--------------------------------

### GitHub Actions Workflow for Building Neonize

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

An example GitHub Actions workflow that checks out the code, sets up Python and Go environments, and builds the Neonize distribution packages.

```yaml
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - uses: actions/setup-go@v4
        with:
          go-version: '1.20'
      - name: Build
        run: |
          pip install build
          python -m build
```

--------------------------------

### Configure Logging

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Setup standard library logging or custom handlers for debugging and monitoring.

```python
import logging

# Set logging level
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

from neonize.client import NewClient

client = NewClient("debug_bot")
```

```python
import logging

# Create custom logger
logger = logging.getLogger('neonize')
logger.setLevel(logging.INFO)

# Add file handler
fh = logging.FileHandler('whatsapp.log')
fh.setLevel(logging.INFO)

# Add console handler
ch = logging.StreamHandler()
ch.setLevel(logging.WARNING)

# Create formatter
formatter = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
fh.setFormatter(formatter)
ch.setFormatter(formatter)

# Add handlers
logger.addHandler(fh)
logger.addHandler(ch)
```

--------------------------------

### Register Event Handler

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

Example of using the decorator to handle connection events.

```python
@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("✅ Bot connected successfully!")
```

--------------------------------

### Dockerfile for Neonize Build Environment

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

A Dockerfile to set up an environment for building Neonize, including Python, Go, and Git. It clones the repository and installs the package in editable mode.

```dockerfile
FROM python:3.11-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    golang-go \
    git \
    && rm -rf /var/lib/apt/lists/*

# Clone and build
WORKDIR /app
COPY . .
RUN pip install -e .

CMD ["python"]
```

--------------------------------

### QR Code Authentication

Source: https://context7.com/krypton-byte/neonize/llms.txt

Authenticate your WhatsApp client by scanning a QR code. This example demonstrates how to handle the QR code data, display it in the terminal, or save it to a file using the segno library.

```python
import segno
from neonize.client import NewClient
from neonize.events import ConnectedEv, event

client = NewClient("my_bot")

@client.event(ConnectedEv)
def on_connected(client: NewClient, evt: ConnectedEv):
    print("Successfully authenticated!")

# Custom QR code handler
@client.qr
def on_qr_code(client: NewClient, qr_data: bytes):
    print("Scan this QR code with your WhatsApp:")

    # Display QR code in terminal
    segno.make_qr(qr_data).terminal(compact=True)

    # Or save to file
    segno.make_qr(qr_data).save("qr_code.png", scale=10)
    print("QR code saved to qr_code.png")

client.connect()
event.wait()
```

--------------------------------

### Create a Synchronous WhatsApp Bot

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

A complete example of a synchronous bot that responds to 'ping' and 'hello' messages.

```python
from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event

# Initialize the client
client = NewClient("my_first_bot")

@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("✅ Bot connected successfully!")
    print(f"📱 Logged in as: {event.device.User}")

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    # Get message text
    text = event.Message.conversation or event.Message.extendedTextMessage.text
    
    # Respond to specific messages
    if text == "ping":
        client.reply_message("pong! 🏓", event)
    elif text == "hello":
        client.reply_message("Hello! 👋 How can I help you?", event)

# Connect and start the bot
client.connect()
event.wait()  # Keep the bot running
```

--------------------------------

### Create a Command Bot with Neonize

Source: https://github.com/krypton-byte/neonize/blob/master/docs/examples/index.md

A bot that parses messages starting with '/' to execute specific commands.

```python
from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event

client = NewClient("command_bot")

@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print(f"✅ Bot connected as {event.device.User}")

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    text = event.Message.conversation or ""
    
    if text.startswith("/"):
        command = text.split()[0][1:]  # Remove /
        
        if command == "help":
            help_text = """
Available commands:
/help - Show this help
/ping - Pong!
/time - Current time
/info - Bot information
            """
            client.reply_message(help_text, event)
        
        elif command == "ping":
            client.reply_message("Pong! 🏓", event)
        
        elif command == "time":
            from datetime import datetime
            now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
            client.reply_message(f"🕐 {now}", event)
        
        elif command == "info":
            info = f"Bot: Neonize Command Bot\nVersion: 1.0"
            client.reply_message(info, event)

client.connect()
event.wait()
```

--------------------------------

### Taskipy Commands for Documentation

Source: https://github.com/krypton-byte/neonize/blob/master/DOCUMENTATION_SETUP.md

These commands manage the documentation build and deployment process. Ensure Taskipy is installed and configured in pyproject.toml.

```bash
# Start development server with live reload
task docs-serve
```

```bash
# Build documentation to site/ directory
task docs-build
```

```bash
# Deploy documentation to GitHub Pages
task docs-deploy
```

```bash
# Clean built documentation
task docs-clean
```

```bash
# Build docs with strict validation
task docs-validate
```

--------------------------------

### Manual Deployment Steps

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Steps for manually building and uploading documentation.

```bash
# Build
mkdocs build

# Upload site/ directory to your hosting
```

--------------------------------

### Markdown Code Example

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Example of a fenced code block for Python code.

```markdown
```python
from neonize.client import NewClient

client = NewClient("my_bot")
```
```

--------------------------------

### Initialize and Use Neonize Client

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/client.md

Demonstrates basic client initialization, connection, message sending, and event registration.

```python
from neonize.client import NewClient
from neonize.utils import build_jid
from neonize.events import MessageEv

# Create client
client = NewClient("my_bot")

# Connect
client.connect()

# Send message
recipient = build_jid("1234567890")
client.send_message(recipient, "Hello!")

# Handle events
@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    print(f"Received: {event.Message.conversation}")
```

--------------------------------

### Configure NewClient Instances

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Various ways to initialize a client with different database backends and device properties.

```python
# Basic client with default SQLite database
client = NewClient("my_bot")

# Custom database path
client = NewClient("my_bot", database="./sessions/bot.db")

# PostgreSQL database
client = NewClient(
    "production_bot",
    database="postgresql://user:pass@localhost:5432/whatsapp"
)

# Custom device properties
from neonize.proto.waCompanionReg.WAWebProtobufsCompanionReg_pb2 import DeviceProps

props = DeviceProps(os="Custom Bot v1.0")
client = NewClient("custom_bot", props=props)
```

--------------------------------

### Initialize Client

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

Creates a client instance and initializes the session file.

```python
client = NewClient("my_first_bot")
```

--------------------------------

### Build Documentation

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Compile the documentation into static files in the site/ directory.

```bash
task docs-build
```

```bash
mkdocs build
```

--------------------------------

### Initialize PostgreSQL Client

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Use PostgreSQL for production environments with various SSL configurations.

```python
# Basic connection
client = NewClient("my_bot", database="postgres://username:password@localhost:5432/dbname")

# With SSL disabled
client = NewClient("my_bot", database="postgres://username:password@localhost:5432/dbname?sslmode=disable")

# With SSL required
client = NewClient("my_bot", database="postgres://username:password@localhost:5432/dbname?sslmode=require")
```

--------------------------------

### Initialize Neonize Client

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Basic client instantiation with default or custom database paths.

```python
from neonize.client import NewClient

# Basic client with default settings
client = NewClient("my_bot")

# Client with custom database
client = NewClient("my_bot", database="./sessions/bot.db")
```

--------------------------------

### Initialize SQLite Client

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Use SQLite for development and small-scale deployments.

```python
client = NewClient("my_bot", database="./whatsapp.db")
```

--------------------------------

### Create a Basic Synchronous WhatsApp Client

Source: https://context7.com/krypton-byte/neonize/llms.txt

Initialize and connect a synchronous WhatsApp client. Set up event handlers for connection and incoming messages. Requires `neonize.client.NewClient` and `neonize.events`.

```python
from neonize.client import NewClient
from neonize.events import MessageEv, ConnectedEv, event

# Initialize client with session name (stored in db.sqlite3)
client = NewClient("my_bot")

# Handle successful connection
@client.event(ConnectedEv)
def on_connected(client: NewClient, event: ConnectedEv):
    print("Bot connected successfully!")

# Handle incoming messages
@client.event(MessageEv)
def on_message(client: NewClient, message: MessageEv):
    text = message.Message.conversation or message.Message.extendedTextMessage.text
    chat = message.Info.MessageSource.Chat

    if text == "ping":
        client.reply_message("pong", message)
    elif text == "hello":
        client.reply_message("Hello! How can I help you?", message)

# Connect and keep running
client.connect()
event.wait()
```

--------------------------------

### Initialize and Run Neonize Client

Source: https://context7.com/krypton-byte/neonize/llms.txt

Instantiate the Neonize client, define an event handler for messages, and connect to the service. Ensure event waiting is enabled to keep the client running.

```python
client = NewClient("my_bot")

@client.event(MessageEv)
def on_message(client: NewClient, message: MessageEv):
    handler.handle(client, message)

client.connect()
event.wait()
```

--------------------------------

### Separate Configurations by Environment

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Set up different database and logging configurations based on the environment variable 'ENVIRONMENT'. Defaults to 'development' if not specified.

```python
import os
from neonize.client import NewClient

ENVIRONMENT = os.getenv("ENVIRONMENT", "development")

if ENVIRONMENT == "production":
    DATABASE = os.getenv("PRODUCTION_DB_URL")
    LOG_LEVEL = "WARNING"
elif ENVIRONMENT == "staging":
    DATABASE = os.getenv("STAGING_DB_URL")
    LOG_LEVEL = "INFO"
else:
    DATABASE = "./dev.db"
    LOG_LEVEL = "DEBUG"

client = NewClient("bot", database=DATABASE)
```

--------------------------------

### Install Python Development Headers on Fedora

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install the Python 3 development headers package on Fedora systems, required for compiling Python extensions.

```bash
sudo dnf install python3-devel
```

--------------------------------

### Initialize NewClient

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Constructor signature for creating a new WhatsApp client instance.

```python
from neonize.client import NewClient

client = NewClient(
    name: str,
    database: str = None,
    props: DeviceProps = None
)
```

--------------------------------

### Install Python Development Headers on Ubuntu/Debian

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Install the Python 3 development headers package on Ubuntu or Debian-based systems, required for compiling Python extensions.

```bash
sudo apt install python3-dev
```

--------------------------------

### Revoke Messages

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Method signature and example for deleting a message for all participants.

```python
client.revoke_message(
    chat: str,
    sender: str,
    message_id: str
)
```

```python
client.revoke_message(chat_jid, sender_jid, "MSG_ID")
```

--------------------------------

### Edit Messages

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Method signature and example for updating an existing message.

```python
client.edit_message(
    chat: str,
    message_id: str,
    new_message: Message
)
```

```python
from neonize.proto.waE2E.WAWebProtobufsE2E_pb2 import Message

new_msg = Message(conversation="Updated text")
client.edit_message(chat_jid, "MSG_ID", new_msg)
```

--------------------------------

### Configure Neonize Database

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

Initialize the client with either a local SQLite file or a PostgreSQL connection string.

```python
client = NewClient("my_bot", database="./my_bot.db")
```

```python
client = NewClient(
    "my_bot",
    database="postgresql://user:password@localhost:5432/whatsapp"
)
```

--------------------------------

### Get Own User Information

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Retrieve information about the currently logged-in user.

```python
me = client.get_me()
print(f"My JID: {me.JID.User}")
```

--------------------------------

### Configure PostgreSQL Database

Source: https://github.com/krypton-byte/neonize/blob/master/docs/faq.md

Initialize a NewClient instance with a PostgreSQL database connection string for production environments. Ensure PostgreSQL is properly set up and accessible.

```python
client = NewClient(
    "bot",
    database="postgresql://user:pass@localhost/db"
)
```

--------------------------------

### Build HTML Documentation Manually

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Manually build the project's HTML documentation using mkdocs.

```bash
mkdocs build
```

--------------------------------

### Reply to Messages

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Method signature and event-driven example for replying to specific messages.

```python
response = client.reply_message(
    text: str,
    quoted: MessageEv,
    link_preview: bool = False,
    reply_privately: bool = False
)
```

```python
from neonize.events import MessageEv

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    # Reply to message
    client.reply_message("Thanks!", event)
    
    # Private reply in group
    client.reply_message(
        "This is private",
        event,
        reply_privately=True
    )
```

--------------------------------

### Get Group Info

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Retrieve information about a specific group using its JID.

```python
info = client.get_group_info(group_jid: str)
```

--------------------------------

### Build Static Documentation

Source: https://github.com/krypton-byte/neonize/blob/master/DOCUMENTATION_SETUP.md

Generates the static HTML files for the documentation. The output will be placed in the `site/` directory.

```bash
task docs-build
```

--------------------------------

### Clone the Neonize Repository

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/index.md

Initializes the local development environment by cloning the source code.

```bash
git clone https://github.com/krypton-byte/neonize.git
cd neonize
```

--------------------------------

### Create an Async WhatsApp Client

Source: https://context7.com/krypton-byte/neonize/llms.txt

Initialize and connect an asynchronous WhatsApp client using asyncio for non-blocking operations. Requires `neonize.aioze.client.NewAClient` and `neonize.aioze.events`.

```python
import asyncio
from neonize.aioze.client import NewAClient
from neonize.aioze.events import ConnectedEv, MessageEv

client = NewAClient("async_bot")

@client.event(ConnectedEv)
async def on_connected(client: NewAClient, event: ConnectedEv):
    print("Async bot connected!")

@client.event(MessageEv)
async def on_message(client: NewAClient, message: MessageEv):
    text = message.Message.conversation or message.Message.extendedTextMessage.text
    chat = message.Info.MessageSource.Chat

    if text == "ping":
        await client.reply_message("pong", message)
    elif text == "wait":
        await client.send_message(chat, "Waiting for 5 seconds...")
        await asyncio.sleep(5)
        await client.send_message(chat, "Done waiting!")

async def main():
    await client.connect()
    await client.idle()  # Keep receiving events

# Always use asyncio.run() - do NOT use deprecated get_event_loop()
asyncio.run(main())
```

--------------------------------

### Check for Neonize Package

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/installation.md

Verify if Neonize is listed in your installed packages. This helps troubleshoot `ModuleNotFoundError`.

```bash
pip list | grep neonize
```

--------------------------------

### Platform-Specific Build for Windows

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Build the goneonize shared library for Windows (amd64 architecture) with CGO enabled. Environment variables are set using 'set' command.

```bash
cd goneonize
set CGO_ENABLED=1
set GOOS=windows
set GOARCH=amd64
go build -buildmode=c-shared -o neonize-windows-amd64.dll
```

--------------------------------

### International Phone Number Formatting

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/authentication.md

Examples of providing phone numbers with country codes for pairing.

```python
# US number
client.pair_phone("1234567890")  # Country code 1 is implied

# UK number
client.pair_phone("447123456789")  # Include country code

# India number
client.pair_phone("919876543210")  # Include country code
```

--------------------------------

### Deploy with PostgreSQL

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/authentication.md

Configure the client to use a PostgreSQL database for production environments.

```python
import os
from neonize.client import NewClient

# Use PostgreSQL for production
DATABASE_URL = os.getenv(
    "DATABASE_URL",
    "postgresql://user:pass@localhost:5432/whatsapp"
)

client = NewClient("production_bot", database=DATABASE_URL)
```

--------------------------------

### Commit Changes

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/contributing.md

Examples of commit messages following the project's conventional commit format.

```bash
git commit -m "feat: add support for new feature"
git commit -m "fix: resolve issue with message handling"
git commit -m "docs: update installation guide"
```

--------------------------------

### Run Development Tools

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/contributing.md

Commands for testing, linting, formatting, and type checking the codebase.

```bash
# Run tests
pytest

# Check code style
ruff check .
ruff format .

# Type checking
mypy neonize
```

--------------------------------

### Configure Database via Environment Variables

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/authentication.md

Use environment variables to manage database paths securely.

```python
import os

DATABASE_URL = os.getenv("WHATSAPP_DB_URL", "./bot.db")
client = NewClient("bot", database=DATABASE_URL)
```

--------------------------------

### NewClient Initialization

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Initialize the synchronous client for Neonize. This client is the primary interface for interacting with WhatsApp.

```APIDOC
## NewClient Constructor

### Description
Initializes the main synchronous client for interacting with WhatsApp through Neonize. It provides a complete interface for sending messages, handling media, managing groups, and responding to events.

### Parameters
#### Path Parameters
- **name** (str) - Required - Unique identifier for this client session
- **database** (str) - Optional - Database connection string (SQLite or PostgreSQL). Defaults to None.
- **props** (DeviceProps) - Optional - Custom device properties. Defaults to None.

### Request Example
```python
from neonize.client import NewClient
from neonize.proto.waCompanionReg.WAWebProtobufsCompanionReg_pb2 import DeviceProps

# Basic client with default SQLite database
client = NewClient("my_bot")

# Custom database path
client = NewClient("my_bot", database="./sessions/bot.db")

# PostgreSQL database
client = NewClient(
    "production_bot",
    database="postgresql://user:pass@localhost:5432/whatsapp"
)

# Custom device properties
props = DeviceProps(os="Custom Bot v1.0")
client = NewClient("custom_bot", props=props)
```
```

--------------------------------

### Implement Simple Command Parser

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/receiving-messages.md

Parses incoming text messages for commands starting with a forward slash.

```python
@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    text = event.Message.conversation or ""
    
    if not text.startswith("/"):
        return
    
    # Parse command
    parts = text.split()
    command = parts[0][1:]  # Remove /
    args = parts[1:] if len(parts) > 1 else []
    
    # Handle commands
    if command == "help":
        help_text = """
Available commands:
/help - Show this help
/ping - Pong!
/echo <text> - Echo back text
        """
        client.reply_message(help_text, event)
    
    elif command == "ping":
        client.reply_message("Pong! 🏓", event)
    
    elif command == "echo":
        if args:
            client.reply_message(" ".join(args), event)
        else:
            client.reply_message("Usage: /echo <text>", event)
```

--------------------------------

### Use Configuration Classes

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Define and use a dataclass for configuration to manage bot name, database URL, log level, and retries. This provides a structured way to handle settings.

```python
from dataclasses import dataclass
from neonize.client import NewClient

@dataclass
class Config:
    bot_name: str = "my_bot"
    database_url: str = "./bot.db"
    log_level: str = "INFO"
    max_retries: int = 3

config = Config()
client = NewClient(config.bot_name, database=config.database_url)
```

--------------------------------

### Test Documentation Locally

Source: https://github.com/krypton-byte/neonize/blob/master/DOCUMENTATION_SETUP.md

Run this command to test your documentation locally before committing changes. It ensures the documentation builds and renders correctly.

```bash
task docs-validate
```

--------------------------------

### Configure Database Backends

Source: https://github.com/krypton-byte/neonize/blob/master/README.md

Configures the client session storage using different database backends like SQLite, PostgreSQL, or in-memory storage.

```python
# SQLite (default)
client = NewClient("bot_name", database="./app.db")

# PostgreSQL (recommended for production)
client = NewClient("bot_name", database="postgres://user:pass@localhost/dbname")

# In-memory (for testing)
client = NewClient("bot_name", database=":memory:")
```

--------------------------------

### Send Messages

Source: https://github.com/krypton-byte/neonize/blob/master/docs/api-reference/async-client.md

Method signature and usage examples for sending text messages with optional features like link previews and ghost mentions.

```python
response = client.send_message(
    to: str,
    message: Union[str, Message],
    link_preview: bool = False,
    ghost_mentions: str = "",
    add_msg_secret: bool = False
)
```

```python
from neonize.utils import build_jid

recipient = build_jid("1234567890")

# Simple text
response = client.send_message(recipient, "Hello!")
print(f"Sent: {response.ID}")

# With link preview
client.send_message(
    recipient,
    "Check this: https://github.com/krypton-byte/neonize",
    link_preview=True
)

# With ghost mentions
client.send_message(
    recipient,
    "Secret mention",
    ghost_mentions="@1234567890"
)
```

--------------------------------

### Create WhatsApp Group

Source: https://github.com/krypton-byte/neonize/blob/master/docs/faq.md

Create a new WhatsApp group with a specified name and a list of participant JIDs. Consult the Group Management guide for further information.

```python
group = client.create_group("Group Name", [jid1, jid2, jid3])
```

--------------------------------

### Send Images and Videos

Source: https://github.com/krypton-byte/neonize/blob/master/docs/faq.md

Send image or video files with optional captions using client.send_image and client.send_video methods. Refer to the Media Handling guide for more details.

```python
client.send_image(jid, "path/to/image.jpg", caption="Caption")
client.send_video(jid, "path/to/video.mp4", caption="Caption")
```

--------------------------------

### Build Distribution Wheel and Source Archive

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Build the Neonize distribution packages (wheel and source archive) using the 'build' package. The output will be in the 'dist/' directory.

```bash
pip install build
python -m build
```

--------------------------------

### Connection Pooling for PostgreSQL

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Optimize PostgreSQL connections by specifying pool parameters directly in the database URL. This example sets minimum connections, maximum connections, and connection timeout.

```python
# Optimize PostgreSQL connection pool
database_url = (
    "postgresql://user:pass@host:5432/db"
    "?pool_min_conns=10"
    "&pool_max_conns=50"
    "&pool_timeout=30"
)

client = NewClient("bot", database=database_url)
```

--------------------------------

### Create Multiple Client Instances

Source: https://github.com/krypton-byte/neonize/blob/master/docs/faq.md

Instantiate multiple NewClient objects with distinct session names to manage separate WhatsApp accounts.

```python
bot1 = NewClient("account1")
bot2 = NewClient("account2")
```

--------------------------------

### Manage multiple sessions with ClientFactory

Source: https://github.com/krypton-byte/neonize/blob/master/docs/async/index.md

Handles multiple client sessions simultaneously using a single entry point.

```python
import asyncio
from neonize.aioze.client import ClientFactory, NewAClient
from neonize.aioze.events import ConnectedEv, MessageEv

client_factory = ClientFactory("sessions.db")

for device in client_factory.get_all_devices():
    client_factory.new_client(device.JID)

@client_factory.event(ConnectedEv)
async def on_connected(client: NewAClient, event: ConnectedEv):
    print("⚡ Client connected")

@client_factory.event(MessageEv)
async def on_message(client: NewAClient, event: MessageEv):
    if event.Message.conversation == "ping":
        await client.reply_message("pong!", event)

async def main():
    await client_factory.run()       # connects all clients
    await client_factory.idle_all()  # keeps them alive

asyncio.run(main())  # ← single entry point for all sessions
```

--------------------------------

### Error Handling for Message Processing in Python

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/receiving-messages.md

Implement error handling within message event listeners to gracefully manage exceptions. This example catches potential errors during message processing and sends a user-friendly error reply.

```python
@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    try:
        text = event.Message.conversation
        if text:
            process_message(text)
    except Exception as e:
        print(f"Error processing message: {e}")
        client.reply_message("Sorry, an error occurred", event)
```

--------------------------------

### Rate Limiting Message Handling in Python

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/receiving-messages.md

Implement rate limiting to control the frequency of message processing per user. This example uses a `defaultdict` to track the last message time for each sender and enforces a minimum delay between messages.

```python
from collections import defaultdict
import time

# Track last message time per user
last_message_time = defaultdict(float)
RATE_LIMIT = 2  # seconds

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    sender = event.Info.MessageSource.Sender.User
    current_time = time.time()
    
    # Check rate limit
    if current_time - last_message_time[sender] < RATE_LIMIT:
        return  # Ignore message
    
    last_message_time[sender] = current_time
    
    # Process message
    handle_message(client, event)
```

--------------------------------

### Configure via Environment Variables

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Use environment variables for sensitive configuration data.

```python
import os
from neonize.client import NewClient

# Database URL from environment
DATABASE_URL = os.getenv("WHATSAPP_DB_URL", "sqlite:///./bot.db")

# Bot name from environment
BOT_NAME = os.getenv("BOT_NAME", "default_bot")

client = NewClient(BOT_NAME, database=DATABASE_URL)
```

```bash
# .env
WHATSAPP_DB_URL=postgresql://user:pass@localhost:5432/whatsapp
BOT_NAME=production_bot
LOG_LEVEL=INFO
```

```python
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

from neonize.client import NewClient

client = NewClient(
    os.getenv("BOT_NAME"),
    database=os.getenv("WHATSAPP_DB_URL")
)
```

--------------------------------

### Download Media with Progress

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/receiving-messages.md

Downloads a document message and saves it to a file, utilizing the tqdm library for progress tracking.

```python
from tqdm import tqdm

@client.event(MessageEv)
def on_message(client: NewClient, event: MessageEv):
    msg = event.Message
    
    if msg.documentMessage:
        file_size = msg.documentMessage.fileLength
        filename = msg.documentMessage.fileName
        
        print(f"Downloading {filename} ({file_size} bytes)...")
        
        # Download
        data = client.download_any(msg)
        
        # Save
        with open(f"downloads/{filename}", "wb") as f:
            f.write(data)
        
        print("Download complete!")
```

--------------------------------

### Deploy to GitHub Pages

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Command to build and push documentation to the gh-pages branch.

```bash
task docs-deploy
```

--------------------------------

### API Documentation with mkdocstrings

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

Use mkdocstrings to automatically generate API documentation from source code.

```markdown
::: neonize.client.NewClient
    options:
      show_root_heading: true
      show_source: true
```

--------------------------------

### Create an Asynchronous Bot with Neonize

Source: https://github.com/krypton-byte/neonize/blob/master/docs/examples/index.md

A basic asynchronous bot using the aioze client for non-blocking event handling.

```python
import asyncio
from neonize.aioze.client import NewAClient
from neonize.aioze.events import ConnectedEv, MessageEv

client = NewAClient("async_bot.sqlite3")

@client.event(ConnectedEv)
async def on_connected(client: NewAClient, event: ConnectedEv):
    print("⚡ Connected")

@client.event(MessageEv)
async def on_message(client: NewAClient, event: MessageEv):
    text = event.Message.conversation or event.Message.extendedTextMessage.text
    if text == "ping":
        await client.reply_message("pong!", event)

async def main():
    await client.connect()
    await client.idle()

asyncio.run(main())
```

--------------------------------

### Taskipy Documentation Commands

Source: https://github.com/krypton-byte/neonize/blob/master/docs/README.md

List of available tasks for managing documentation.

```bash
# Serve with live reload
task docs-serve

# Build documentation
task docs-build

# Deploy to GitHub Pages
task docs-deploy

# Clean built files
task docs-clean

# Build with strict validation
task docs-validate
```

--------------------------------

### Platform-Specific Build for macOS (arm64)

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Build the goneonize shared library for macOS (Apple Silicon arm64 architecture) with CGO enabled.

```bash
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 \
  go build -buildmode=c-shared -o neonize-darwin-arm64.dylib
```

--------------------------------

### Correct Modern Async Pattern

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/quickstart.md

The recommended way to run an async main function.

```python
# ✅ CORRECT — standard since Python 3.7, works on all versions
asyncio.run(main())
```

--------------------------------

### Build Neonize Docker Image

Source: https://github.com/krypton-byte/neonize/blob/master/docs/development/building.md

Build the Docker image for Neonize using the Dockerfile in the current directory.

```bash
docker build -t neonize .
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/krypton-byte/neonize/blob/master/docs/getting-started/authentication.md

Configure standard logging to troubleshoot connection issues.

```python
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

client = NewClient("my_bot")
client.connect()
```

--------------------------------

### Configure PostgreSQL Database

Source: https://github.com/krypton-byte/neonize/blob/master/docs/user-guide/client-configuration.md

Production-ready database configuration supporting SSL and connection pooling.

```python
from neonize.client import NewClient

# PostgreSQL connection
client = NewClient(
    "production_bot",
    database="postgresql://username:password@localhost:5432/whatsapp"
)

# With SSL
client = NewClient(
    "production_bot",
    database="postgresql://user:pass@host:5432/db?sslmode=require"
)

# Connection pooling
database_url = "postgresql://user:pass@host:5432/db?pool_min_conns=5&pool_max_conns=20"
client = NewClient("bot", database=database_url)
```