nplusone

NPLUSONE

A Nplusone é uma biblioteca para detectar o problema de consultas n+1 em Python ORMs, incluindo SQLalChemy, Peewee e o Django ORM.

O problema

Muitas bibliotecas de mapeamento de objetos-relatórios (ORM) são inadimplentes para o carregamento preguiçoso para relacionamentos. Esse padrão pode ser eficiente quando linhas relacionadas raramente são acessadas, mas rapidamente se tornam ineficientes à medida que os relacionamentos são acessados ​​com mais frequência. Nesses casos, o carregamento de linhas relacionadas ansiosamente usando uma JOIN pode ser muito mais performante. Infelizmente, entender quando usar o carregamento preguiçoso versus ansioso pode ser um desafio: você pode não notar o problema até que seu aplicativo diminua a velocidade.

nplusone é uma ferramenta de perfil ORM para ajudar a diagnosticar e melhorar o desempenho fraco causado por um carregamento preguiçoso inadequado. nplusone monitora as aplicações usando Django ou Sqlalchemy e envia notificações quando são emitidas cargas preguiçosas potencialmente caras. Ele pode identificar o atributo de relacionamento ofensivo e as linhas específicas de código por trás do problema e recomendar correções para melhor desempenho.

nplusone também detecta o carregamento inapropriado e ansioso para o Flask-Sqlalchemy e o Django ORM, emitindo um aviso quando dados relacionados são carregados ansiosamente, mas nunca acessados ​​dentro da solicitação atual.

Instalação

 pip install -u nplusone

O Nplusone suporta Python> = 2,7 ou> = 3.3.

Uso

NOTA: nplusone deve ser usado apenas para desenvolvimento e não deve ser implantado em ambientes de produção.

Django

Nota: nplusone suporta Django> = 1.8.

Adicione nplusone ao INSTALLED_APPS :

 Instalado_apps = (
    ...
    'Nplusone.ext.django',
)

Adicione NPlusOneMiddleware :

 Middleware = (
    'Nplusone.ext.django.nplusonemiddleware',
    ...
)

Opcionalmente, configure as configurações de registro:

 Nplusone_logger = logging.getLogger ('Nplusone')
Nplusone_log_level = logging.warn

Configurar manipuladores de madeira:

 Logging = {
    'versão': 1,
    'Manipuladores': {
        'Console': {
            'classe': 'logging.streamhandler',
        },
    },
    'Loggers': {
        'Nplusone': {
            'manipuladores': ['console'],
            'nível': 'aviso',
        },
    },
}

Quando seu aplicativo carrega dados preguiçosamente, nplusone emite uma mensagem de log:

 Consulta Potencial N+1 detectada em `<model>. <field>`

Considere usar select_related ou prefetch_related neste caso.

Quando seu aplicativo carrega ansiosamente os dados relacionados sem acessá -los, nplusone registrará um aviso:

 Potencial carga ansiosa desnecessária detectada em `<model>. <field>`

Flask-sqlalchemy

Enrole o aplicativo com NPlusOne :

 do frasco de importação de frascos
de nplusone.ext.flask_sqlalchemy importar nplusone

App = Flask (__ nome__)
NPLUSONE (APP)

Opcionalmente, configure as configurações de registro:

 App = Flask (__ nome__)
app.config ['Nplusone_logger'] = logging.getLogger ('App.nplusOne')
app.config ['Nplusone_log_level'] = logging.error
NPLUSONE (APP)

Quando seu aplicativo carrega dados preguiçosamente, nplusone emite uma mensagem de log:

 Consulta Potencial N+1 detectada em `<model>. <field>`

Considere usar subqueryload ou joinedload neste caso; Consulte o Guia do SQLALCHEMY para carregamento de relacionamento para uma documentação completa.

Quando seu aplicativo carrega ansiosamente os dados relacionados sem acessá -los, nplusone registrará um aviso:

 Potencial carga ansiosa desnecessária detectada em `<model>. <field>`

WSGI

Para outras estruturas que seguem a especificação do WSGI, envolva seu aplicativo com o NPLUSONEMIDLEWARWware. Você também deve importar a extensão nplusone relevante para o seu ORM:

 garrafa de importação
de Nplusone.ext.wsgi importar nplusonemiddleware
importar nplusone.ext.SQLalChemy

App = NplusoneMiddleware (Bottle.App ())

Genérico

As integrações acima são acopladas ao ciclo de resposta-resposta. Para usar nplusone fora do contexto de uma solicitação HTTP, use o Profiler Context Manager: você também deve importar a extensão nplusone relevante para o seu ORM:

 de Nplusone.core Import Profiler
importar nplusone.ext.SQLalChemy

com perfiler.profiler ():
    ...

Personalização de notificações

Por padrão, nplusone registra todas as consultas potencialmente desnecessárias usando um logger chamado "NPLUSONE". Quando a opção de configuração Nplusone_raise estiver definida, nplusone também aumentará um NPlusOneError . Isso pode ser usado para forçar todos os testes automatizados envolvendo consultas desnecessárias a falhar.

 # Django Config
Nplusone_raise = true

# Flask Config
app.config ['Nplusone_raise'] = true

O tipo de exceção também pode ser especificado, se desejado, usando a opção NPLUSONE_ERROR .

Ignorando notificações

Para ignorar as notificações da nplusone em todo o mundo, configure a lista de permissões usando a opção NPLUSONE_WHITELIST:

 # Django Config
Nplusone_whitelist = [
    {'Label': 'n_plus_one', 'modelo': 'myApp.mymodel'}
]

# Flask-SqlalChemy Config
App.config ['Nplusone_whitelist'] = [
    {'Label': 'Unused_eAger_load', 'Model': 'MyModel', 'Field': 'My_Field'}
]

Você pode ter uma lista de permissões por nome exato ou por padrões fnmatch:

 # Django Config
Nplusone_whitelist = [
    {'Model': 'MyApp.*'}
]

Para suprimir as notificações localmente, use o ignore Context Manager:

 de sinais de importação de Nplusone.core

com sinais.ignore (sinals.lazy_load):
    # linhas de carga preguiçosa
    # ...

Licença

MIT licenciado. Consulte o arquivo de licença em pacote para obter mais detalhes.