Metadata-Version: 2.1
Name: hypothesis-mongoengine
Version: 2.0.0
Summary: Hypothesis strategy for MongoEngine models
Author-email: George Macon <george.macon@gmail.com>
Project-URL: Source, https://github.com/gmacon/hypothesis-mongoengine
Project-URL: Issues, https://github.com/gmacon/hypothesis-mongoengine/issues
Project-URL: Changelog, https://github.com/gmacon/hypothesis-mongoengine/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Framework :: Hypothesis
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: hypothesis
Requires-Dist: mongoengine
Provides-Extra: dev
Requires-Dist: ruff ; extra == 'dev'
Provides-Extra: tests
Requires-Dist: pytest ; extra == 'tests'

Hypothesis Strategy for MongoEngine
===================================

This package contains a `Hypothesis <http://hypothesis.works/>`_ strategy
for generating example documents from a `MongoEngine <http://mongoengine.org/>`_ model.

Here's a minimal example:

.. code:: python

    from hypothesis import given
    from hypothesis_mongoengine.strategies import documents
    from mongoengine import Document, StringField


    class Foo(Document):
        foo = StringField()


    @given(documents(Foo))
    def test_something(foo):
        assert hasattr(foo, 'id')


You can customize the generation of examples by passing alternate strategies
for each field as keyword arguments:

.. code:: python

    @given(documents(Foo, foo=strategies.strings(max_size=7)))
    def test_another thing(foo):
        pass

By default, all examples that would validate against
the built-in MongoEngine restrictions are generated.
If the field is not required, ``None`` will also be generated.
If ``choices`` is specified, only those values will be generated.

If ``validation`` is specified, the default strategy will be filtered by the validation function.
If the custom validation function accepts too few values, Hypothesis may fail the health check.
In that case, supply a custom validator that generates acceptable examples more efficiently.

Depending on the level of control you have over the models,
it might be useful to infer everything *except* whether or not a field is required.
In that cause, you can use the provided ``field_values`` strategy
but provide ``required=True`` as a keyword argument.

What's Not Supported
--------------------

``ReferenceField`` is not generically supported and probably will never be.
You can, and should, provide an application-specific strategy for these fields.
This permits you to ensure that the referential-integrity constraints
needed by your application are satisfied.
Don't forget that MongoEngine expects the documents to have been saved to the database
before you try to reference them.
You can use the ``hypothesis_mongoengine.helpers.mark_saved`` function
to make a document appear as if saved.

``DictField`` is not generically supported and probably will never be.
``MapField`` is supported generically and should be preferred to ``DictField``
when the values are homogenous.
When writing custom strategies for a ``DictField``,
you can use the ``hypothesis_mongoengine.strategies.mongodb_keys`` strategy
to generate the keys in the absence of more specific application knowledge about the keys.

``DynamicDocument`` (and ``DynamicEmbeddedDocument``) currently generate
only the explicitly-specified fields.

``DynamicField`` is normally used internally by ``DynamicDocument``,
but if you have a model which references it explicitly, it won't be handled generically.

Handling Custom Fields
----------------------

If you have a custom field in use in your application,
you can register a strategy to generate examples for it using the ``field_strategy`` decorator.

For example, a strategy for the ``EnumField``
from `extras-mongoengine <https://github.com/MongoEngine/extras-mongoengine>`_
could look like this:

.. code:: python

    from extras_mongoengine.fields import EnumField
    from hypothesis import strategies
    from hypothesis_mongoengine.strategies import field_strategy

    @field_strategy(EnumField)
    def my_custom_strat(field):
        return strategies.sampled_from(field.enum)

The fields are looked up in the registry by equality of the classes,
so if you have a hierarchy of custom fields, you must register the leaf types.
You can, however, stack the decorator several times if you need to:

.. code:: python

    from extras_mongoengine.fields import EnumField, IntEnumField, StringEnumField
    from hypothesis import strategies
    from hypothesis_mongoengine.strategies import field_strategy

    @field_strategy(EnumField)
    @field_strategy(IntEnumField)
    @field_strategy(StringEnumField)
    def my_custom_strat(field):
        return strategies.sampled_from(field.enum)
