DEV Community: Augusto Domingos

Metaprogramming and the Limits of Static Analysis

Augusto Domingos — Sun, 25 Jan 2026 08:01:25 +0000

About a year ago, I started Lazy Ninja with a clear goal: eliminate boilerplate in Django APIs.

The idea was simple in theory: automatically generate CRUD routes, validation, serialization, and documentation directly from Django models. Less repetition, fewer files to maintain, and a smoother developer experience.

I was involved early in the development of Arkos.js, a project built on top of Prisma and designed around a schema-first, code-generated approach. That experience strongly influenced how I initially thought about tooling and type safety.

While building Lazy Ninja, however, I ran into a problem that had little to do with framework design and everything to do with how far static analysis can really go.

The real tension

The core issue is not Python versus any other language.

It is the tension between static analysis and runtime-driven systems.

Lazy Ninja relies heavily on metaprogramming and runtime introspection. In practice, it needs to:

Inspect Django models at runtime
Discover fields via reflection (_meta.get_fields())
Generate Pydantic schemas dynamically
Create API routes automatically

From a runtime perspective, this is safe and predictable. Django guarantees the existence of model fields, primary keys, and relationships.

From a static analysis perspective, however, things start to break down.

Why static analysis struggles with runtime-driven design

Static type checkers such as Pylance and mypy analyze code without executing it. They operate under a fundamental constraint: they can only reason about information that exists before runtime.

When a system builds part of its structure dynamically, static analysis simply cannot observe that process.

A minimal example:

User = get_user_model() # type unknown to the checker 
user.email # attribute may not exist (statically)  

# At runtime, Django guarantees that User has an email field

This is not a bug in the type checker.

It is a limitation of static analysis itself.

The contract exists — but it exists only at runtime.

A more realistic example from metaprogramming

Consider a simplified version of how Lazy Ninja inspects models:

def extract_fields(model):
    return [
        field.name
        for field in model._meta.get_fields()
        if not field.is_relation
    ]

At runtime, this works flawlessly.

Django’s model system ensures _meta is present and fully populated.

From the type checker’s point of view:

_meta is dynamic
get_fields() returns heterogeneous field types
The structure is opaque

The result is warnings — even though the behavior is correct.

The temptation to “fight” the type checker

Early on, it’s tempting to try to make the type checker happy at all costs:

Overusing cast()
Adding fake base classes
Writing overly generic Any annotations
Hiding logic behind layers of indirection

In practice, this often makes the code harder to read and less honest about what is happening.

At some point, I realized the better question was not:

“How do I silence the type checker?”

But rather:

“Where exactly does static analysis stop being useful?”

When static analysis works extremely well

Static analysis shines when the data contract is known before execution.

Schema-first systems that generate code ahead of time give static analyzers full visibility into models, fields, and relationships. This is why tools like Prisma Client Python can offer strong type safety in Python: the client is generated from a schema, not inferred from runtime behavior.

In those systems:

Autocomplete works perfectly
IDEs understand relationships
Many bugs are caught before execution

This reinforces an important idea:

The limitation is not the language, but when the contract exists.

Why Lazy Ninja does not adopt a schema-first approach

I seriously considered a schema-first model.

However, Lazy Ninja is intentionally built on top of Django, not just as a database access layer.

Django provides much more than an ORM:

A mature model system tightly integrated with the framework
Migrations and schema evolution
The admin panel
Signals, authentication, permissions, and a large ecosystem

Adopting a separate schema and code-generation pipeline would mean stepping outside Django’s model system and duplicating responsibilities that Django already handles well.

Lazy Ninja’s goal is not to replace Django’s data layer, but to amplify it — even if that means accepting the limits of static analysis in exchange for runtime flexibility.

Making the trade-offs explicit

Rather than pretending full static guarantees were possible, I chose to make the boundaries explicit.

Strategic `type: ignore`

user_id = user.id  # type: ignore[attr-defined]

Here, Django guarantees that every model instance has a primary key.

The type: ignore is local and intentional.

Safe attribute access with `getattr`

last_login = getattr(user, "last_login", None)

This allows optional fields without breaking at runtime and without lying to the type system.

Conditional logic with `hasattr`

if  hasattr(user, "is_staff"):
    ...

This is especially useful for compatibility across Django versions or custom user models.

Encapsulating ambiguity with type guards

from typing import TypeGuard

def is_django_model(obj) -> TypeGuard[Model]:
    return hasattr(obj, "_meta")

This keeps dynamic checks localized and improves readability.

The outcome

This approach led to a predictable result:

Zero runtime errors
Some IDE warnings
A codebase that is honest about its constraints

Most importantly, it avoided the illusion of safety that comes from forcing static guarantees where they cannot truly exist.

The main lesson

Static analysis is not a universal solution.

It has real limits when applied to systems designed around runtime introspection and metaprogramming. Lazy Ninja does not fight type checkers — it operates beyond what they can fully model.

The real challenge is being explicit about where static guarantees end and runtime guarantees begin, and designing systems that respect that boundary.

Final reflection

Building Lazy Ninja ended up being less about generating routes and more about understanding the architectural limits of static analysis in highly dynamic systems.

If you’ve built frameworks, ORMs, or tooling that relies heavily on metaprogramming, you’ve likely faced the same trade-offs — regardless of language.

Lazy Ninja is available on GitHub, and you can experiment with it directly in your Django projects.

Integração do Cloudinary ao seu projeto Django gratuitamente

Augusto Domingos — Tue, 16 Jul 2024 11:53:27 +0000

No tutorial passado, você aprendeu a hospedar um site Django de maneira gratuita no Vercel. Mas o que acontece se o seu site precisar fazer upload de arquivos, como fotos ou vídeos? Normalmente, você teria um diretório de mídia no seu projeto para armazenar e renderizar esses arquivos, pois não é uma boa prática armazenar fotos ou vídeos diretamente no banco de dados.

No entanto, a Vercel não permite escrita na plataforma. Como resolver isso? É aí que entra o Cloudinary, um serviço de upload de imagens e vídeos com um plano gratuito oferecendo 25 GB de storage, ideal para o seu projeto que necessita de armazenamento de mídias.

Neste tutorial, você aprenderá a integrar o Cloudinary ao seu projeto Django, aproveitando a SDK que esta plataforma oferece para Python.

Implementando Cloudinary no seu projeto Django

Para seguir com esse tutorial, basta ter um projeto Django funcionando, seja ele já hospedado na Vercel ou não, pois o método é o mesmo.

Passo 1:

A primeira coisa é instalar a SDK do Cloudinary no seu ambiente de desenvolvimento usando:

pip install cloudinary

Dica: Se for na Vercel, basta adicionar cloudinary no requirements.txt do seu projeto e fazer o build (redeploy) novamente. Caso esteja controlando versões com o Git, o commit dessa alteração já vai automaticamente buildar na plataforma Vercel e estará instalando a biblioteca usando o nosso script bash que criamos anteriormente.

Passo 2:

No seu settings.py, importe o cloudinary e adicione a seguinte configuração:

import cloudinary
import cloudinary.uploader
import cloudinary.api

cloudinary.config(
  cloud_name = os.getenv("CLOUD_NAME"),
  api_key = os.getenv("CLOUD_API_KEY"),
  api_secret = os.getenv("CLOUD_SECRET_KEY"),
)

Passo 3:

No seu models.py faça o seguinte import:

from cloudinary.models import CloudinaryField

E no campo de imagem em qualquer modelo seu que faz upload de imagens, use o CloudinaryField além de models.ImageField (padrão do Django), veja o exemplo de um modelo Post:

# models.py

class Post(models.Model):
    title = models.CharField(max_length=100)
    description = models.CharField(max_length=250)
    image = CloudinaryField("image") # nesta linha

    def __str__(self):
        return self.title

Passo 4:

Agora você vai configurar váriaveis de ambiente que chamaste no segundo passo.
Para isso, crie um arquivo .env no diretório raíz do seu projeto com as seguintes variáveis:

CLOUD_NAME=seu cloud_name
CLOUD_API_KEY=sua api_key
CLOUD_SECRET_KEY=sua secret_key

Dica: Se estiver usando a Vercel, você pode adicionar variáveis de ambiente diretamente nas configurações do projeto na dashboard da plataforma. Além de criar um arquivo .env localmente, acesse a dashboard da Vercel e adicione as variáveis com os respectivos valores no seu projeto.

Falando em valores, você precisará pegar eles na sua conta do Cloudinary, para isso, acesse o site oficial, e crie uma conta se não tiver uma.
Tendo acesso à Dashboard da sua conta, clique em "Go to API Key":

Na próxima tela, clique em "Generate API KEY" para obter suas chaves de acesso:

Com isso, você terá os valores necessários para preencher seu arquivo .env: CLOUD_NAME, CLOUD_API_KEY e CLOUD_SECRET_KEY.

Neste tutorial, estamos usando o os.getenv para acessar as váriaveis, e para funcionar, precisamos da biblioteca python-dotenv. Então, caso não tenha essa biblioteca no seu ambiente, faça a instalação com:

pip install python-dotenv

E no princípio do settings.py do seu projeto, faça a importação dela para permitir o uso:

# settings.py

import os
from dotenv import load_dotenv
load_dotenv()

Tudo pronto! Você configurou o Cloudinary no seu projeto, permitindo o upload e host de imagens diretamente na plataforma. Parabéns por ter concluído!
Agora, para exibir essas imagens no seu projeto, você pode configurar suas views e templates para renderizar as URLs das imagens em suas páginas.

Links Utéis:

Projeto usado para configuração de Cloudinary nesse tutorial: https://github.com/AghastyGD/django-cloudinary-demo.git - Inclusive, neste repositório adicionei views e templates de exemplo para demonstrar uma imagem hospedada no Cloudinary. Você pode usá-lo como referência.
Documentação do Cloudinary para uso com Python: https://cloudinary.com/documentation/django_integration - Recomendo a leitura, pois oferece diversas funcionalidades adicionais, como compressão de imagens, transformações e muito mais.

Se precisar de mais ajuda ou tiver dúvidas, deixe um comentário. Te vejo na próxima vez 👋.

Hospede seu site Django com arquivos estáticos na Vercel gratuitamente (Novo Método)

Augusto Domingos — Fri, 12 Jul 2024 18:24:17 +0000

Hospedar um site Django completo pode ser um desafio, especialmente ao optar por plataformas gratuitas. No entanto, com a Vercel, você pode configurar seu site para ser hospedado sem custo algum 💸 , e com os arquivos estáticos funcionando corretamente utilizando esse novo método sem erros 🤩.
Neste tutorial, você será guiado por todo o processo, desde a preparação do ambiente até o deploy final.

Requisitos:

Ter um projeto Django funcional na sua máquina
Ter Python instalado

Atendendo esses requisitos, você já pode continuar o tutorial abaixo:

Preparando o ambiente

Passo 1:

Abra o arquivo wsgi.py do seu projeto, normalmente localizado dentro do seu diretorio "project_name" e adicione a seguinte linha no final:

import os
from django.core.wsgi import get_wsgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'nomedoseuprojeto.settings')

application = get_wsgi_application()

# esta linha
app = application

Passo 2:

Navegue até a pasta raiz do seu projeto e crie o arquivo vercel.json com o seguinte código:

{
  "version": 2,
  "builds": [
    {
      "src": "nomedoseuprojeto/wsgi.py",
      "use": "@vercel/python",
      "config": { "maxLambdaSize": "15mb", "runtime": "python3.9" }
    }],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "nomedoseuprojeto/wsgi.py"
    }
  ]
}

Substitua "nomedoseuprojeto" pelo nome do diretório onde está localizado o arquivo wsgi.py do seu projeto Django

Explicação (pode pular se quiser):

O arquivo vercel.json configura como seu projeto será construído e roteado na plataforma Vercel

version: Define a versão da configuração da Vercel (geralmente 1 ou 2).
builds: Especifica como seu projeto será construído.
- src: Caminho para o arquivo wsgi.py do seu projeto Django.
- use: Usa o ambiente Python da Vercel.
- config: Configurações específicas para Python, como tamanho máximo do pacote e versão.
routes: Define como as solicitações HTTP são roteadas.
- src: Todas as solicitações HTTP.
- dest: Encaminha para wsgi.py do seu projeto.

Agora com o vercel.json criado corretamente, no próximo passo você irá adicionar um script bash para executar comandos de terminal na plataforma Vercel.

Passo 3:

Na pasta raíz do seu projeto, crie mais um arquivo build.sh com o seguinte código:

# build.sh
echo "Starting build script"

pip install -r requirements.txt

# make migrations
python3 manage.py makemigrations
python3 manage.py migrate

# collectstatic
python3 manage.py collectstatic

echo "Build script completed"

Passo 4:

Gere um requirements.txt de todas as dependências do seu projeto, e adicione whitenoise na lista, conforme o exemplo abaixo:

# outras dependências...
Django==5.0.6
whitenoise==6.7.0

No momento da escrita deste post, a versão atual do WhiteNoise é a 6.7.0. Sinta-se à vontade para usar uma versão mais recente no seu caso.

Explicação:

WhiteNoise é uma biblioteca Python que ajuda a servir arquivos estáticos em aplicações web de maneira eficiente. É frequentemente usado com Django para simplificar a configuração e melhorar o desempenho no serviço de arquivos estáticos como CSS, JavaScript e imagens, muito útil para hospedagem em plataformas cloud.

Passo 5:

Adicione o middleware do whitenoise no settings.py do seu projeto:

'django.middleware.security.SecurityMiddleware',
'whitenoise.middleware.WhiteNoiseMiddleware',  # Adicione esta linha

Configure a localização dos seus arquivos estáticos:

STATIC_URL = 'static/'
STATIC_ROOT = (BASE_DIR/"static/")

E se preferir, adicione também a seguinte configuração para ativar a compressão e armazenamento em cache, garantindo melhor performance na sua aplicação:

STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

Fazendo Deploy na Vercel

Agora que você preparou o ambiente, está pronto para fazer o deploy do seu projeto na Vercel. Siga os passos abaixo para completar o processo:

1 - Crie uma conta na plataforma Vercel se ainda não tiver
2 - Importe o repositório git do seu projeto:

3 - Configure as variáveis de ambiente se o seu projeto precisar de alguma e depois clique em "Deploy":

4 - Aguarde o processo:

5 - Finalmente, após a conclusão do processo, você deve ver uma tela semelhante a esta:

E booyah! Você conseguiu hospedar o seu projeto Django com arquivos estáticos na Vercel! Parabéns pelo feito, é um grande passo!

Prepare-se para futuras jornadas, pois, uma vez que a Vercel é serverless, você não poderá realizar tarefas de escrita diretamente na Vercel, como upload de imagens e vídeos. No entanto, não se preocupe, Em um artigo futuro, você aprenderá como fazer isso gratuitamente utilizando a API de outra plataforma gratuita que serve arquivos de mídia, sem custos. 💸🫡

Nota: Se o seu projeto Django estiver utilizando o banco de dados SQLite, que é geralmente gerado em todos os projetos Django, não será possível realizar gravações diretamente na Vercel. Para isso, será necessário utilizar um servidor de banco de dados. A Vercel oferece uma instância gratuita de PostgreSQL que pode ser configurada no seu projeto.

Links Utéis

Código-fonte do Projeto usado para deploy neste tutorial: https://github.com/AghastyGD/ai-interview-django/tree/deploy (acesse a branch deploy)
Documentação do Whitenoise: https://whitenoise.readthedocs.io/en/stable/django.html

Volte sempre! ❤️ Dúvidas? deixe nos comentários!

DEV Community: Augusto Domingos

Metaprogramming and the Limits of Static Analysis

The real tension

Why static analysis struggles with runtime-driven design

A more realistic example from metaprogramming

The temptation to “fight” the type checker

When static analysis works extremely well

Why Lazy Ninja does not adopt a schema-first approach

Making the trade-offs explicit

Strategic type: ignore

Safe attribute access with getattr

Conditional logic with hasattr

Encapsulating ambiguity with type guards

The outcome

The main lesson

Final reflection

Integração do Cloudinary ao seu projeto Django gratuitamente

Implementando Cloudinary no seu projeto Django

Passo 1:

Passo 2:

Passo 3:

Passo 4:

Links Utéis:

Hospede seu site Django com arquivos estáticos na Vercel gratuitamente (Novo Método)

Requisitos:

Preparando o ambiente

Passo 1:

Passo 2:

Explicação (pode pular se quiser):

Passo 3:

Passo 4:

Explicação:

Passo 5:

Fazendo Deploy na Vercel

Links Utéis

Strategic `type: ignore`

Safe attribute access with `getattr`

Conditional logic with `hasattr`