From f3ca03e569ac042b47694b12c1b72ee527ab9657 Mon Sep 17 00:00:00 2001
From: Roman Mogylatov <rmogilatov@gmail.com>
Date: Thu, 22 Oct 2020 11:41:15 -0400
Subject: [PATCH] Add example and docs

---
 docs/containers/overriding.rst                | 16 ++++++++++++
 .../declarative_override_decorator.py         | 25 +++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 examples/containers/declarative_override_decorator.py

diff --git a/docs/containers/overriding.rst b/docs/containers/overriding.rst
index 3d1a7030..b0966cad 100644
--- a/docs/containers/overriding.rst
+++ b/docs/containers/overriding.rst
@@ -21,4 +21,20 @@ The container also has:
 
 :py:class:`DynamicContainer` has the same functionality.
 
+Another possible way to override container providers on declarative level is
+``@containers.override()`` decorator:
+
+.. literalinclude:: ../../examples/containers/declarative_override_decorator.py
+   :language: python
+   :lines: 3-
+   :emphasize-lines: 12-16
+
+Decorator ``@containers.override()`` takes a container for overriding as an argument.
+This container providers will be overridden by the providers with the same names from
+the decorated container.
+
+It helps to change the behaviour of application by importing extension modules but not a code change.
+Imported module can override providers in main container. While the code uses main container as
+before, the overridden providers provide components defined in the extension module.
+
 .. disqus::
diff --git a/examples/containers/declarative_override_decorator.py b/examples/containers/declarative_override_decorator.py
new file mode 100644
index 00000000..8995cb13
--- /dev/null
+++ b/examples/containers/declarative_override_decorator.py
@@ -0,0 +1,25 @@
+"""Declarative container provider overriding with `@override()` decorator."""
+
+import sqlite3
+from unittest import mock
+
+from dependency_injector import containers, providers
+
+
+class Container(containers.DeclarativeContainer):
+
+    database = providers.Singleton(sqlite3.connect, ':memory:')
+
+
+# Overriding `Container` with `OverridingContainer`:
+@containers.override(Container)
+class OverridingContainer(containers.DeclarativeContainer):
+
+    database = providers.Singleton(mock.Mock)
+
+
+if __name__ == '__main__':
+    container = Container()
+
+    database = container.database()
+    assert isinstance(database, mock.Mock)