Skip to content

Django Mindoff

Coverage Status PyPI version Python

Build production-ready Django REST APIs faster with less boilerplate.

Django Mindoff is an architectural framework that manages the structure and mechanics of API development so developers can focus on business logic, with efficient data workflows powered by Polars.

Key Features

  1. Project Setup That Just Works
    Start a new API project with guided CLI commands for init, create, delete, and nuke. Projects start ready to run with a sensible structure, so developers can begin building APIs immediately without worrying about project layout.

  2. Fully Managed APIs
    Define request method, access control, payload rules, rate limits, and execution mode in a single API definition. Mindoff enforces these rules automatically, handling validation, security checks, and execution flow behind the scenes.

  3. API Versioning That Stays Manageable
    Ship and evolve versioned APIs using a built‑in routing structure. APIs are automatically organized so new versions stay clean while existing clients continue working without disruption.

  4. Queue-Ready APIs
    Run APIs synchronously or as background processes when needed. Simply switch process_mode to "queue" and Mindoff handles queue orchestration, status tracking, progress updates, cancellation, and retries.

  5. Validation in One Line
    Use simple validation helpers that keep API logic clean and cognitively light. With aggregation support, multiple validation errors can be captured together and returned in a structured response.

  6. Consistent Responses, Every Time
    Return responses through a unified response structure using response endpoints. Messages stay professional, consistent, and predictable across the entire API surface.

  7. Vectorized Model Validation & Bulk Writes
    Pass a model_frame (DataFrame or LazyFrame) to create or update and Mindoff validates it automatically against the Django model. Validation runs in a vectorized, loop‑free pipeline and valid rows are written directly to the model's table with high efficiency.

  8. Querysets to DataFrames, Instantly
    Provide a Django queryset and Mindoff converts the results into a DataFrame or LazyFrame. Data is returned with built‑in pagination and streaming support, making large reads predictable and efficient.

  9. Optimized Polars Utilities for DataFrame & LazyFrame
    Run checks, conversions, and transformations seamlessly across both DataFrame and LazyFrame with Mindoff’s Polars utilities. Operations run natively in vectorized form and stay tuned for performance and efficiency, keeping data pipelines smooth and predictable.

  10. Tests With Almost No Setup
    Write API tests using declarative test mixins that talk to the API automatically. Focus on verifying behavior instead of crafting request calls and basic assertions, which are handled automatically by Mindoff.

Quick Start

1. Install the Package

pip install django-mindoff

2. Initialize a Project

django-mindoff init

This sets up the project foundation for you, including structure, config files, and ready-to-run wiring. Framework dependencies are managed internally, and django-mindoff aligns compatible Django, DRF, and Polars versions for you. Read the complete list here: requirements guide.

What you should see:

  • A new project scaffold with manage.py, mindoff.py, config/, and apps/
  • Environment and config files ready to use

3. Create an App

python mindoff.py create

In the interactive flow, choose option 1 and create an app named shop.

What you should see:

  • App folder at apps/shop/
  • App route linked as versioned URL at config/urls.py
  • App path added INSTALLED_APPS at config/settings.py

4. Create an API

python mindoff.py create

In the interactive flow, choose option 2 and create an API named ping under the shop app.

This generates the API file and wires its route so the endpoint is callable right away.

What you should see:

  • API file at apps/shop/apis/ping.py
  • URL route auto-registered at apps/shop/urls.py

5. Return a Success Response

Open apps/shop/apis/ping.py and add this inside the API class run() method:

def run(self, request, *args, **kwargs):
    return mo_response_kit.json_response(
        code="SUCCESS",
        category="success",
        data={"message": "Hello from shop ping"}
    )

6. Run and Verify

python manage.py makemigrations
python manage.py migrate
python manage.py runserver

Open:

  • http://127.0.0.1:8000/v1/shop/ping/

What you should get:

  • A JSON response with status, structured message metadata, and your data.message

✅ You now have a working API endpoint running with a structured success response.

From here, shape the run() method around your real business logic and output. To control response messaging, add custom entries in config/responses.csv with your preferred http_status code. When you are ready to move beyond Quick Start, continue with the developer guide. It covers the package features in detail, explains configuration and architecture choices, and helps you build real-world applications with confidence.

License

This project uses the same BSD 3-Clause License as the Django project. See the LICENSE file for full terms.