Merge pull request #136 from ets-labs/deprecate_inject_decorator

Deprecate inject decorator

Author: rmk135

README.rst

@@ -62,6 +62,8 @@ system that consists from several business and platform services:
 
  import sqlite3
  import boto.s3.connection
+
+ import example.main
  import example.services
 
  import dependency_injector.containers as containers
@@ -92,29 +94,38 @@ system that consists from several business and platform services:
  db=Platform.database,
  s3=Platform.s3)
 
-Next example demonstrates usage of ``@inject`` decorator with IoC containers 
-defined above: 
 
-.. code-block:: python
+ class Application(containers.DeclarativeContainer):
+ """IoC container of application component providers."""
 
- """Dependency Injector @inject decorator example."""
+ main = providers.Callable(example.main.main,
+ users_service=Services.users,
+ auth_service=Services.auth,
+ photos_service=Services.photos)
 
- import application
- import dependency_injector.injections as injections
+Next example demonstrates usage of IoC containers & providers defined above:
 
+.. code-block:: python
 
- @injections.inject(users_service=application.Services.users)
- @injections.inject(auth_service=application.Services.auth)
- @injections.inject(photos_service=application.Services.photos)
- def main(users_service, auth_service, photos_service):
- """Main function."""
- user = users_service.get_user('user')
- auth_service.authenticate(user, 'secret')
- photos_service.upload_photo(user['id'], 'photo.jpg')
+ """Run example application."""
+
+ import containers
 
 
  if __name__ == '__main__':
- main()
+ containers.Application.main()
+
+ # Previous call is an equivalent of next operations:
+ #
+ # database = sqlite3.connect(':memory:')
+ # s3 = boto.s3.connection.S3Connection(aws_access_key_id='KEY',
+ # aws_secret_access_key='SECRET')
+ #
+ # example.main.main(users_service=example.services.Users(db=database),
+ # auth_service=example.services.Auth(db=database,
+ # token_ttl=3600),
+ # photos_service=example.services.Photos(db=database,
+ # s3=s3))
  
 Alternative definition styles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -136,21 +147,6 @@ IoC containers from previous example could look like these:
  .add_kwargs(aws_access_key_id='KEY',
  aws_secret_access_key='SECRET')
 
-
- class Services(containers.DeclarativeContainer):
- """IoC container of business service providers."""
-
- users = providers.Factory(example.services.Users) \
- .add_kwargs(db=Platform.database)
-
- auth = providers.Factory(example.services.Auth) \
- .add_kwargs(db=Platform.database,
- token_ttl=3600)
-
- photos = providers.Factory(example.services.Photos) \
- .add_kwargs(db=Platform.database,
- s3=Platform.s3)
-
 or like this these:
 
 .. code-block:: python
@@ -165,21 +161,6 @@ or like this these:
  s3.add_kwargs(aws_access_key_id='KEY',
  aws_secret_access_key='SECRET')
 
-
- class Services(containers.DeclarativeContainer):
- """IoC container of business service providers."""
-
- users = providers.Factory(example.services.Users)
- users.add_kwargs(db=Platform.database)
-
- auth = providers.Factory(example.services.Auth)
- auth.add_kwargs(db=Platform.database,
- token_ttl=3600)
-
- photos = providers.Factory(example.services.Photos)
- photos.add_kwargs(db=Platform.database,
- s3=Platform.s3)
-
 You can get more *Dependency Injector* examples in ``/examples`` directory on
 GitHub:
 

dependency_injector/injections.py

@@ -1,5 +1,7 @@
 """Dependency injector injections module."""
 
+import warnings
+
 import six
 
 from dependency_injector.providers.base import (
@@ -13,6 +15,13 @@
 def inject(*args, **kwargs):
  """Dependency injection decorator.
 
+ .. warning::
+
+ :py:func:`inject` decorator has been deprecated since version 2.2.0.
+
+ Usage of :py:func:`inject` decorator can lead to bad design and could
+ be considered as anti-pattern.
+
  :py:func:`inject` decorator can be used for making inline dependency
  injections. It patches decorated callable in such way that dependency
  injection will be done during every call of decorated callable.
@@ -41,6 +50,10 @@ class SomeClass(object):
  def __init__(self, arg1, arg2):
  pass
 
+ .. deprecated:: 2.2.0
+ Usage of :py:func:`inject` decorator can lead to bad design and could
+ be considered as anti-pattern.
+
  :param args: Tuple of context positional arguments.
  :type args: tuple[object]
 
@@ -50,6 +63,11 @@ def __init__(self, arg1, arg2):
  :return: Class / callable decorator
  :rtype: (callable) -> (type | callable)
  """
+ warnings.warn(message='Call to a deprecated decorator - @{0}.{1}'
+ .format(inject.__module__, inject.__name__),
+ category=DeprecationWarning,
+ stacklevel=2)
+
  arg_injections = _parse_positional_injections(args)
  kwarg_injections = _parse_keyword_injections(kwargs)
 

docs/advanced_usage/index.rst

@@ -9,6 +9,10 @@ Current section of documentation describes advanced usage of
 
 .. currentmodule:: dependency_injector.injections
 
+.. warning::
+
+ :py:func:`inject` decorator has been deprecated since version 2.2.0.
+
 :py:func:`inject` decorator is a part of 
 :py:mod:`dependency_injector.injections` module.
 

docs/api/index.rst

@@ -7,6 +7,5 @@ API Documentation
  top_level
  providers
  containers
- injections
  utils
  errors

docs/examples/index.rst

@@ -9,8 +9,8 @@ Examples
  "Dependency Injector" framework.
 
 Current section of documentation is designed to provide several example mini 
-applications that are built on the top of inversion of control principle and 
-powered by *Dependency Injector* framework.
+applications that are built according to the inversion of control principle 
+and powered by *Dependency Injector* framework.
 
 .. toctree::
  :maxdepth: 2

docs/examples/movie_lister.rst

@@ -20,14 +20,14 @@ Like Martin says:
 
 While original Martin's MovieLister example was a bit modified here, it 
 makes sense to provide some description. So, the idea of this example is to 
-create ``movies`` library that can be configurable to work with different 
-movie databases (csv, sqlite) and provide 2 main features:
+create ``movies`` library that can be configured to work with different 
+movie databases (csv, sqlite, etc...) and provide 2 main features:
 
 1. List all movies that were directed by certain person.
 2. List all movies that were released in certain year.
 
 Also this example contains 3 mini applications that are based on ``movies`` 
-library :
+library:
 
 1. ``app_csv.py`` - list movies by certain criteria from csv file database.
 2. ``app_db.py`` - list movies by certain criteria from sqlite database.
@@ -38,8 +38,6 @@ Instructions for running:
 
 .. code-block:: bash
 
- python create_db.py
-
  python app_csv.py
  python app_db.py
  python app_db_csv.py
@@ -74,6 +72,30 @@ Listing of ``movies/__init__.py``:
  :language: python
  :linenos:
 
+Example application
+~~~~~~~~~~~~~~~~~~~
+
+Example application structure:
+
+.. code-block:: bash
+
+ /example
+ /__init__.py
+ /db.py
+ /main.py
+
+Listing of ``examples/main.py``:
+
+.. literalinclude:: ../../examples/miniapps/movie_lister/example/main.py
+ :language: python
+ :linenos:
+
+Listing of ``examples/db.py``:
+
+.. literalinclude:: ../../examples/miniapps/movie_lister/example/db.py
+ :language: python
+ :linenos:
+
 Csv application
 ~~~~~~~~~~~~~~~
 

docs/index.rst

@@ -59,7 +59,6 @@ Contents
  main/installation
  providers/index
  containers/index
- advanced_usage/index
  examples/index
  api/index
  main/feedback

docs/main/changelog.rst

@@ -9,7 +9,7 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
-- No features.
+- Deprecate ``inject`` decorator.
 
 2.1.1
 -----

examples/miniapps/movie_lister/README.rst

@@ -11,8 +11,6 @@ Instructions for running:
 
 .. code-block:: bash
 
- python create_db.py
-
  python app_csv.py
  python app_db.py
  python app_db_csv.py

examples/miniapps/movie_lister/app_csv.py

@@ -9,42 +9,40 @@
 csv file movies database.
 """
 
-import dependency_injector.containers as containers
-import dependency_injector.providers as providers
-import dependency_injector.injections as injections
-
 import movies
 import movies.finders
 
+import example.db
+import example.main
+
 import settings
 
+import dependency_injector.containers as containers
+import dependency_injector.providers as providers
+
 
 @containers.override(movies.MoviesModule)
 class MyMoviesModule(containers.DeclarativeContainer):
  """IoC container for overriding movies module component providers."""
 
  movie_finder = providers.Factory(movies.finders.CsvMovieFinder,
- csv_file=settings.MOVIES_CSV_PATH,
- delimeter=',',
+ csv_file_path=settings.MOVIES_CSV_PATH,
+ delimiter=',',
  **movies.MoviesModule.movie_finder.kwargs)
 
 
-@injections.inject(movies.MoviesModule.movie_lister)
-def main(movie_lister):
- """Main function.
-
- This program prints info about all movies that were directed by different
- persons and then prints all movies that were released in 2015.
+class CsvApplication(containers.DeclarativeContainer):
+ """IoC container of csv application component providers."""
 
- :param movie_lister: Movie lister instance
- :type movie_lister: movies.listers.MovieLister
- """
- print movie_lister.movies_directed_by('Francis Lawrence')
- print movie_lister.movies_directed_by('Patricia Riggen')
- print movie_lister.movies_directed_by('JJ Abrams')
+ main = providers.Callable(example.main.main,
+ movie_lister=movies.MoviesModule.movie_lister)
 
- print movie_lister.movies_released_in(2015)
+ init_db = providers.Callable(example.db.init_csv,
+ movies_data=settings.MOVIES_SAMPLE_DATA,
+ csv_file_path=settings.MOVIES_CSV_PATH,
+ delimiter=',')
 
 
 if __name__ == '__main__':
- main()
+ CsvApplication.init_db()
+ CsvApplication.main()