From 8274b495fe034b56aead611260d50f739e1cedb9 Mon Sep 17 00:00:00 2001
From: Konsta Vesterinen <konsta.vesterinen@gmail.com>
Date: Fri, 22 Aug 2014 13:20:56 +0300
Subject: [PATCH] Add quote utility function

---
 CHANGES.rst                            |  6 ++++++
 docs/orm_helpers.rst                   |  6 ++++++
 setup.py                               |  2 +-
 sqlalchemy_utils/__init__.py           |  2 +-
 sqlalchemy_utils/functions/__init__.py |  2 ++
 sqlalchemy_utils/functions/orm.py      | 25 +++++++++++++++++++++++++
 tests/functions/test_quote.py          | 14 ++++++++++++++
 7 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 tests/functions/test_quote.py

diff --git a/CHANGES.rst b/CHANGES.rst
index 0d1d3a7..9e04f05 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.12 (2014-08-22)
+^^^^^^^^^^^^^^^^^^^^
+
+- Added quote utility function
+
+
 0.26.11 (2014-08-21)
 ^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/orm_helpers.rst b/docs/orm_helpers.rst
index 41918d7..443fb58 100644
--- a/docs/orm_helpers.rst
+++ b/docs/orm_helpers.rst
@@ -82,6 +82,12 @@ naturally_equivalent
 .. autofunction:: naturally_equivalent
 
 
+quote
+^^^^^
+
+.. autofunction:: quote
+
+
 sort_query
 ^^^^^^^^^^
 
diff --git a/setup.py b/setup.py
index 97d9c85..f61b809 100644
--- a/setup.py
+++ b/setup.py
@@ -44,7 +44,7 @@ for name, requirements in extras_require.items():
 
 setup(
     name='SQLAlchemy-Utils',
-    version='0.26.11',
+    version='0.26.12',
     url='https://github.com/kvesteri/sqlalchemy-utils',
     license='BSD',
     author='Konsta Vesterinen, Ryan Leckey, Janne Vanhala, Vesa Uimonen',
diff --git a/sqlalchemy_utils/__init__.py b/sqlalchemy_utils/__init__.py
index af701c5..55ce5c0 100644
--- a/sqlalchemy_utils/__init__.py
+++ b/sqlalchemy_utils/__init__.py
@@ -75,7 +75,7 @@ from .types import (
 from .models import Timestamp
 
 
-__version__ = '0.26.11'
+__version__ = '0.26.12'
 
 
 __all__ = (
diff --git a/sqlalchemy_utils/functions/__init__.py b/sqlalchemy_utils/functions/__init__.py
index cffcb98..c5ff1f9 100644
--- a/sqlalchemy_utils/functions/__init__.py
+++ b/sqlalchemy_utils/functions/__init__.py
@@ -33,6 +33,7 @@ from .orm import (
     has_changes,
     identity,
     naturally_equivalent,
+    quote,
     table_name,
 )
 
@@ -64,6 +65,7 @@ __all__ = (
     'naturally_equivalent',
     'non_indexed_foreign_keys',
     'QuerySorterException',
+    'quote',
     'render_expression',
     'render_statement',
     'sort_query',
diff --git a/sqlalchemy_utils/functions/orm.py b/sqlalchemy_utils/functions/orm.py
index 7157815..92705db 100644
--- a/sqlalchemy_utils/functions/orm.py
+++ b/sqlalchemy_utils/functions/orm.py
@@ -333,6 +333,31 @@ def remote_column_names(prop):
                     yield remote.name
 
 
+def quote(mixed, ident):
+    """
+    Conditionally quote an identifier.
+    ::
+
+
+        from sqlalchemy_utils import quote
+
+
+        engine = create_engine('sqlite:///:memory:')
+
+        quote(engine, 'order')
+        # '"order"'
+
+        quote(engine, 'some_other_identifier')
+        # 'some_other_identifier'
+
+
+    :param mixed: SQLAlchemy Session / Connection / Engine object.
+    :param ident: identifier to conditionally quote
+    """
+    dialect = get_bind(mixed).dialect
+    return dialect.preparer(dialect).quote(ident)
+
+
 def query_labels(query):
     """
     Return all labels for given SQLAlchemy query object.
diff --git a/tests/functions/test_quote.py b/tests/functions/test_quote.py
new file mode 100644
index 0000000..4d86b3f
--- /dev/null
+++ b/tests/functions/test_quote.py
@@ -0,0 +1,14 @@
+from sqlalchemy_utils.functions import quote
+from tests import TestCase
+
+
+class TestQuote(TestCase):
+    def test_quote_with_preserved_keyword(self):
+        assert quote(self.connection, 'order') == '"order"'
+        assert quote(self.session, 'order') == '"order"'
+        assert quote(self.engine, 'order') == '"order"'
+
+    def test_quote_with_non_preserved_keyword(self):
+        assert quote(self.connection, 'some_order') == 'some_order'
+        assert quote(self.session, 'some_order') == 'some_order'
+        assert quote(self.engine, 'some_order') == 'some_order'