From ec6bd0c2c1c3924b619be906a95ea87883840937 Mon Sep 17 00:00:00 2001 From: Roman Mogilatov Date: Sat, 14 Nov 2015 22:47:33 +0200 Subject: [PATCH] Add API docs --- docs/api/catalogs.rst | 63 ++-------------------------- docs/api/errors.rst | 5 +++ docs/api/index.rst | 5 ++- docs/api/providers.rst | 9 +++- docs/api/top_level.rst | 6 +++ docs/api/utils.rst | 5 +++ docs/catalogs/declarative.rst | 19 +++++---- examples/catalogs/declarative.py | 13 +++--- examples/catalogs/declarative_api.py | 17 ++++---- 9 files changed, 55 insertions(+), 87 deletions(-) create mode 100644 docs/api/errors.rst create mode 100644 docs/api/top_level.rst create mode 100644 docs/api/utils.rst diff --git a/docs/api/catalogs.rst b/docs/api/catalogs.rst index b89dda38..ffabcac9 100644 --- a/docs/api/catalogs.rst +++ b/docs/api/catalogs.rst @@ -1,62 +1,7 @@ -dependency_injector.catalogs ----------------------------- +``dependency_injector.catalogs`` +-------------------------------- .. automodule:: dependency_injector.catalogs - - -Declarative catalog -------------------- - -.. autoclass:: DeclarativeCatalog - :member-order: bysource - :members: - - .. classmethod:: __getattr__(name) - - Return provider with specified name or raise en error. - - :param name: Attribute's name - :type name: str - - :raise: dependency_injector.UndefinedProviderError - - .. classmethod:: __setattr__(cls, name, value) - - Handle setting of catalog attributes. - - Setting of attributes works as usual, but if value of attribute is - provider, this provider will be bound to catalog correctly. - - :param name: Attribute's name - :type name: str - - :param value: Attribute's value - :type value: dependency_injector.Provider | object - - :rtype: None - - .. classmethod:: __delattr__(cls, name) - - Handle deleting of catalog attibute. - - Deleting of attributes works as usual, but if value of attribute is - provider, this provider will be unbound from catalog correctly. - - :param name: Attribute's name - :type name: str - - :rtype: None - - .. classmethod:: __repr__(cls, name) - - Return string representation of the catalog. - - :rtype: str - -Dynamic catalog ---------------- - -.. autoclass:: DynamicCatalog - :member-order: bysource - :members: + :members: :special-members: + :member-order: bysource diff --git a/docs/api/errors.rst b/docs/api/errors.rst new file mode 100644 index 00000000..c37ad8f7 --- /dev/null +++ b/docs/api/errors.rst @@ -0,0 +1,5 @@ +``dependency_injector.errors`` +------------------------------ + +.. automodule:: dependency_injector.errors + :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index 6c594ff6..3c9ca377 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -3,7 +3,10 @@ API .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + top_level providers catalogs + errors + utils diff --git a/docs/api/providers.rst b/docs/api/providers.rst index 759c4837..3573364f 100644 --- a/docs/api/providers.rst +++ b/docs/api/providers.rst @@ -1,3 +1,8 @@ -dependency_injector.providers ------------------------------ +``dependency_injector.providers`` +--------------------------------- +.. automodule:: dependency_injector.providers + :members: + :special-members: + :private-members: + :member-order: bysource diff --git a/docs/api/top_level.rst b/docs/api/top_level.rst new file mode 100644 index 00000000..e455f520 --- /dev/null +++ b/docs/api/top_level.rst @@ -0,0 +1,6 @@ +``dependency_injector`` +----------------------- + +.. automodule:: dependency_injector + :members: + :special-members: diff --git a/docs/api/utils.rst b/docs/api/utils.rst new file mode 100644 index 00000000..38ea3b70 --- /dev/null +++ b/docs/api/utils.rst @@ -0,0 +1,5 @@ +``dependency_injector.utils`` +----------------------------- + +.. automodule:: dependency_injector.utils + :members: diff --git a/docs/catalogs/declarative.rst b/docs/catalogs/declarative.rst index 32e6c626..58a7e681 100644 --- a/docs/catalogs/declarative.rst +++ b/docs/catalogs/declarative.rst @@ -1,13 +1,13 @@ Declarative catalogs -------------------- -``di.DeclarativeCatalog`` is a catalog of providers that could be defined in -declarative manner. It should cover most of the cases when list of providers -that would be included in catalog is deterministic (catalog will not change -its structure in runtime). +:py:class:`dependency_injector.catalogs.DeclarativeCatalog` is a catalog of +providers that could be defined in declarative manner. It should cover most +of the cases when list of providers that would be included in catalog is +deterministic (catalog will not change its structure in runtime). Declarative catalogs have to extend base declarative catalog class - -``di.DeclarativeCatalog``. +:py:class:`dependency_injector.catalogs.DeclarativeCatalog`. Providers have to be defined like catalog's class attributes. Every provider in catalog has name. This name should follow ``some_provider`` convention, @@ -15,7 +15,8 @@ that is standard naming convention for attribute names in Python. .. note:: - It might be useful to add such ``""":type: di.Provider -> Object1"""`` + It might be useful to add such + ``""":type: dependency_injector.providers.Provider -> Object1"""`` docstrings just on the next line after provider's definition. It will help code analyzing tools and IDE's to understand that variable above contains some callable object, that returns particular instance as a @@ -30,9 +31,9 @@ Here is an simple example of declarative catalog with several factories: .. literalinclude:: ../../examples/catalogs/declarative.py :language: python -``di.DeclarativeCatalog`` has several features that could be useful for some -kind of operations on catalog's providers (please visit API docs for -getting full list of feautes - +:py:class:`dependency_injector.catalogs.DeclarativeCatalog` has several +features that could be useful for some kind of operations on catalog's +providers (please visit API docs for getting full list of feautes - :py:class:`dependency_injector.catalogs.DeclarativeCatalog`): Example: diff --git a/examples/catalogs/declarative.py b/examples/catalogs/declarative.py index 8d22778f..3b4c1d09 100644 --- a/examples/catalogs/declarative.py +++ b/examples/catalogs/declarative.py @@ -1,16 +1,17 @@ """Declarative catalog example.""" -import dependency_injector as di +from dependency_injector import catalogs +from dependency_injector import providers -class Catalog(di.DeclarativeCatalog): +class Catalog(catalogs.DeclarativeCatalog): """Providers catalog.""" - factory1 = di.Factory(object) - """:type: di.Provider -> object""" + factory1 = providers.Factory(object) + """:type: providers.Provider -> object""" - factory2 = di.Factory(object) - """:type: di.Provider -> object""" + factory2 = providers.Factory(object) + """:type: providers.Provider -> object""" # Creating some objects: object1 = Catalog.factory1() diff --git a/examples/catalogs/declarative_api.py b/examples/catalogs/declarative_api.py index 0b055491..8e3b13b0 100644 --- a/examples/catalogs/declarative_api.py +++ b/examples/catalogs/declarative_api.py @@ -1,20 +1,21 @@ """Declarative catalog API example.""" -import dependency_injector as di +from dependency_injector import catalogs +from dependency_injector import providers -class CatalogA(di.DeclarativeCatalog): +class CatalogA(catalogs.DeclarativeCatalog): """Example catalog A.""" - provider1 = di.Factory(object) - """:type: di.Provider -> object""" + provider1 = providers.Factory(object) + """:type: providers.Provider -> object""" class CatalogB(CatalogA): """Example catalog B.""" - provider2 = di.Singleton(object) - """:type: di.Provider -> object""" + provider2 = providers.Singleton(object) + """:type: providers.Provider -> object""" # Making some asserts for `providers` attribute: @@ -29,7 +30,3 @@ assert CatalogB.cls_providers == dict(provider2=CatalogB.provider2) # Making some asserts for `inherited_providers` attribute: assert CatalogA.inherited_providers == dict() assert CatalogB.inherited_providers == dict(provider1=CatalogA.provider1) - -# Making some asserts for `filter()` method: -assert CatalogB.filter(di.Factory) == dict(provider1=CatalogA.provider1) -assert CatalogB.filter(di.Singleton) == dict(provider2=CatalogB.provider2)