nplusone 1.0.0

任何人获得此软件及其相关文档文件（“软件”）的副本，均可免费使用。
在不受限制的情况下处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件的副本，并允许软件的提供方进行此类操作，但需遵守以下条件：
上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。
软件按“原样”提供，不提供任何形式的保证，无论是明示的还是暗示的，包括但不限于适销性、特定用途的适用性和非侵权性。
在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该责任是基于合同、侵权或其他原因，以及与软件或其使用或其他操作相关。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。

软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。

本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。
本软件的使用或操作引起的任何索赔，无论该责任是基于合同、侵权或其他原因，作者或版权所有者均不承担责任。

描述： ========
nplusone
========

.. image:: https://img.shields.io/pypi/v/nplusone.svg
:target: http://badge.fury.io/py/nplusone
:alt: 最新版本

.. image:: https://img.shields.io/travis/jmcarp/nplusone/master.svg
:target: https://travis-ci.org/jmcarp/nplusone
:alt: Travis-CI

.. image:: https://img.shields.io/codecov/c/github/jmcarp/nplusone/master.svg
:target: https://codecov.io/github/jmcarp/nplusone
:alt: 代码覆盖率

nplusone 是一个用于检测Python ORM（包括 SQLAlchemy、Peewee 和 Django ORM）中 n+1 查询问题的库。

问题：
===========

许多对象关系映射（ORM）库默认采用懒加载来处理关系。当相关行很少被访问时，这种模式可以非常高效，但随着关系的频繁访问，它很快就会变得低效。在这些情况下，使用 `JOIN` 一次性加载相关行可以大大提高性能。不幸的是，理解何时使用懒加载与 eager 加载可能很具挑战性：你可能直到应用速度减慢到几乎停止时才会注意到问题。

``nplusone`` 是一个 ORM 性能分析工具，用于诊断和改进由于不适当的懒加载引起的性能问题。``nplusone`` 监控使用 Django 或 SQLAlchemy 的应用程序，并在发出可能昂贵的懒加载时发送通知。它可以识别引起问题的关系属性和背后的特定代码行，并推荐改进性能的修复方法。

``nplusone`` 还会检测 Flask-SQLAlchemy 和 Django ORM 中的不适当 eager 加载，在当前请求中相关数据被 eager 加载但从未被访问时发出警告。

安装
============

::

pip install -U nplusone

nplusone 支持 Python >= 2.7 或 >= 3.3。

使用
=====

注意：``nplusone`` 应仅用于开发，不应部署到生产环境。

Django
******

注意：``nplusone`` 支持 Django >= 1.8。

将 ``nplusone`` 添加到 ``INSTALLED_APPS``: :

INSTALLED_APPS = (
...
'nplusone.ext.django',
)

添加 ``NPlusOneMiddleware``: :

MIDDLEWARE = (
'nplusone.ext.django.NPlusOneMiddleware',
...
)

可选配置日志设置： :

NPLUSONE_LOGGER = logging.getLogger('nplusone')
NPLUSONE_LOG_LEVEL = logging.WARN

配置日志处理器： :

LOGGING = {
'version': 1,
'handlers': {
'console': {
'class': 'logging.StreamHandler',
},
},
'loggers': {
'nplusone': {
'handlers': ['console'],
'level': 'WARN',
},
},
}

当你的应用以懒加载方式加载数据时，``nplusone`` 将发出一条日志消息： :

检测到在 `<model>.<field>` 上的潜在 n+1 查询

在这种情况下，考虑使用 `select_related <https://docs.django.ac.cn/en/1.8/ref/models/querysets/#select-related>`_ 或 `prefetch_related <https://docs.django.ac.cn/en/1.8/ref/models/querysets/#prefetch-related>`_。

当你的应用急切地加载相关数据但从未访问时，``nplusone`` 将记录一条警告： :

检测到在 `<model>.<field>` 上的潜在不必要的急切加载

Flask-SQLAlchemy
****************

使用 ``NPlusOne`` 包装应用程序： :

from flask import Flask
from nplusone.ext.flask_sqlalchemy import NPlusOne

app = Flask(__name__)
NPlusOne(app)

可选配置日志设置： :

app = Flask(__name__)
app.config['NPLUSONE_LOGGER'] = logging.getLogger('app.nplusone')
app.config['NPLUSONE_LOG_LEVEL'] = logging.ERROR
NPlusOne(app)

当你的应用以懒加载方式加载数据时，``nplusone`` 将发出一条日志消息： :

检测到在 `<model>.<field>` 上的潜在 n+1 查询

在这种情况下，考虑使用 ``subqueryload`` 或 ``joinedload``；有关完整文档，请参阅 SQLAlchemy 的 `关系加载 <https://docs.sqlalchemy.org.cn/en/latest/orm/loading_relationships.html>`_ 指南。

当你的应用急切地加载相关数据但从未访问时，``nplusone`` 将记录一条警告： :

检测到在 `<model>.<field>` 上的潜在不必要的急切加载

WSGI
****

对于遵循 WSGI 规范的其他框架，使用 `NPlusOneMiddleware` 包装你的应用程序。你还必须导入适用于你的 ORM 的相关 ``nplusone`` 扩展： :

import bottle
from nplusone.ext.wsgi import NPlusOneMiddleware
import nplusone.ext.sqlalchemy

app = NPlusOneMiddleware(bottle.app())

通用
*******

上述集成与请求-响应周期相关联。要在 HTTP 请求之外使用 ``nplusone``，请使用 `Profiler` 上下文管理器：你还必须导入适用于你的 ORM 的相关 ``nplusone`` 扩展： :

from nplusone.core import profiler
import nplusone.ext.sqlalchemy

with profiler.Profiler()
...

自定义通知
*************************

默认情况下，``nplusone`` 使用名为 "nplusone" 的记录器记录所有潜在不必要的查询。当设置 `NPLUSONE_RAISE` 配置选项时，``nplusone`` 还将引发一个 ``NPlusOneError``。这可以用来强制所有涉及不必要的查询的自动测试失败。 :

# Django 配置
NPLUSONE_RAISE = True

# Flask 配置
app.config['NPLUSONE_RAISE'] = True

如果需要，还可以使用 ``NPLUSONE_ERROR`` 选项指定异常类型。

忽略通知
**********************

要全局忽略 ``nplusone`` 的通知，请使用 `NPLUSONE_WHITELIST` 选项配置白名单： :

# Django 配置
NPLUSONE_WHITELIST = [
{'label': 'n_plus_one', 'model': 'myapp.MyModel'}
]

Flask-SQLAlchemy 配置
app.config['NPLUSONE_WHITELIST'] = [
{'label': 'unused_eager_load', 'model': 'MyModel', 'field': 'my_field'}
]

您可以通过精确名称或使用 `fnmatch` 模式来白名单模型：

# Django 配置
NPLUSONE_WHITELIST = [
{'model': 'myapp.*'}
]

要局部抑制通知，请使用 `ignore` 上下文管理器：

from nplusone.core import signals

with signals.ignore(signals.lazy_load)
延迟加载行
# ...

许可证
=======

MIT 许可。有关详细信息，请参阅附带的 `LICENSE `_ 文件。

关键词：nplusone
平台：未知
分类：开发状态 :: 2 - 预_alpha
分类：目标受众 :: 开发者
分类：许可证 :: OSI 批准 :: MIT 许可证
分类：自然语言 :: 英语
分类：编程语言 :: Python :: 2
分类：编程语言 :: Python :: 2.7
分类：编程语言 :: Python :: 3
分类：编程语言 :: Python :: 3.3
分类：编程语言 :: Python :: 3.4
分类：编程语言 :: Python :: 3.5
分类：编程语言 :: Python :: 3.6