Skip to main content

SQLAlchemy mock helpers.

Project description

alchemy bottle icon

mock-alchemy

Simple and intuitive SQLAlchemy mock helpers.



🤖 Mocking SQLAlchemy

SQLAlchemy is awesome.

Unittests are great.

Accessing DB during tests - not so much. This library provides an easy way to mock SQLAlchemy's session in unittests while preserving the ability to do sane asserts.

📚 Documentation

Full documentation is available at http://mock-alchemy.rtfd.io/. On the documentation, you should be able to select a version of your choice in order to view documentation of an older version if need be.

This README includes some basic examples, but more detailed examples are included in the documentation, especially in the user guide. If you are looking for an API reference, it is also available on the documentation.

📦 Installing

You can install mock-alchemy using pip:

$ pip install mock-alchemy

If you want to use this package on Python 2.7 or Python 3.6, then install mock-alchemy using:

$ pip install "mock-alchemy>=0.1.0,<0.2.0"

Pip should auto-detect the correct version but this ensures the correct version is downloaded for your needs.

🔖 Versioning

There are several different versions of mock-alchemy available depending on your needs. The versions 0.1.x are available for use on Python 2.7, Python 3.6+. The newer versions serve users who are on Python 3.7+. For people interested in contributing, if you want to work on Python 2.7 version checkout the branch 0.1.x and then create pull-requests to that branch. There is a set of specific tests run for that branch on pushes and pull-requests since there are different tests for the newer versions of mock-alchemy. Check out contributor guide for more information.

Documentation for the 0.1.0 version is available. However, the current documentation should do a sufficient job at illustrating both the past and the features of the present version at least as of now. Therefore, I suggest using the most recent documentation for now, and if you want, you can switch using the readthedocs version system (click on the drop-down menu on the bottom right of the screen on the documentation or go to the project page).

📤 Credit

The original library (alchemy-mock) was created by Miroslav Shubernetskiy and Serkan Hoscai. This is a forked version due to a lack of updates in the original library. It appeared that the alchemy-mock project was no longer supported. Therefore, since I desired to add some basic support for deleting, I created my own version of the library.

Full credit goes to the original creators for starting and building this project. You can find the original package on PyPi and Github.

⚙ Using

Normally SQLAlchemy's expressions cannot be easily compared as comparison on binary expression produces yet another binary expression:

>>> type((Model.foo == 5) == (Model.bar == 5))
<class 'sqlalchemy.sql.elements.BinaryExpression'>

But they can be compared with this library:

>>> ExpressionMatcher(Model.foo == 5) == (Model.bar == 5)
False

ExpressionMatcher can be directly used:

>>> from mock_alchemy.comparison import ExpressionMatcher
>>> ExpressionMatcher(Model.foo == 5) == (Model.foo == 5)
True

Alternatively AlchemyMagicMock can be used to mock out SQLAlchemy session:

>>> from mock_alchemy.mocking import AlchemyMagicMock
>>> session = AlchemyMagicMock()
>>> session.query(Model).filter(Model.foo == 5).all()

>>> session.query.return_value.filter.assert_called_once_with(Model.foo == 5)

In real world though session can be interacted with multiple times to query some data. In those cases UnifiedAlchemyMagicMock can be used which combines various calls for easier assertions:

>>> from mock_alchemy.mocking import UnifiedAlchemyMagicMock
>>> session = UnifiedAlchemyMagicMock()

>>> m = session.query(Model)
>>> q = m.filter(Model.foo == 5)
>>> if condition:
...     q = q.filter(Model.bar > 10).all()
>>> data1 = q.all()
>>> data2 = m.filter(Model.note == 'hello world').all()

>>> session.filter.assert_has_calls([
...     mock.call(Model.foo == 5, Model.bar > 10),
...     mock.call(Model.note == 'hello world'),
... ])

Also real-data can be stubbed by criteria:

>>> from mock_alchemy.mocking import UnifiedAlchemyMagicMock
>>> session = UnifiedAlchemyMagicMock(data=[
...     (
...         [mock.call.query(Model),
...          mock.call.filter(Model.foo == 5, Model.bar > 10)],
...         [Model(foo=5, bar=11)]
...     ),
...     (
...         [mock.call.query(Model),
...          mock.call.filter(Model.note == 'hello world')],
...         [Model(note='hello world')]
...     ),
...     (
...         [mock.call.query(AnotherModel),
...          mock.call.filter(Model.foo == 5, Model.bar > 10)],
...         [AnotherModel(foo=5, bar=17)]
...     ),
... ])
>>> session.query(Model).filter(Model.foo == 5).filter(Model.bar > 10).all()
[Model(foo=5, bar=11)]
>>> session.query(Model).filter(Model.note == 'hello world').all()
[Model(note='hello world')]
>>> session.query(AnotherModel).filter(Model.foo == 5).filter(Model.bar > 10).all()
[AnotherModel(foo=5, bar=17)]
>>> session.query(AnotherModel).filter(Model.note == 'hello world').all()
[]

The UnifiedAlchemyMagicMock can partially fake session mutations such as session.add(instance). For example:

>>> session = UnifiedAlchemyMagicMock()
>>> session.add(Model(pk=1, foo='bar'))
>>> session.add(Model(pk=2, foo='baz'))
>>> session.query(Model).all()
[Model(foo='bar'), Model(foo='baz')]
>>> session.query(Model).get(1)
Model(foo='bar')
>>> session.query(Model).get(2)
Model(foo='baz')

Note that its partially correct since if added models are filtered on, session is unable to actually apply any filters so it returns everything:

>>> session.query(Model).filter(Model.foo == 'bar').all()
[Model(foo='bar'), Model(foo='baz')]

Finally, UnifiedAlchemyMagicMock can partially fake deleting. Anything that can be accessed with all can also be deleted. For example:

>>> s = UnifiedAlchemyMagicMock()
>>> s.add(SomeClass(pk1=1, pk2=1))
>>> s.add_all([SomeClass(pk1=2, pk2=2)])
>>> s.query(SomeClass).all()
[1, 2]
>>> s.query(SomeClass).delete()
2
>>> s.query(SomeClass).all()
[]

Note the limitation for dynamic sessions remains the same. Additionally, the delete will not be propagated across queries (only unified in the exact same query). As in, if there are multiple queries in which the 'same' object is present, this library considers them separate objects. For example:

>>> s = UnifiedAlchemyMagicMock(data=[
...     (
...         [mock.call.query('foo'),
...          mock.call.filter(c == 'one', c == 'two')],
...         [SomeClass(pk1=1, pk2=1), SomeClass(pk1=2, pk2=2)]
...     ),
...     (
...         [mock.call.query('foo'),
...          mock.call.filter(c == 'one', c == 'two'),
...          mock.call.order_by(c)],
...         [SomeClass(pk1=2, pk2=2), SomeClass(pk1=1, pk2=1)]
...     ),
...     (
...         [mock.call.filter(c == 'three')],
...         [SomeClass(pk1=3, pk2=3)]
...     ),
...     (
...         [mock.call.query('foo'),
...          mock.call.filter(c == 'one', c == 'two', c == 'three')],
...         [SomeClass(pk1=1, pk2=1), SomeClass(pk1=2, pk2=2), SomeClass(pk1=3, pk2=3)]
...     ),
... ])

>>> s.query('foo').filter(c == 'three').delete()
1
>>> s.query('foo').filter(c == 'three').all()
[]
>>> s.query('foo').filter(c == 'one').filter(c == 'two').filter(c == 'three').all()
[1, 2, 3]

The item referred to by c == 'three' is still present in the filtered query despite the individual item being deleted.

👷 Contributing

Contributions are welcome. To learn more, see the Contributor Guide.

📕 License

Distributed under the terms of the MIT license, mock-alchemy is free and open source software.

💥 Issues

If you encounter any issues or problems, please file an issue along with a detailed description.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mock_alchemy-0.2.6.tar.gz (17.4 kB view details)

Uploaded Source

Built Distribution

mock_alchemy-0.2.6-py3-none-any.whl (16.4 kB view details)

Uploaded Python 3

File details

Details for the file mock_alchemy-0.2.6.tar.gz.

File metadata

  • Download URL: mock_alchemy-0.2.6.tar.gz
  • Upload date:
  • Size: 17.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.1 CPython/3.8.16 Linux/5.15.0-1034-azure

File hashes

Hashes for mock_alchemy-0.2.6.tar.gz
Algorithm Hash digest
SHA256 807cc2bd7f658fb98292900052eaa6eeb4a65b2d62364e639462480a275299ef
MD5 b1378b63003f6ee48393b9e6e2ae7ff7
BLAKE2b-256 a7805af6036ed9a97d927c36384b63ea2f270224726cda7f1402cb62781d7054

See more details on using hashes here.

File details

Details for the file mock_alchemy-0.2.6-py3-none-any.whl.

File metadata

  • Download URL: mock_alchemy-0.2.6-py3-none-any.whl
  • Upload date:
  • Size: 16.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.1 CPython/3.8.16 Linux/5.15.0-1034-azure

File hashes

Hashes for mock_alchemy-0.2.6-py3-none-any.whl
Algorithm Hash digest
SHA256 d5e17f2c92d0299d70cd9a0d3c8f96f759a81c285c76b03f4192451583bf865f
MD5 3c1774ced5f6bacab94c6b407def08a7
BLAKE2b-256 aa938d1f7ee9fa858d1c13511de6e0bedf7f57d15e9c7aab0e9fdf4d66074417

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page