From 3eac18eb8e139bbf2e951a1f0dc43aa9b4348194 Mon Sep 17 00:00:00 2001
From: Konsta Vesterinen <konsta.vesterinen@gmail.com>
Date: Wed, 25 Jun 2014 14:50:44 +0300
Subject: [PATCH] Add has_any_changes function

---
 CHANGES.rst                             |  6 ++++++
 docs/orm_helpers.rst                    |  6 ++++++
 sqlalchemy_utils/__init__.py            |  4 ++++
 sqlalchemy_utils/functions/__init__.py  |  2 ++
 sqlalchemy_utils/functions/orm.py       | 28 +++++++++++++++++++++++++
 tests/functions/test_has_any_changes.py | 24 +++++++++++++++++++++
 6 files changed, 70 insertions(+)
 create mode 100644 tests/functions/test_has_any_changes.py

diff --git a/CHANGES.rst b/CHANGES.rst
index 997d014..72690d0 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -4,6 +4,12 @@ Changelog
 Here you can see the full list of changes between each SQLAlchemy-Utils release.
 
 
+0.26.3 (2014-06-25)
+^^^^^^^^^^^^^^^^^^^
+
+- Added has_any_changes
+
+
 0.26.2 (2014-05-29)
 ^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/orm_helpers.rst b/docs/orm_helpers.rst
index ad413ee..4e5323e 100644
--- a/docs/orm_helpers.rst
+++ b/docs/orm_helpers.rst
@@ -52,6 +52,12 @@ query_entities
 .. autofunction:: query_entities
 
 
+has_any_changes
+^^^^^^^^^^^^^^^
+
+.. autofunction:: has_any_changes
+
+
 has_changes
 ^^^^^^^^^^^
 
diff --git a/sqlalchemy_utils/__init__.py b/sqlalchemy_utils/__init__.py
index bc014d8..4e7dfe5 100644
--- a/sqlalchemy_utils/__init__.py
+++ b/sqlalchemy_utils/__init__.py
@@ -19,6 +19,8 @@ from .functions import (
     get_referencing_foreign_keys,
     get_tables,
     group_foreign_keys,
+    has_any_changes,
+    has_changes,
     has_index,
     identity,
     merge_references,
@@ -94,6 +96,8 @@ __all__ = (
     get_referencing_foreign_keys,
     get_tables,
     group_foreign_keys,
+    has_any_changes,
+    has_changes,
     has_index,
     identity,
     instrumented_list,
diff --git a/sqlalchemy_utils/functions/__init__.py b/sqlalchemy_utils/functions/__init__.py
index 93533d5..b7e6b89 100644
--- a/sqlalchemy_utils/functions/__init__.py
+++ b/sqlalchemy_utils/functions/__init__.py
@@ -26,6 +26,7 @@ from .orm import (
     get_primary_keys,
     get_tables,
     getdotattr,
+    has_any_changes,
     has_changes,
     identity,
     naturally_equivalent,
@@ -50,6 +51,7 @@ __all__ = (
     'get_tables',
     'getdotattr',
     'group_foreign_keys',
+    'has_any_changes',
     'has_changes',
     'identity',
     'is_auto_assigned_date_column',
diff --git a/sqlalchemy_utils/functions/orm.py b/sqlalchemy_utils/functions/orm.py
index 99ef536..c208f55 100644
--- a/sqlalchemy_utils/functions/orm.py
+++ b/sqlalchemy_utils/functions/orm.py
@@ -475,6 +475,7 @@ def has_changes(obj, attr):
 
     :param obj: SQLAlchemy declarative model object
     :param attr: Name of the attribute
+    .. seealso:: :func:`has_any_changes`
     """
     return (
         sa.inspect(obj)
@@ -485,6 +486,33 @@ def has_changes(obj, attr):
     )
 
 
+def has_any_changes(model, columns):
+    """
+    Simple shortcut function for checking if any of the given attributes of
+    given declarative model object have changes.
+
+
+    ::
+
+
+        from sqlalchemy_utils import has_any_changes
+
+
+        user = User()
+
+        has_any_changes(user, ('name', ))  # False
+
+        user.name = u'someone'
+
+        has_any_changes(user, ('name', 'age'))  # True
+
+
+    :param obj: SQLAlchemy declarative model object
+    :param attrs: Names of the attributes
+    """
+    return any(has_changes(model, column) for column in columns)
+
+
 def identity(obj_or_class):
     """
     Return the identity of given sqlalchemy declarative model class or instance
diff --git a/tests/functions/test_has_any_changes.py b/tests/functions/test_has_any_changes.py
new file mode 100644
index 0000000..2411e55
--- /dev/null
+++ b/tests/functions/test_has_any_changes.py
@@ -0,0 +1,24 @@
+import sqlalchemy as sa
+from sqlalchemy.ext.declarative import declarative_base
+
+from sqlalchemy_utils import has_any_changes
+
+
+class TestHasAnyChanges(object):
+    def setup_method(self, method):
+        Base = declarative_base()
+
+        class Article(Base):
+            __tablename__ = 'article_translation'
+            id = sa.Column(sa.Integer, primary_key=True)
+            title = sa.Column(sa.String(100))
+
+        self.Article = Article
+
+    def test_without_changed_attr(self):
+        article = self.Article()
+        assert not has_any_changes(article, ['title'])
+
+    def test_with_changed_attr(self):
+        article = self.Article(title='Some title')
+        assert has_any_changes(article, ['title', 'id'])