nanodjango Documentation

When writing a plugin that moves code to a new file, use the Resolver to ensure all necessary imports and dependencies are included.

1. Initialize a Resolver with the target module name (e.g., '.api').
2. When you find a symbol to move, use resolver.add(name, references) to register the symbol and its dependencies.
3. Use resolver.gen_src() to generate the necessary import statements and boilerplate code.
4. Use converter.write_file() to write the generated header and the collected code body.

from nanodjango.convert.plugin import Resolver

# Inside a hook implementation
resolver = Resolver(converter, ".api")
# ... find symbols ...
resolver.add(name, references)
# ... later ...
converter.write_file(
    converter.app_path / "api.py",
    resolver.gen_src(),
    "\n".join(code_lines)
)

Models are defined using standard django.db.models. Crucially, they must be defined in the same file as your Django instance and must appear after the app = Django() line.

To apply migrations, use the nanodjango run command, which automatically creates and applies migrations for your script.

from django.db import models
from nanodjango import Django

app = Django()

class CountLog(models.Model):
    timestamp = models.DateTimeField(auto_now_add=True)

To run the script and apply migrations:

nanodjango run counter.py

Nanodjango allows you to extend its behavior using hooks. Plugins are defined by decorating functions with nanodjango.hookimpl. These hooks allow you to customize the conversion process, integrate third-party packages, or inject custom logic during the Django setup or the code conversion lifecycle.

from nanodjango import hookimpl

@hookimpl
def your_hook_name(context):
    # Your plugin logic here
    pass

To avoid import order issues, use the app.ninja attribute to access Django Ninja features (like Schema or File) instead of importing ninja directly. This allows you to use Ninja's types and utilities while maintaining compatibility with nanodjango's single-file configuration pattern.

class Item(app.ninja.Schema):
    foo: str
    bar: float

@app.api.post('/do_something')
def do_something(
    request,
    item: Item,
    file: app.ninja.UploadedFile = app.ninja.File(..)
):
    ...

The SQLite database used by your script is stored entirely within your browser's local storage.

Key characteristics:

• Privacy: The database is never sent to the server.
• Isolation: Databases are not shared when you share a script. Every visitor who runs your script starts with their own fresh, empty database instance.

Instead of replacing a setting entirely, you can pass a callable (like a lambda) to modify existing nanodjango default settings. The callable will receive the current value as an argument, and its return value will be used as the new setting. This is ideal for prepending/appending to lists like MIDDLEWARE or INSTALLED_APPS.

Note: This behavior only applies to settings that already exist in nanodjango's defaults. For new settings, the callable is stored as-is (e.g., for WHITENOISE_ADD_HEADERS_FUNCTION).

app = Django(
    MIDDLEWARE=lambda m: [MyPreMiddleware] + m + [MyPostMiddleware],
    INSTALLED_APPS=lambda apps: [a for a in apps if "admin" not in a],
)

During conversion, nanodjango may add an @ensure_http_response decorator to views that lack type hints. This decorator automatically converts str return values into HttpResponse objects at runtime.

To avoid this decorator and ensure cleaner code in your new Django project, add a type hint for the return value (e.g., -> HttpResponse or a subclass like -> HttpResponseRedirect).

@app.route("/author/")
def redirect(request) -> HttpResponseRedirect:
    return HttpResponseRedirect("https://radiac.net/")

You can pass the app = Django() instance directly to standard WSGI or ASGI servers. The app object automatically detects if it should use WSGI or ASGI based on whether async views or endpoints are present.

WSGI (Standard):

gunicorn -w 4 counter:app

ASGI (Async):

uvicorn counter:app

Explicit Handlers: If you want to override the automatic detection, specify the handler explicitly:

gunicorn counter:app.wsgi
uvicorn counter:app.asgi

To integrate a nanodjango site into a larger project or publish it as a standalone PyPI package, you can wrap your script in a Python package. This allows you to launch the app using the package name (e.g., python -m myproject) instead of running a single file.

Recommended directory structure:

myproject/
  __init__.py
  __main__.py
  app.py

In this setup, app.py contains your nanodjango logic, and __main__.py serves as the entry point.