Mafia Online API for Python

A Python client library for Mafia Online.

Temporary Suspension of Library Updates

During an audit, it was discovered that my code was being used in violation of the terms of the GPL license. As a result, an investigation is currently underway.

Until the situation is resolved, no updates to the library to support the new API will be released.

Further updates and a possible timeline for resuming development will be provided after the investigation is complete.

Overview

zafiaonline is a small library providing utilities and client functionality for interacting with the Mafia Online service. It includes:

• an async Client for authentication and API calls,
• anti-ban utilities and message tracking helpers,
• transport layers and ancillary utilities.

Full documentation is available at ReadtheDocs

Install

Install from PyPI:

pip install zafiaonline

Install for development from source:

python -m venv .venv
source .venv/bin/activate    # macOS / Linux
pip install -e .
pip install -r docs/requirements.txt   # optional: build docs locally

Quickstart — Import and Auth

Example using the async Client:

import asyncio
import zafiaonline

async def main():
    client = zafiaonline.Client()
    await client.auth.sign_in("email@example.com", "your_password")
    # Use the client for API calls, then sign out
    await client.https.sign_out()

asyncio.run(main())

If you prefer a synchronous helper wrapper, wrap async calls via asyncio.run() or your own event loop.

Examples

Create a client and fetch some data (pseudo-code):

import asyncio
import zafiaonline

async def example():
    client = zafiaonline.Client()
    await client.auth.sign_in("email", "password")
    profile = await client.players.get_user("user_xxxxxxxxxxxx")   # example id
    print(profile[zafiaonline.PacketDataKeys.USER_PROFILE][zafiaonline.PacketDataKeys.PROFILE_USER_DATA])
    await client.https.sign_out()

asyncio.run(example())

Adjust imports and method names to the actual API surface of your package.

Documentation

Docs are published at: https://zafiaonlinepy.readthedocs.io/en/latest/

Build docs locally:

cd docs
make html
# Open docs/_build/html/index.html

If you use the src/ layout, ensure docs/source/conf.py contains:

import os
import sys
sys.path.insert(0, os.path.abspath("../../src"))
master_doc = "index"

Read the Docs (CI) config

Example .readthedocs.yaml to place in the repo root:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: latest

sphinx:
  configuration: docs/source/conf.py

python:
  install:
    - method: pip
      path: .
    - requirements: docs/requirements.txt

And docs/requirements.txt (basic):

sphinx
sphinx-rtd-theme

Configuration (YAML)

The library also supports configuration via a YAML file for WebSocket connection parameters.
Example config.yaml:

host: "dottap.com"
port: 7091
connect_type: "wss"

You can then load and use it inside your project:

class Config:
    def __init__(self, path: str = "ws_config.yaml") -> None:
        config_path = files('zafiaonline.transport.websocket').joinpath(path)
        with as_file(config_path) as resource_file:
            with open(resource_file, "r") as config_file:
                config: dict = yaml.safe_load(config_file)
        self.address: str = config.get("address", "dottap.com")
        self.port: int = config.get("port", 7091)
        self.connect_type: str = config.get("connect_type", "wss")

This way, connection details are kept separate from your code and can be changed without modifying Python files.

Troubleshooting Sphinx / Documentation

• Unexpected indentation — fix docstring code examples: use : then an indented literal block:

  """Typical Usage Example:
  
      messages = SentMessages(enable_logging=True)
      messages.add_message("hello")
  """
  

• Index file is not present — ensure docs/source/index.rst exists and master_doc = "index" in conf.py.

• Duplicate or ambiguous cross-references — avoid re-exporting the same object in __init__.py or use fully-qualified cross-references (e.g. :class:\zafiaonline.main.Client``) or :no-index: to suppress duplicates.

Contributing

1. Fork the repo → create a feature branch → open a PR.
2. Follow code style and include tests for non-trivial changes.
3. In PR description, explain changes and link documentation where applicable.

License

This project is licensed under GNU GPL v3.0 or later. See the LICENSE file for details.

Contact

Author: unelected Bugs & feature requests: open an issue on the repository.